第五十七章. 编写自定义任务类

想在一个构建脚本中使用一个任务类，你需要把这个类添加到构建脚本的类路径中。要做到这一点，你要使用在第 59.5 节，“构建脚本的外部依赖”中描述的 buildscript { } 块。下面的示例展示了当包含任务类的JAR文件已经被发布到一个本地仓库时，你可以怎么做。
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 Section 59.5, “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!'
}

当你要测试你的任务类时，你可以使用ProjectBuilder 类来创建 Project 实例去使用你的任务类。
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)
    }
}

对于一个要增量处理输入的任务，它必须包含一个 增量任务操作。这是一个任务操作方法，它包含了一个简单的 IncrementalTaskInputs 参数，该参数提示了Gradle 这个操作将只处理那些更改的输入。
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.

这个增量任务操作可能提供了一个IncrementalTaskInputs.outOfDate() 操作，用于处理所有out-of-date的输入文件，以及一个IncrementalTaskInputs.removed()操作，对任何从前一次执行开始已经被删除的文件执行。
The incremental task action may supply an IncrementalTaskInputs.outOfDate() action for processing any input file that is out-of-date, and a IncrementalTaskInputs.removed() 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"
        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()
        }
    }
}

对于像这样的简单转换任务，任务操作只需要对任何out-of-date的输入生成输出的文件，并对任何已移除的输入删除对应的输出文件。
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.

当Gradle有了前一次任务执行的历史，并且从那一次执行开始任务执行的上下文中只有输入文件有更改，那么Gradle 就能够决定哪些输入文件需要被这个任务重新处理。在这种情况下，IncrementalTaskInputs.outOfDate() 操作会对任何新加入的 或者是 已修改的输入文件执行，并且IncrementalTaskInputs.removed()操作会对任何被移除的输入文件执行。
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() action will be executed for any input file that was added or modified, and the IncrementalTaskInputs.removed() action will be executed for any removed input file.

然而，有许多情况下，Gradle还是无法确定哪些输入文件需要被重新处理。比如包括：
However, there are many cases where Gradle is unable to determine which input files need to be reprocessed. Examples include:

满足以上情况的任何一个，Gradle都会考虑使所有的输入文件为outOfDate。然后会为每一个输入文件执行 IncrementalTaskInputs.outOfDate()操作，并且不再执行IncrementalTaskInputs.removed()操作。
In any of these cases, Gradle will consider all of the input files to be outOfDate. The IncrementalTaskInputs.outOfDate() action will be executed for every input file, and the IncrementalTaskInputs.removed() action will not be executed at all.

你可以通过 IncrementalTaskInputs.isIncremental()检查Gradle是否能够对输入的文件确定增量更改。
You can check if Gradle was able to determine the incremental changes to input files with IncrementalTaskInputs.isIncremental().

给定 上面的增量任务实现，我们可以通过示例探讨中种变化场景。注意不同变化的任务（“updateInputs”，“removeInput”等）都是出于演示目的而存在：它们通常不会在构建脚本中。
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.

首先，考虑到 IncrementalReverseTask第一次针对一组输入执行。在这种情况下，所有的输入都被认为是“out of date”：
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

当然，对于没有任何修改的情况下执行任务时，该任务本身是up to date的，并且不会有文件上报到这个任务操作中：
Naturally when the task is executed again with no changes, then task itself is up to date and no files are reported to the task action:

> gradle -q incrementalReverse

当以某种方式修改了一个输入文件，或者新增了一个输入文件时，重新执行这个任务会使这些文件被上报到IncrementalTaskInputs.outOfDate()：
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():

task updateInputs() << {
    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 that file being reported to IncrementalTaskInputs.removed():

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

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

当输出文件被删除（或更改）时，Gradle是无法确定哪一个输入文件是out of date的。在这种情况下，所有的输入文件都会被报告到 IncrementalTaskInputs.outOfDate()操作中，并且没有文件会被上报到 IncrementalTaskInputs.removed() 操作：
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() action, and no input files are reported to the IncrementalTaskInputs.removed() action:

task removeOutput() << {
    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

当一个任务的输入属性被修改时，Gradle 无法确定这个属性是如何影响到这个任务的输出的，因此所有的输入文件都会被认为是out of date的。所以类似于更改输出文件的例子，所有的输入文件都会被报告到 IncrementalTaskInputs.outOfDate()操作中，并且没有文件会被上报到 IncrementalTaskInputs.removed() 操作：
When a task input property modified, Gradle is not able 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() action, and no input files are reported to the IncrementalTaskInputs.removed() 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