Package org.gradle.api.provider

# Interface Property<T>

Type Parameters:
  `T` - Type of value represented by the property

All Superinterfaces:
  `HasConfigurableValue`, `Provider<T>`, `SupportsConvention`

All Known Subinterfaces:
  `DirectoryProperty`, `FileSystemLocationProperty<T>`, `RegularFileProperty`

@ManagedType @SupportsKotlinAssignmentOverloading public interface Property<T> extends Provider<T>, HasConfigurableValue, SupportsConvention
A container object that represents a configurable value of a specific type. A `Property` is also a `Provider` and can be used in the same way as a `Provider`. A property's value can be accessed using the methods of `Provider` such as `get()`. The value can be modified by using the methods `set(Object)` and `set(Provider)`, or their fluid API counterparts `value(Object)` and `value(Provider)`.

A property may represent a task output. Such a property carries information about the task producing its value. When this property is attached to an input of another task, Gradle will automatically determine the task dependencies based on this connection.

There are also several specialized subtypes of this interface that can be created using various other factory methods.

Instances of this interface are not thread-safe for reading and writing. It is not safe to share the same Property instance between different projects.

Note: This interface is not intended for implementation by build script or plugin authors.

Since:
  4.3
See Also:
  - `Create an instance of this as a managed property (preferred).`
  - `Create an instance of this manually.`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Property<T>`
  `convention(@Nullable T value)`
  Specifies the value to use as the convention (default value) for this property.
  `Property<T>`
  `convention(Provider<? extends T> provider)`
  Specifies the provider to be used to query the convention (default value) for this property.
  `void`
  `finalizeValue()`
  Disallows further changes to the value of this property.
  `void`
  `set(@Nullable T value)`
  Sets the value of the property to the given value, replacing whatever value the property already had.
  `void`
  `set(Provider<? extends T> provider)`
  Sets the property to have the same value as the given provider, replacing whatever value the property already had.
  `Property<T>`
  `unset()`
  Unsets this object's explicit value, allowing the convention to be selected when evaluating this object's value.
  `Property<T>`
  `unsetConvention()`
  Unsets this object's convention value.
  `Property<T>`
  `value(@Nullable T value)`
  Sets the value of the property to the given value, replacing whatever value the property already had.
  `Property<T>`
  `value(Provider<? extends T> provider)`
  Sets the property to have the same value as the given provider, replacing whatever value the property already had.

  ### Methods inherited from interface org.gradle.api.provider.HasConfigurableValue

  `disallowChanges, disallowUnsafeRead, finalizeValueOnRead`

  ### Methods inherited from interface org.gradle.api.provider.Provider

  `filter, flatMap, get, getOrElse, getOrNull, isPresent, map, orElse, orElse, zip`

- ## Method Details

  - ### set

    void set(@Nullable T value)
    Sets the value of the property to the given value, replacing whatever value the property already had.

    This method can also be used to discard the value of the property, by passing it `null`. When the value is discarded (or has never been set in the first place), the convention (default value) for this property, if specified, will be used to provide the value instead.

    Parameters:
      `value` - The value, can be null.

  - ### set

    void set(Provider<? extends T> provider)
    Sets the property to have the same value as the given provider, replacing whatever value the property already had. This property will track the value of the provider and query its value each time the value of the property is queried. When the provider has no value, this property will also have no value.

    This method can NOT be used to discard the value of the property. Specifying a `null` provider will result in an `IllegalArgumentException` being thrown. When the provider has no value, this property will also have no value - regardless of whether or not a convention has been set.

    When the given provider represents a task output, this property will also carry the task dependency information from the provider.

    Parameters:
      `provider` - The provider of the property's value, can't be null.

  - ### value

    Property<T> value(@Nullable T value)
    Sets the value of the property to the given value, replacing whatever value the property already had. This is the same as `set(Object)` but returns this property to allow method chaining.

    This method can also be used to discard the value of the property, by passing it `null`. When the value is discarded (or has never been set in the first place), the convention (default value) for this property, if specified, will be used to provide the value instead.

    Parameters:
      `value` - The value, can be null.
    Returns:
      this
    Since:
      5.0

  - ### value

    Property<T> value(Provider<? extends T> provider)
    Sets the property to have the same value as the given provider, replacing whatever value the property already had. This property will track the value of the provider and query its value each time the value of the property is queried. When the provider has no value, this property will also have no value. This is the same as `set(Provider)` but returns this property to allow method chaining.

    This method can NOT be used to discard the value of the property. Specifying a `null` provider will result in an `IllegalArgumentException` being thrown. When the provider has no value, this property will also have no value - regardless of whether or not a convention has been set.

    When the given provider represents a task output, this property will also carry the task dependency information from the provider.

    Parameters:
      `provider` - The provider whose value to use.
    Returns:
      this
    Since:
      5.6

  - ### unset

    Property<T> unset()
    Unsets this object's explicit value, allowing the convention to be selected when evaluating this object's value.

    This is similar to calling `value(Object)` with a `null` argument.

    Specified by:
      `unset` in interface `SupportsConvention`

  - ### convention

    Property<T> convention(@Nullable T value)
    Specifies the value to use as the convention (default value) for this property. If the convention is set and no explicit value or value provider has been specified, then the convention will be returned as the value of the property (when queried).

    This method can be used to specify that the property does not have a default value, by passing it `null`.

    Parameters:
      `value` - The convention value, or `null` if the property should have no default value.
    Returns:
      this
    Since:
      5.1

  - ### convention

    Property<T> convention(Provider<? extends T> provider)
    Specifies the provider to be used to query the convention (default value) for this property. If a convention provider has been set and no explicit value or value provider has been specified, then the convention provider's value will be returned as the value of the property (when queried).

    The property's convention tracks the convention provider. Whenever the convention's actual value is needed, the convention provider will be queried anew.

    This method can't be used to specify that a property does not have a default value. Passing in a `null` provider will result in an `IllegalArgumentException` being thrown. When the provider doesn't have a value, then the property will behave as if it wouldn't have a convention specified.

    Parameters:
      `provider` - The provider of the property's convention value, can't be null.
    Returns:
      this
    Since:
      5.1

  - ### unsetConvention

    Property<T> unsetConvention()
    Unsets this object's convention value.

    This is similar to calling `convention(Object)` with a `null` argument.

    Specified by:
      `unsetConvention` in interface `SupportsConvention`

  - ### finalizeValue

    void finalizeValue()
    Disallows further changes to the value of this property. Calls to methods that change the value of this property, such as `set(Object)`, `set(Provider)`, `value(Object)` and `value(Provider)` will fail, by throwing an `IllegalStateException`.

    When this property's value is specified via a `Provider`, calling `finalizeValue()` will trigger the querying of the provider and the obtained value will be set as the final value of the property. The value of the provider will not be tracked further.

    Note that although the value of the property will not change, the value itself may be a mutable object. Calling this method does not guarantee that the value will become immutable.

    Specified by:
      `finalizeValue` in interface `HasConfigurableValue`
    Since:
      5.0