org.gradle.api.tasks.incremental

## Interface IncrementalTaskInputs

-     @Incubating
      @NonExtensible
      public interface IncrementalTaskInputs

  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 `outOfDate(org.gradle.api.Action<? super org.gradle.api.tasks.incremental.InputFileDetails>)`. 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:
  - `outOfDate(org.gradle.api.Action<? super org.gradle.api.tasks.incremental.InputFileDetails>)` and `removed(org.gradle.api.Action<? super org.gradle.api.tasks.incremental.InputFileDetails>)` can each only be executed a single time per `IncrementalTaskInputs` instance.
  - `outOfDate(org.gradle.api.Action<? super org.gradle.api.tasks.incremental.InputFileDetails>)` must be executed before `removed(org.gradle.api.Action<? super org.gradle.api.tasks.incremental.InputFileDetails>)` is called.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `isIncremental()` Indicates if it was possible for Gradle to determine which exactly which input files were out of date compared to a previous execution.
    `void` | `outOfDate(Action<? super InputFileDetails> outOfDateAction)` Executes the action for all of the input files that are out-of-date since the previous task execution.
    `void` | `removed(Action<? super InputFileDetails> removedAction)` Executes the action for all of the input files that were removed since the previous task execution.

- - ### Method Detail

    - #### isIncremental

          boolean isIncremental()

      Indicates if it was possible for Gradle to determine which exactly which 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 `outOfDate(org.gradle.api.Action<? super org.gradle.api.tasks.incremental.InputFileDetails>)`.
      - Any input files that has been removed since previous execution will be reported to `removed(org.gradle.api.Action<? super org.gradle.api.tasks.incremental.InputFileDetails>)`.

      When `false`:

      - Every input file will be considered to be 'out-of-date' and will be reported to `outOfDate(org.gradle.api.Action<? super org.gradle.api.tasks.incremental.InputFileDetails>)`.
      - No input files will be reported to `removed(org.gradle.api.Action<? super org.gradle.api.tasks.incremental.InputFileDetails>)`.

    - #### outOfDate

          void outOfDate(Action<? super InputFileDetails> outOfDateAction)

      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 `isIncremental()` == `true`, the action will be executed for any added or modified input file.
      - When `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.

      Throws:
        `IllegalStateException` - on second and subsequent invocations.

    - #### removed

          void removed(Action<? super InputFileDetails> removedAction)

      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 `isIncremental()` == `true`, the action will be executed for any removed input file.
      - When `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 `outOfDate(org.gradle.api.Action<? super org.gradle.api.tasks.incremental.InputFileDetails>)` has been called.

      Throws:
        `IllegalStateException` - if invoked prior to `outOfDate(org.gradle.api.Action<? super org.gradle.api.tasks.incremental.InputFileDetails>)`, or if invoked more than once.