public interface ExtraPropertiesExtension
Extra properties extensions allow new properties to be added to existing domain objects. They act like maps,
allowing the storage of arbitrary key/value pairs. All ExtensionAware Gradle domain objects intrinsically have an extension
named “"ext"” of this type.
An important feature of extra properties extensions is that all of its properties are exposed for reading and writing via the ExtensionAware
object that owns the extension.
project.ext.set("myProp", "myValue")
assert project.myProp == "myValue"
project.myProp = "anotherValue"
assert project.myProp == "anotherValue"
assert project.ext.get("myProp") == "anotherValue"
Extra properties extension objects support Groovy property syntax. That is, a property can be read via extension.«name» and set via
extension.«name» = "value". Wherever possible, the Groovy property syntax should be preferred over the
get(String) and set(String, Object) methods.
project.ext {
myprop = "a"
}
assert project.myprop == "a"
assert project.ext.myprop == "a"
project.myprop = "b"
assert project.myprop == "b"
assert project.ext.myprop == "b"
You can also use the Groovy accessor syntax to get and set properties on an extra properties extension.
project.ext["otherProp"] = "a" assert project.otherProp == "a" assert project.ext["otherProp"] == "a"The exception that is thrown when an attempt is made to get the value of a property that does not exist is different depending on whether the Groovy syntax is used or not. If Groovy property syntax is used, the Groovy
MissingPropertyException will be thrown.
When the get(String) method is used, an ExtraPropertiesExtension.UnknownPropertyException will be thrown.
This mechanism replaces the ability to create new properties on domain objects directly. In versions of Gradle prior to 1.0-milestone-9,
new properties could be added to objects by assignment:
project.myProp = "myValue"This functionality has been deprecated (a deprecation warning message will be issued when this is attempted). Future versions of Gradle will remove this functionality completely, resulting in an exception being thrown.
| Modifier and Type | Interface and Description |
|---|---|
static class |
ExtraPropertiesExtension.UnknownPropertyException
The exception that will be thrown when an attempt is made to read a property that is not set.
|
| Modifier and Type | Field and Description |
|---|---|
static String |
EXTENSION_NAME
The name of this extension in all
ExtensnionContainers, "ext". |
| Modifier and Type | Method and Description |
|---|---|
Object |
get(String name)
Returns the value for the registered property with the given name.
|
Map<String,Object> |
getProperties()
Returns all of the registered properties and their current values as a map.
|
boolean |
has(String name)
Returns whether or not the extension has a property registered via the given name.
|
void |
set(String name,
Object value)
Updates the value for, or creates, the registered property with the given name to the given value.
|
static final String EXTENSION_NAME
ExtensnionContainers, "ext".boolean has(String name)
assert project.ext.has("foo") == false
assert project.hasProperty("foo") == false
project.ext.foo = "bar"
assert project.ext.has("foo")
assert project.hasProperty("foo")
name - The name of the property to check fortrue if a property has been registered with this name, otherwise false.Object get(String name) throws ExtraPropertiesExtension.UnknownPropertyException
project.ext { foo = "bar" }
assert project.ext.get("foo") == "bar"
assert project.ext.foo == "bar"
assert project.ext["foo"] == "bar"
assert project.foo == "bar"
assert project["foo"] == "bar"
When using the first form, an ExtraPropertiesExtension.UnknownPropertyException exception will be thrown if the
extension does not have a property called “foo”. When using the second forms (i.e. Groovy notation),
Groovy's MissingPropertyException will be thrown instead.name - The name of the property to get the value ofExtraPropertiesExtension.UnknownPropertyException - if there is no property registered with the given namevoid set(String name, Object value)
project.ext.set("foo", "bar")
project.ext.foo = "bar"
project.ext["foo"] = "bar"
// Once the property has been created via the extension, it can be changed by the owner.
project.foo = "bar"
project["foo"] = "bar"
name - The name of the property to update the value of or createvalue - The value to set for the propertyMap<String,Object> getProperties()
project.version = "1.0"
assert project.hasProperty("version")
assert project.ext.properties.containsKey("version") == false
project.ext.foo = "bar"
assert project.ext.properties.containsKey("foo")
assert project.ext.properties.foo == project.ext.foo
assert project.ext.properties.every { key, value -> project.properties[key] == value }