ExtraPropertiesExtension (Gradle API 7.6.4)

Package org.gradle.api.plugins

## Interface ExtraPropertiesExtension

-     public interface ExtraPropertiesExtension

  Additional, ad-hoc, properties for Gradle domain objects.

  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.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface | Description
    --- | --- | ---
    `static class` | `ExtraPropertiesExtension.UnknownPropertyException` | The exception that will be thrown when an attempt is made to read a property that is not set.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `EXTENSION_NAME` | The name of this extension in all `ExtensionContainers`, "ext".

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.lang.Object` | `get​(java.lang.String name)` | Returns the value for the registered property with the given name.
    `java.util.Map<java.lang.String,​java.lang.Object>` | `getProperties()` | Returns all of the registered properties and their current values as a map.
    `boolean` | `has​(java.lang.String name)` | Returns whether or not the extension has a property registered via the given name.
    `void` | `set​(java.lang.String name, java.lang.Object value)` | Updates the value for, or creates, the registered property with the given name to the given value.

- - ### Field Detail

    - #### EXTENSION_NAME

          static final java.lang.String EXTENSION_NAME

      The name of this extension in all `ExtensionContainers`, "ext".
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### has

          boolean has​(java.lang.String name)

      Returns whether or not the extension has a property registered via the given 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")

      Parameters:
        `name` - The name of the property to check for
      Returns:
        `true` if a property has been registered with this name, otherwise `false`.

    - #### get

          @Nullable
          java.lang.Object get​(java.lang.String name)
                        throws ExtraPropertiesExtension.UnknownPropertyException

      Returns the value for the registered property with the given name. When using an extra properties extension from Groovy, you can also get properties via Groovy's property syntax. All of the following lines of code are equivalent.

           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.
      Parameters:
        `name` - The name of the property to get the value of
      Returns:
        The value for the property with the given name.
      Throws:
        `ExtraPropertiesExtension.UnknownPropertyException` - if there is no property registered with the given name

    - #### set

          void set​(java.lang.String name,
                   @Nullable
                   java.lang.Object value)

      Updates the value for, or creates, the registered property with the given name to the given value. When using an extra properties extension from Groovy, you can also set properties via Groovy's property syntax. All of the following lines of code are equivalent.

           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"

      Parameters:
        `name` - The name of the property to update the value of or create
        `value` - The value to set for the property

    - #### getProperties

          java.util.Map<java.lang.String,​java.lang.Object> getProperties()

      Returns all of the registered properties and their current values as a map. The returned map is detached from the extension. That is, any changes made to the map do not change the extension from which it originated.

           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 }

      Returns:
        All of the registered properties and their current values as a map.