IncrementalTaskInputs - Gradle DSL Version 3.5

# IncrementalTaskInputs

API Documentation: | `IncrementalTaskInputs`

Note: This class is incubating and may change in a future version of Gradle.

Provides access to any input files that need to be processed by an incremental task.

An incremental task action is one that accepts a single `IncrementalTaskInputs` parameter. The task can then provide an action to execute for all input files that are out of date with respect to the previous execution of the task, and a separate action for all input files that have been removed since the previous execution.

    class IncrementalReverseTask extends DefaultTask {
         @InputDirectory
         def File inputDir

         @OutputDirectory
         def File outputDir

         @TaskAction
         void execute(IncrementalTaskInputs inputs) {
             if (!inputs.incremental)
                 project.delete(outputDir.listFiles())

             inputs.outOfDate { change ->
                 def targetFile = project.file("$outputDir/${change.file.name}")
                 targetFile.text = change.file.text.reverse()
             }

             inputs.removed { change ->
                 def targetFile = project.file("$outputDir/${change.file.name}")
                 if (targetFile.exists()) {
                     targetFile.delete()
                 }
             }
         }
     }

In the case where Gradle is unable to determine which input files need to be reprocessed, then all of the input files will be reported as `IncrementalTaskInputs.outOfDate(org.gradle.api.Action)`. Cases where this occurs include:

- There is no history available from a previous execution.
- An `TaskOutputs.upToDateWhen(groovy.lang.Closure)` criteria added to the task returns `false`.
- An `Input` property has changed since the previous execution.
- One or more output files have changed since the previous execution.

Note that this is a stateful API:

- `IncrementalTaskInputs.outOfDate(org.gradle.api.Action)` and `IncrementalTaskInputs.removed(org.gradle.api.Action)` can each only be executed a single time per `IncrementalTaskInputs` instance.
- `IncrementalTaskInputs.outOfDate(org.gradle.api.Action)` must be executed before `IncrementalTaskInputs.removed(org.gradle.api.Action)` is called.

### Properties

Property | Description
`incremental` | Incubating Indicates if it was possible for Gradle to determine which exactly input files were out of date compared to a previous execution. This is not possible in the case of no previous execution, changed input properties, output files, etc.

### Methods

Method | Description
`outOfDate(outOfDateAction)` | Incubating Executes the action for all of the input files that are out-of-date since the previous task execution. The action may also be supplied as a `Closure`.
`removed(removedAction)` | Incubating Executes the action for all of the input files that were removed since the previous task execution. The action may also be supplied as a `Closure`.

### Script blocks

No script blocks

### Property details

#### `boolean` `incremental` (read-only)

Note: This property is incubating and may change in a future version of Gradle.

Indicates if it was possible for Gradle to determine which exactly input files were out of date compared to a previous execution. This is not possible in the case of no previous execution, changed input properties, output files, etc.

When `true`:

- Any input file that has been added or modified since previous execution will be considered 'out-of-date' and reported to `IncrementalTaskInputs.outOfDate(org.gradle.api.Action)`.
- Any input files that has been removed since previous execution will be reported to `IncrementalTaskInputs.removed(org.gradle.api.Action)`.

When `false`:

- Every input file will be considered to be 'out-of-date' and will be reported to `IncrementalTaskInputs.outOfDate(org.gradle.api.Action)`.
- No input files will be reported to `IncrementalTaskInputs.removed(org.gradle.api.Action)`.

### Method details

#### `void` `outOfDate`(``Action`<? super `InputFileDetails`>` outOfDateAction)

Note: This method is incubating and may change in a future version of Gradle.

Executes the action for all of the input files that are out-of-date since the previous task execution. The action may also be supplied as a `Closure`.

- When `IncrementalTaskInputs.isIncremental()` == `true`, the action will be executed for any added or modified input file.
- When `IncrementalTaskInputs.isIncremental()` == `false`, the action will be executed for every input file for the task.

This method may only be called a single time for a single `IncrementalTaskInputs` instance.

#### `void` `removed`(``Action`<? super `InputFileDetails`>` removedAction)

Note: This method is incubating and may change in a future version of Gradle.

Executes the action for all of the input files that were removed since the previous task execution. The action may also be supplied as a `Closure`.

- When `IncrementalTaskInputs.isIncremental()` == `true`, the action will be executed for any removed input file.
- When `IncrementalTaskInputs.isIncremental()` == `false`, the action will not be executed.

This method may only be called a single time for a single `IncrementalTaskInputs` instance.

This method may only be called after `IncrementalTaskInputs.outOfDate(org.gradle.api.Action)` has been called.