Writing Custom Task Classes

To use a task class in a build script, you need to add the class to the build script’s classpath. To do this, you use a buildscript { } block, as described in the section called “External dependencies for the build script”. The following example shows how you might do this when the JAR containing the task class has been published to a local repository:

buildscript {
    repositories {
        maven {
            url uri('../repo')
        }
    }
    dependencies {
        classpath group: 'org.gradle', name: 'customPlugin',
                  version: '1.0-SNAPSHOT'
    }
}

task greeting(type: org.gradle.GreetingTask) {
    greeting = 'howdy!'
}

You can use the ProjectBuilder class to create Project instances to use when you test your task class.

class GreetingTaskTest {
    @Test
    public void canAddTaskToProject() {
        Project project = ProjectBuilder.builder().build()
        def task = project.task('greeting', type: GreetingTask)
        assertTrue(task instanceof GreetingTask)
    }
}

For a task to process inputs incrementally, that task must contain an incremental task action. This is a task action method that contains a single IncrementalTaskInputs parameter, which indicates to Gradle that the action will process the changed inputs only.

The incremental task action may supply an IncrementalTaskInputs.outOfDate(org.gradle.api.Action) action for processing any input file that is out-of-date, and a IncrementalTaskInputs.removed(org.gradle.api.Action) action that executes for any input file that has been removed since the previous execution.

class IncrementalReverseTask extends DefaultTask {
    @InputDirectory
    def File inputDir

    @OutputDirectory
    def File outputDir

    @Input
    def inputProperty

    @TaskAction
    void execute(IncrementalTaskInputs inputs) {
        println inputs.incremental ? 'CHANGED inputs considered out of date'
                                   : 'ALL inputs considered out of date'
        if (!inputs.incremental)
            project.delete(outputDir.listFiles())

        inputs.outOfDate { change ->
            println "out of date: ${change.file.name}"
            def targetFile = new File(outputDir, change.file.name)
            targetFile.text = change.file.text.reverse()
        }

        inputs.removed { change ->
            println "removed: ${change.file.name}"
            def targetFile = new File(outputDir, change.file.name)
            targetFile.delete()
        }
    }
}

If for some reason the task is not run incremental, e.g. by running with --rerun-tasks, only the outOfDate action is executed, even if there were deleted input files. You should consider handling this case at the beginning, as is done in the example above.

For a simple transformer task like this, the task action simply needs to generate output files for any out-of-date inputs, and delete output files for any removed inputs.

A task may only contain a single incremental task action.

When Gradle has history of a previous task execution, and the only changes to the task execution context since that execution are to input files, then Gradle is able to determine which input files need to be reprocessed by the task. In this case, the IncrementalTaskInputs.outOfDate(org.gradle.api.Action) action will be executed for any input file that was added or modified, and the IncrementalTaskInputs.removed(org.gradle.api.Action) action will be executed for any removed input file.

However, there are many cases where Gradle is unable to determine which input files need to be reprocessed. Examples include:

In any of these cases, Gradle will consider all of the input files to be outOfDate. The IncrementalTaskInputs.outOfDate(org.gradle.api.Action) action will be executed for every input file, and the IncrementalTaskInputs.removed(org.gradle.api.Action) action will not be executed at all.

You can check if Gradle was able to determine the incremental changes to input files with IncrementalTaskInputs.isIncremental().

Given the incremental task implementation above, we can explore the various change scenarios by example. Note that the various mutation tasks ('updateInputs', 'removeInput', etc) are only present for demonstration purposes: these would not normally be part of your build script.

First, consider the IncrementalReverseTask executed against a set of inputs for the first time. In this case, all inputs will be considered “out of date”:

task incrementalReverse(type: IncrementalReverseTask) {
    inputDir = file('inputs')
    outputDir = file("$buildDir/outputs")
    inputProperty = project.properties['taskInputProperty'] ?: 'original'
}

incrementalTask/
  build.gradle
  inputs/
    1.txt
    2.txt
    3.txt

> gradle -q incrementalReverse
ALL inputs considered out of date
out of date: 1.txt
out of date: 2.txt
out of date: 3.txt

Naturally when the task is executed again with no changes, then the entire task is up to date and no files are reported to the task action:

> gradle -q incrementalReverse

When an input file is modified in some way or a new input file is added, then re-executing the task results in those files being reported to IncrementalTaskInputs.outOfDate(org.gradle.api.Action):

task updateInputs() {
    doLast {
        file('inputs/1.txt').text = 'Changed content for existing file 1.'
        file('inputs/4.txt').text = 'Content for new file 4.'
    }
}

> gradle -q updateInputs incrementalReverse
CHANGED inputs considered out of date
out of date: 1.txt
out of date: 4.txt

When an existing input file is removed, then re-executing the task results in that file being reported to IncrementalTaskInputs.removed(org.gradle.api.Action):

task removeInput() {
    doLast {
        file('inputs/3.txt').delete()
    }
}

> gradle -q removeInput incrementalReverse
CHANGED inputs considered out of date
removed: 3.txt

When an output file is deleted (or modified), then Gradle is unable to determine which input files are out of date. In this case, all input files are reported to the IncrementalTaskInputs.outOfDate(org.gradle.api.Action) action, and no input files are reported to the IncrementalTaskInputs.removed(org.gradle.api.Action) action:

task removeOutput() {
    doLast {
        file("$buildDir/outputs/1.txt").delete()
    }
}

> gradle -q removeOutput incrementalReverse
ALL inputs considered out of date
out of date: 1.txt
out of date: 2.txt
out of date: 3.txt

When a task input property is modified, Gradle is unable to determine how this property impacted the task outputs, so all input files are assumed to be out of date. So similar to the changed output file example, all input files are reported to the IncrementalTaskInputs.outOfDate(org.gradle.api.Action) action, and no input files are reported to the IncrementalTaskInputs.removed(org.gradle.api.Action) action:

> gradle -q -PtaskInputProperty=changed incrementalReverse
ALL inputs considered out of date
out of date: 1.txt
out of date: 2.txt
out of date: 3.txt

Using Gradle’s IncrementalTaskInputs is not the only way to create tasks that only works on changes since the last execution. Tools like the Kotlin compiler provide incrementality as a built-in feature. The way this is typically implemented is that the tool stores some analysis data about the state of the previous execution in some file. If such state files are relocatable, then they can be declared as outputs of the task. This way when the task’s results are loaded from cache, the next execution can already use the analysis data loaded from cache, too.

However, if the state files are non-relocatable, then they can’t be shared via the build cache. Indeed, when the task is loaded from cache, any such state files must be cleaned up to prevent stale state to confuse the tool during the next execution. Gradle can ensure such stale files are removed if they are declared via task.localState.register() or a property is marked with the @LocalState annotation.

Exposing a new command line option for a task property is straightforward. You just have to annotate the corresponding setter method of a property with Option. An option requires a mandatory identifier. Additionally, you can provide an optional description. A task can expose as many command line options as properties available in the class.

Let’s have a look at an example to illustrate the functionality. The custom task UrlVerify verifies whether a given URL can be resolved by making a HTTP call and checking the response code. The URL to be verified is configurable through the property url. The setter method for the property is annotated with Option.

import org.gradle.api.tasks.options.Option;

public class UrlVerify extends DefaultTask {
    private String url;

    @Option(option = "url", description = "Configures the URL to be verified.")
    public void setUrl(String url) {
        this.url = url;
    }

    @Input
    public String getUrl() {
        return url;
    }

    @TaskAction
    public void verify() {
        getLogger().quiet("Verifying URL '{}'", url);

        // verify URL by making a HTTP call
    }
}

All options declared for a task can be rendered as console output by running the help task and the --task option.

Using an option on the command line has to adhere to the following rules:

Getting back to the previous example, the build script creates a task instance of type UrlVerify and provides a value from the command line through the exposed option.

task verifyUrl(type: UrlVerify)

> gradle -q verifyUrl --url=http://www.google.com/
Verifying URL 'http://www.google.com/'

Gradle limits the set of data types that can be used for declaring command line options. The use on the command line differ per type.

In theory, an option for a property type String or List<String> can accept any arbitrary value. Expected values for such an option can be documented programmatically with the help of the annotation OptionValues. This annotation may be assigned to any method that returns a List of one of the supported data types. In addition, you have to provide the option identifier to indicate the relationship between option and available values.

This example demonstrates the use of multiple options for a single task. The task implementation provides a list of available values for the option output-type.

import org.gradle.api.tasks.options.Option;
import org.gradle.api.tasks.options.OptionValues;

public class UrlProcess extends DefaultTask {
    private String url;
    private OutputType outputType;

    @Option(option = "url", description = "Configures the URL to be write to the output.")
    public void setUrl(String url) {
        this.url = url;
    }

    @Input
    public String getUrl() {
        return url;
    }

    @Option(option = "output-type", description = "Configures the output type.")
    public void setOutputType(OutputType outputType) {
        this.outputType = outputType;
    }

    @OptionValues("output-type")
    public List<OutputType> getAvailableOutputTypes() {
        return new ArrayList<OutputType>(Arrays.asList(OutputType.values()));
    }

    @Input
    public OutputType getOutputType() {
        return outputType;
    }

    @TaskAction
    public void process() {
        getLogger().quiet("Writing out the URL reponse from '{}' to '{}'", url, outputType);

        // retrieve content from URL and write to output
    }

    private static enum OutputType {
        CONSOLE, FILE
    }
}

Command line options using the annotations Option and OptionValues are self-documenting. You will see declared options and their available values reflected in the console output of the help task. The output renders options in alphabetical order.

> gradle -q help --task processUrl
Detailed task information for processUrl

Path
     :processUrl

Type
     UrlProcess (UrlProcess)

Options
     --output-type     Configures the output type.
                       Available values are:
                            CONSOLE
                            FILE

     --url     Configures the URL to be write to the output.

Description
     -

Group
     -

Support for declaring command line options currently comes with a few limitations.

In order to submit work to the Worker API, two things must be provided: an implementation of the unit of work, and a configuration for the unit of work. The implementation is simply a class that extends java.lang.Runnable. This class should have a constructor that is annotated with javax.inject.Inject and accepts parameters that configure the class for a single unit of work. When a unit of work is submitted to the WorkerExecutor, an instance of this class will be created and the parameters configured for the unit of work will be passed to the constructor.

import org.gradle.workers.WorkerExecutor

import javax.inject.Inject

// The implementation of a single unit of work
class ReverseFile implements Runnable {
    File fileToReverse
    File destinationFile

    @Inject
    public ReverseFile(File fileToReverse, File destinationFile) {
        this.fileToReverse = fileToReverse
        this.destinationFile = destinationFile
    }

    @Override
    public void run() {
        destinationFile.text = fileToReverse.text.reverse()
    }
}

The configuration of the worker is represented by a WorkerConfiguration and is set by configuring an instance of this object at the time of submission. However, in order to submit the unit of work, it is necessary to first acquire the WorkerExecutor. To do this, a constructor should be provided that is annotated with javax.inject.Inject and accepts a WorkerExecutor parameter. Gradle will inject the instance of WorkerExecutor at runtime when the task is created.

class ReverseFiles extends SourceTask {
    final WorkerExecutor workerExecutor

    @OutputDirectory
    File outputDir

    // The WorkerExecutor will be injected by Gradle at runtime
    @Inject
    public ReverseFiles(WorkerExecutor workerExecutor) {
        this.workerExecutor = workerExecutor
    }

    @TaskAction
    void reverseFiles() {
        // Create and submit a unit of work for each file
        source.files.each { file ->
            workerExecutor.submit(ReverseFile.class) { WorkerConfiguration config ->
                // Use the minimum level of isolation
                config.isolationMode = IsolationMode.NONE

                // Constructor parameters for the unit of work implementation
                config.params file, project.file("${outputDir}/${file.name}")
            }
        }
    }
}

Note that one element of the WorkerConfiguration is the params property. These are the parameters passed to the constructor of the unit of work implementation for each item of work submitted. Any parameters provided to the unit of work must be java.io.Serializable.

Once all of the work for a task action has been submitted, it is safe to exit the task action. The work will be executed asynchronously and in parallel (up to the setting of max-workers). Of course, any tasks that are dependent on this task (and any subsequent task actions of this task) will not begin executing until all of the asynchronous work completes. However, other independent tasks that have no relationship to this task can begin executing immediately.

If any failures occur while executing the asynchronous work, the task will fail and a WorkerExecutionException will be thrown detailing the failure for each failed work item. This will be treated like any failure during task execution and will prevent any dependent tasks from executing.

In some cases, however, it might be desirable to wait for work to complete before exiting the task action. This is possible using the WorkerExecutor.await() method. As in the case of allowing the work to complete asynchronously, any failures that occur while executing an item of work will be surfaced as a WorkerExecutionException thrown from the WorkerExecutor.await() method.

// Create and submit a unit of work for each file
source.files.each { file ->
    workerExecutor.submit(ReverseFile.class) { config ->
        config.isolationMode = IsolationMode.NONE
        // Constructor parameters for the unit of work implementation
        config.params file, project.file("${outputDir}/${file.name}")
    }
}

// Wait for all asynchronous work to complete before continuing
workerExecutor.await()
logger.lifecycle("Created ${outputDir.listFiles().size()} reversed files in ${project.relativePath(outputDir)}")

Gradle provides three isolation modes that can be configured on a unit of work and are specified using the IsolationMode enum:

When using IsolationMode.PROCESS, gradle will start a long-lived Worker Daemon process that can be reused for future work items.

workerExecutor.submit(ReverseFile.class) { WorkerConfiguration config ->
    // Run this work in an isolated process
    config.isolationMode = IsolationMode.PROCESS

    // Configure the options for the forked process
    config.forkOptions { JavaForkOptions options ->
        options.maxHeapSize = "512m"
        options.systemProperty "org.gradle.sample.showFileSize", "true"
    }

    // Constructor parameters for the unit of work implementation
    config.params file, project.file("${outputDir}/${file.name}")
}

When a unit of work for a Worker Daemon is submitted, Gradle will first look to see if a compatible, idle daemon already exists. If so, it will send the unit of work to the idle daemon, marking it as busy. If not, it will start a new daemon. When evaluating compatibility, Gradle looks at a number of criteria, all of which can be controlled through WorkerConfiguration.forkOptions(org.gradle.api.Action).

Worker daemons will remain running until either the build daemon that started them is stopped, or system memory becomes scarce. When available system memory is low, Gradle will begin stopping worker daemons in an attempt to minimize memory consumption.