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

@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.

You can create a Property instance using ObjectFactory.property(Class). 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

Method Summary

Modifier and Type	Method	Description
Property<T>	convention(Provider<? extends T> provider)	Specifies the provider to be used to query the convention (default value) for this property.
Property<T>	convention(T value)	Specifies the value to use as the convention (default value) for this property.
void	finalizeValue()	Disallows further changes to the value of this property.
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.
void	set(T value)	Sets the value of the property to the given value, 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(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>	value(T value)	Sets the value of the property to the given value, 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, forUseAtConfigurationTime, 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