Package org.gradle.api.tasks

# Interface TaskOutputs

public interface TaskOutputs

A `TaskOutputs` represents the outputs of a task.

You can obtain a `TaskOutputs` instance using `Task.getOutputs()`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `cacheIf(String cachingEnabledReason, Spec<? super Task> spec)`
  Cache the results of the task only if the given spec is satisfied.
  `void`
  `cacheIf(Spec<? super Task> spec)`
  Cache the results of the task only if the given spec is satisfied.
  `TaskOutputFilePropertyBuilder`
  `dir(Object path)`
  Registers an output directory for this task.
  `TaskOutputFilePropertyBuilder`
  `dirs(@Nullable Object... paths)`
  Registers some output directories for this task.
  `void`
  `doNotCacheIf(String cachingDisabledReason, Spec<? super Task> spec)`
  Disable caching the results of the task if the given spec is satisfied.
  `TaskOutputFilePropertyBuilder`
  `file(Object path)`
  Registers some output file for this task.
  `TaskOutputFilePropertyBuilder`
  `files(@Nullable Object... paths)`
  Registers some output files for this task.
  `FileCollection`
  `getFiles()`
  Returns the output files of this task.
  `boolean`
  `getHasOutput()`
  Returns true if this task has declared any outputs.
  `void`
  `upToDateWhen(Closure upToDateClosure)`
  Adds a predicate to determine whether previous outputs of this task can be reused.
  `void`
  `upToDateWhen(Spec<? super Task> upToDateSpec)`
  Adds a predicate to determine whether previous outputs of this task can be reused.

- ## Method Details

  - ### upToDateWhen

    void upToDateWhen(Closure upToDateClosure)

    Adds a predicate to determine whether previous outputs of this task can be reused. The given closure is executed at task execution time. The closure is passed the task as a parameter. If the closure returns false, previous outputs of this task cannot be reused and the task will be executed. That means the task is out-of-date and no outputs will be loaded from the build cache.

    You can add multiple such predicates. The task outputs cannot be reused when any predicate returns false.

    Parameters:
      `upToDateClosure` - The closure to use to determine whether the task outputs are up-to-date.

  - ### upToDateWhen

    void upToDateWhen(Spec<? super Task> upToDateSpec)

    Adds a predicate to determine whether previous outputs of this task can be reused. The given spec is evaluated at task execution time. If the spec returns false, previous outputs of this task cannot be reused and the task will be executed. That means the task is out-of-date and no outputs will be loaded from the build cache.

    You can add multiple such predicates. The task outputs cannot be reused when any predicate returns false.

    Parameters:
      `upToDateSpec` - The spec to use to determine whether the task outputs are up-to-date.

  - ### cacheIf

    void cacheIf(Spec<? super Task> spec)

    Cache the results of the task only if the given spec is satisfied. If the spec is not satisfied, the results of the task will not be cached.

    You may add multiple such predicates. The results of the task are not cached if any of the predicates return `false`, or if any of the predicates passed to `doNotCacheIf(String, Spec)` returns `true`. If `cacheIf()` is not specified, the task will not be cached unless the @`CacheableTask` annotation is present on the task type.

    Consider using `cacheIf(String, Spec)` instead for also providing a reason for enabling caching.

    Parameters:
      `spec` - specifies if the results of the task should be cached.
    Since:
      3.0

  - ### cacheIf

    void cacheIf(String cachingEnabledReason, Spec<? super Task> spec)

    Cache the results of the task only if the given spec is satisfied. If the spec is not satisfied, the results of the task will not be cached.

    You may add multiple such predicates. The results of the task are not cached if any of the predicates return `false`, or if any of the predicates passed to `doNotCacheIf(String, Spec)` returns `true`. If `cacheIf()` is not specified, the task will not be cached unless the @`CacheableTask` annotation is present on the task type.

    Parameters:
      `cachingEnabledReason` - the reason why caching would be enabled by the spec.
      `spec` - specifies if the results of the task should be cached.
    Since:
      3.4

  - ### doNotCacheIf

    void doNotCacheIf(String cachingDisabledReason, Spec<? super Task> spec)

    Disable caching the results of the task if the given spec is satisfied. The spec will be evaluated at task execution time, not during configuration.

    As opposed to `cacheIf(String, Spec)`, this method never enables caching for a task, it can only be used to disable caching.

    You may add multiple such predicates. The results of the task are not cached if any of the predicates return `true`, or if any of the predicates passed to `cacheIf(String, Spec)` returns `false`.

    Parameters:
      `cachingDisabledReason` - the reason why caching would be disabled by the spec.
      `spec` - specifies if the results of the task should not be cached.
    Since:
      3.4

  - ### getHasOutput

    boolean getHasOutput()
    Returns true if this task has declared any outputs. Note that a task may be able to produce output files and still have an empty set of output files.
    Returns:
      true if this task has declared any outputs, otherwise false.

  - ### getFiles

    FileCollection getFiles()
    Returns the output files of this task.
    Returns:
      The output files. Returns an empty collection if this task has no output files.

  - ### files

    TaskOutputFilePropertyBuilder files(@Nullable Object... paths)
    Registers some output files for this task.

    When the given `paths` is a `Map`, then each output file will be associated with an identity. The keys of the map must be non-empty strings. The values of the map will be evaluated to individual files as per `Project.file(Object)`.

    Otherwise the given files will be evaluated as per `Project.files(Object...)`.

    Parameters:
      `paths` - The output files.
    See Also:
      - `CacheableTask`

  - ### dirs

    TaskOutputFilePropertyBuilder dirs(@Nullable Object... paths)
    Registers some output directories for this task.

    When the given `paths` is a `Map`, then each output directory will be associated with an identity. The keys of the map must be non-empty strings. The values of the map will be evaluated to individual directories as per `Project.file(Object)`.

    Otherwise the given directories will be evaluated as per `Project.files(Object...)`.

    Parameters:
      `paths` - The output files.
    Since:
      3.3
    See Also:
      - `CacheableTask`

  - ### file

    TaskOutputFilePropertyBuilder file(Object path)
    Registers some output file for this task.
    Parameters:
      `path` - The output file. The given path is evaluated as per `Project.file(Object)`.
    Returns:
      a property builder to further configure this property.

  - ### dir

    TaskOutputFilePropertyBuilder dir(Object path)
    Registers an output directory for this task.
    Parameters:
      `path` - The output directory. The given path is evaluated as per `Project.file(Object)`.
    Returns:
      a property builder to further configure this property.