Package org.gradle.api.provider

## Interface ValueSource<T,​P extends ValueSourceParameters>

- Type Parameters:
    `T` - The type of value obtained from this source.
    `P` - The source specific parameter type.

      @Incubating
      public interface ValueSource<T,​P extends ValueSourceParameters>

  Represents an external source of information used by a Gradle build. Examples of external sources include client environment variables, system properties, configuration files, shell commands, network services, among others.

  Representing external sources as `ValueSource`s allows Gradle to transparently manage the work graph cacheas values obtained from those sources change. For example, a build might run a different set of tasks depending on whether the `CI` environment variable is set or not.

  To integrate a new type of value source, create an abstract subclass of this interface and use `ProviderFactory.of(Class, Action)` to get a provider to a configured source. The returned `Provider` can be passed to tasks or queried by build logic during the configuration phase, in which case the source would be automatically considered as an input to the work graph cache.

  A value source implementation will most likely take parameters. To do this create a subtype of `ValueSourceParameters` and declare this type as the type parameter to the value source implementation.

  A value source implementation doesn't have to be thread-safe, as the single call to `obtain()` is synchronized.

  Since:
    6.1
  See Also:
    `ProviderFactory.environmentVariable(String)`, `ProviderFactory.systemProperty(String)`, `ProviderFactory.fileContents(RegularFile)`, `ProviderFactory.of(Class, Action)`, Instant Execution

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `P` | `getParameters()` | The object provided by `ValueSourceSpec.getParameters()` when creating a provider from the value source.
    `T` | `obtain()` | Obtains the value from the source.

- - ### Method Detail

    - #### getParameters

          @Inject
          P getParameters()

      The object provided by `ValueSourceSpec.getParameters()` when creating a provider from the value source.

      Do not implement this method in your subclass. Gradle provides the implementation when creating a provider from the value source via `ProviderFactory.of(Class, Action)`.

    - #### obtain

          @Nullable
          T obtain()

      Obtains the value from the source. The returned value must be effectively immutable.

      This method must be implemented in the subclass.

      This method is only called if the provider value is requested and only once in that case.

      Returns:
        the value obtained or `null` if the value is not present.