InputChanges (Gradle API 8.11)

Package org.gradle.work

## Interface InputChanges

-     public interface InputChanges

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

  An incremental work action is one that accepts a single `InputChanges` parameter. The work action can then query what changed for an input parameter since the last execution to only process the changes. The following example shows a task which reverses the text in each of its input files. It demonstrates how to use `InputChanges` to only process the changed files.

       abstract class IncrementalReverseTask extends DefaultTask {
           @Incremental
           @InputDirectory
           abstract DirectoryProperty getInputDir()

           @OutputDirectory
           abstract DirectoryProperty getOutputDir()

           @TaskAction
           void execute(InputChanges inputChanges) {
               inputChanges.getFileChanges(inputDir).each { change ->
                   if (change.fileType == FileType.DIRECTORY) return

                   def targetFile = outputDir.file(change.normalizedPath).get().asFile
                   if (change.changeType == ChangeType.REMOVED) {
                       targetFile.delete()
                   } else {
                       targetFile.text = change.file.text.reverse()
                   }
               }
           }
       }

  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 `ChangeType.ADDED`. When such a full rebuild happens, the output files of the work are removed prior to executing the work action. Cases where this occurs include:

  - There is no history available from a previous execution.
  - A non-file input parameter has changed since the previous execution.
  - One or more output files have changed since the previous execution.
  Since:
    5.4

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.lang.Iterable<FileChange>` | `getFileChanges​(FileCollection parameter)` | Changes for a parameter.
    `java.lang.Iterable<FileChange>` | `getFileChanges​(Provider<? extends FileSystemLocation> parameter)` | Changes for a parameter.
    `boolean` | `isIncremental()` | Indicates if it was possible for Gradle to determine which input files were out of date compared to a previous execution.

- - ### Method Detail

    - #### isIncremental

          boolean isIncremental()

      Indicates if it was possible for Gradle to determine which input files were out of date compared to a previous execution. Incremental inputs are unavailable when history is unavailable (i.e. this piece of work has never been executed before), or if there are changes to non-file input properties, or output files.

      When `true`:

      - `getFileChanges(FileCollection)` and `getFileChanges(Provider)` report changes to the input files compared to the previous execution.

      When `false`:

      - Every input file is reported via `getFileChanges(FileCollection)` and `getFileChanges(Provider)` as if it was `ChangeType.ADDED`.

    - #### getFileChanges

          java.lang.Iterable<FileChange> getFileChanges​(FileCollection parameter)

      Changes for a parameter.

      When `isIncremental()` is `false`, then all elements of the parameter are returned as `ChangeType.ADDED`.

      Only input file properties annotated with @`Incremental` or @`SkipWhenEmpty` can be queried for changes.

      Note that for inputs with `PathSensitivity.NONE`, instead of a `ChangeType.MODIFIED` event, file modifications can be reported as a pair of an `ChangeType.ADDED` and a `ChangeType.REMOVED` event.

      Parameters:
        `parameter` - The value of the parameter to query.

    - #### getFileChanges

          java.lang.Iterable<FileChange> getFileChanges​(Provider<? extends FileSystemLocation> parameter)

      Changes for a parameter.

      When `isIncremental()` is `false`, then all elements of the parameter are returned as `ChangeType.ADDED`.

      This method allows querying properties of type `RegularFileProperty` and `DirectoryProperty` for changes. These two types are typically used for @`InputFile` and @`InputDirectory` properties.

      Only input file properties annotated with @`Incremental` or @`SkipWhenEmpty` can be queried for changes.

      Note that for inputs with `PathSensitivity.NONE`, instead of a `ChangeType.MODIFIED` event, file modifications can be reported as a pair of an `ChangeType.ADDED` and a `ChangeType.REMOVED` event.

      Parameters:
        `parameter` - The value of the parameter to query.