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:

  • 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