flatMap

Returns a new Provider from the value of this provider transformed using the given function.

While very similar in functionality to the regular map operation, this method offers a convenient way of connecting together task inputs and outputs. (For a deeper understanding of the topic see the Lazy Configuration section of the Gradle manual.)

Task inputs and outputs often take the form of providers or properties, the latter being a special case of provider whose value can be changed at will. An example of using flatMap for connecting such properties would be following:

class Producer extends DefaultTask {
    @OutputFile
    abstract RegularFileProperty getOutputFile()

    //irrelevant details omitted
}

class Consumer extends DefaultTask {
    @InputFile
    abstract RegularFileProperty getInputFile()

    //irrelevant details omitted
}

def producer = tasks.register("producer", Producer)
def consumer = tasks.register("consumer", Consumer)

consumer.configure {
    inputFile = producer.flatMap { it.outputFile }
}

An added benefit of connecting input and output properties like this is that Gradle can automatically detect task dependencies based on such connections. To make this happen at code level, any task details associated with this provider (the one on which flatMap is being called) are ignored. The new provider will use whatever task details are associated with the return value of the transformation.

The new provider returned by flatMap will be live, so that each time it is queried, it queries this provider and applies the transformation to the result. Whenever this provider has no value, the new provider will also have no value and the transformation will not be called.

Parameters