Property (Apache Ant API)
Date: 2021-07-10

org.apache.tools.ant.taskdefs

## Class Property

- java.lang.Object
- - org.apache.tools.ant.ProjectComponent
  - - org.apache.tools.ant.Task
    - - org.apache.tools.ant.taskdefs.Property

- All Implemented Interfaces:
    java.lang.Cloneable

      public class Property
      extends Task

  Sets a property by name, or set of properties (from file or resource) in the project.

  Properties are immutable: whoever sets a property first freezes it for the rest of the build; they are most definitely not variable.

  There are seven ways to set properties:

  - By supplying both the name and value attribute.
  - By supplying the name and nested text.
  - By supplying both the name and refid attribute.
  - By setting the file attribute with the filename of the property file to load. This property file has the format as defined by the file used in the class java.util.Properties.
  - By setting the url attribute with the url from which to load the properties. This url must be directed to a file that has the format as defined by the file used in the class java.util.Properties.
  - By setting the resource attribute with the resource name of the property file to load. This property file has the format as defined by the file used in the class java.util.Properties.
  - By setting the environment attribute with a prefix to use. Properties will be defined for every environment variable by prefixing the supplied name and a period to the name of the variable.
  - By setting the runtime attribute with a prefix to use. Properties `prefix.availableProcessors`, `prefix.freeMemory`, `prefix.totalMemory` and `prefix.maxMemory` will be defined with values that correspond to the corresponding methods of the `Runtime` class.

  Although combinations of these ways are possible, only one should be used at a time. Problems might occur with the order in which properties are set, for instance.

  The value part of the properties being set, might contain references to other properties. These references are resolved at the time these properties are set. This also holds for properties loaded from a property file.

  Properties are case sensitive.
  Since:
    Ant 1.1

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Path` | `classpath`
    `protected java.lang.String` | `env`
    `protected java.io.File` | `file`
    `protected java.lang.String` | `name`
    `protected java.lang.String` | `prefix`
    `protected Reference` | `ref`
    `protected java.lang.String` | `resource`
    `protected java.net.URL` | `url`
    `protected boolean` | `userProperty`
    `protected java.lang.String` | `value`

    - ### Fields inherited from class org.apache.tools.ant.Task

      `target, taskName, taskType, wrapper`

    - ### Fields inherited from class org.apache.tools.ant.ProjectComponent

      `description, location, project`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `Property()` Constructor for Property.
    `protected` | `Property(boolean userProperty)` Constructor for Property.
    `protected` | `Property(boolean userProperty, Project fallback)` Constructor for Property.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `addProperties(java.util.Properties props)` iterate through a set of properties, resolve them then assign them
    `protected void` | `addProperty(java.lang.String n, java.lang.Object v)` add a name value pair to the project property set
    `protected void` | `addProperty(java.lang.String n, java.lang.String v)` add a name value pair to the project property set
    `void` | `addText(java.lang.String msg)` Set a (multiline) property as nested text.
    `Path` | `createClasspath()` The classpath to use when looking up a resource.
    `void` | `execute()` set the property in the project to the value.
    `Path` | `getClasspath()` Get the classpath used when looking up a resource.
    `java.lang.String` | `getEnvironment()` Get the environment attribute.
    `java.io.File` | `getFile()` Get the file attribute.
    `java.lang.String` | `getName()` Get the property name.
    `java.lang.String` | `getPrefix()` Get the prefix attribute.
    `boolean` | `getPrefixValues()` Whether to apply the prefix when expanding properties on the right hand side of a properties file as well.
    `Reference` | `getRefid()` Get the refid attribute.
    `java.lang.String` | `getResource()` Get the resource attribute.
    `java.lang.String` | `getRuntime()` Get the runtime attribute.
    `java.net.URL` | `getUrl()` Get the url attribute.
    `java.lang.String` | `getValue()` Get the property value.
    `protected void` | `loadEnvironment(java.lang.String prefix)` load the environment values
    `protected void` | `loadFile(java.io.File file)` load properties from a file
    `protected void` | `loadResource(java.lang.String name)` load properties from a resource in the current classpath
    `protected void` | `loadRuntime(java.lang.String prefix)` load the runtime values
    `protected void` | `loadUrl(java.net.URL url)` load properties from a url
    `void` | `setBasedir(java.io.File basedir)` Sets 'basedir' attribute.
    `void` | `setClasspath(Path classpath)` The classpath to use when looking up a resource.
    `void` | `setClasspathRef(Reference r)` the classpath to use when looking up a resource, given as reference to a <path> defined elsewhere
    `void` | `setEnvironment(java.lang.String env)` Prefix to use when retrieving environment variables.
    `void` | `setFile(java.io.File file)` Filename of a property file to load.
    `void` | `setLocation(java.io.File location)` Sets the property to the absolute filename of the given file.
    `void` | `setName(java.lang.String name)` The name of the property to set.
    `void` | `setPrefix(java.lang.String prefix)` Prefix to apply to properties loaded using `file` or `resource`.
    `void` | `setPrefixValues(boolean b)` Whether to apply the prefix when expanding properties on the right hand side of a properties file as well.
    `void` | `setRefid(Reference ref)` Sets a reference to an Ant datatype declared elsewhere.
    `void` | `setRelative(boolean relative)` Sets 'relative' attribute.
    `void` | `setResource(java.lang.String resource)` The resource name of a property file to load
    `void` | `setRuntime(java.lang.String prefix)` Prefix to use when retrieving Runtime properties.
    `void` | `setUrl(java.net.URL url)` The url from which to load properties.
    `void` | `setUserProperty(boolean userProperty)` Deprecated. since 1.5.x. This was never a supported feature and has been deprecated without replacement.
    `void` | `setValue(java.lang.Object value)` Set the value of the property.
    `void` | `setValue(java.lang.String value)` Set the value of the property as a String.
    `java.lang.String` | `toString()` get the value of this property

    - ### Methods inherited from class org.apache.tools.ant.Task

      `bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType`

    - ### Methods inherited from class org.apache.tools.ant.ProjectComponent

      `clone, getDescription, getLocation, getProject, setDescription, setLocation, setProject`

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### name

          protected java.lang.String name

    - #### value

          protected java.lang.String value

    - #### file

          protected java.io.File file

    - #### url

          protected java.net.URL url

    - #### resource

          protected java.lang.String resource

    - #### classpath

          protected Path classpath

    - #### env

          protected java.lang.String env

    - #### ref

          protected Reference ref

    - #### prefix

          protected java.lang.String prefix

    - #### userProperty

          protected boolean userProperty

  - ### Constructor Detail

    - #### Property

          public Property()

      Constructor for Property.

    - #### Property

          protected Property(boolean userProperty)

      Constructor for Property.
      Parameters:
        `userProperty` - if true this is a user property
      Since:
        Ant 1.5

    - #### Property

          protected Property(boolean userProperty,
                             Project fallback)

      Constructor for Property.
      Parameters:
        `userProperty` - if true this is a user property
        `fallback` - a project to use to look for references if the reference is not in the current project
      Since:
        Ant 1.5

  - ### Method Detail

    - #### setRelative

          public void setRelative(boolean relative)

      Sets 'relative' attribute.
      Parameters:
        `relative` - new value
      Since:
        Ant 1.8.0

    - #### setBasedir

          public void setBasedir(java.io.File basedir)

      Sets 'basedir' attribute.
      Parameters:
        `basedir` - new value
      Since:
        Ant 1.8.0

    - #### setName

          public void setName(java.lang.String name)

      The name of the property to set.
      Parameters:
        `name` - property name

    - #### getName

          public java.lang.String getName()

      Get the property name.
      Returns:
        the property name

    - #### setLocation

          public void setLocation(java.io.File location)

      Sets the property to the absolute filename of the given file. If the value of this attribute is an absolute path, it is left unchanged (with / and \ characters converted to the current platforms conventions). Otherwise it is taken as a path relative to the project's basedir and expanded.
      Parameters:
        `location` - path to set

    - #### setValue

          public void setValue(java.lang.Object value)

      Set the value of the property.
      Parameters:
        `value` - the value to use.

    - #### setValue

          public void setValue(java.lang.String value)

      Set the value of the property as a String.
      Parameters:
        `value` - value to assign

    - #### addText

          public void addText(java.lang.String msg)

      Set a (multiline) property as nested text.
      Parameters:
        `msg` - the text to append to the output text
      Since:
        Ant 1.8.0

    - #### getValue

          public java.lang.String getValue()

      Get the property value.
      Returns:
        the property value

    - #### setFile

          public void setFile(java.io.File file)

      Filename of a property file to load.
      Parameters:
        `file` - filename

    - #### getFile

          public java.io.File getFile()

      Get the file attribute.
      Returns:
        the file attribute

    - #### setUrl

          public void setUrl(java.net.URL url)

      The url from which to load properties.
      Parameters:
        `url` - url string

    - #### getUrl

          public java.net.URL getUrl()

      Get the url attribute.
      Returns:
        the url attribute

    - #### setPrefix

          public void setPrefix(java.lang.String prefix)

      Prefix to apply to properties loaded using `file` or `resource`. A "." is appended to the prefix if not specified.
      Parameters:
        `prefix` - prefix string
      Since:
        Ant 1.5

    - #### getPrefix

          public java.lang.String getPrefix()

      Get the prefix attribute.
      Returns:
        the prefix attribute
      Since:
        Ant 1.5

    - #### setPrefixValues

          public void setPrefixValues(boolean b)

      Whether to apply the prefix when expanding properties on the right hand side of a properties file as well.
      Parameters:
        `b` - boolean
      Since:
        Ant 1.8.2

    - #### getPrefixValues

          public boolean getPrefixValues()

      Whether to apply the prefix when expanding properties on the right hand side of a properties file as well.
      Returns:
        boolean
      Since:
        Ant 1.8.2

    - #### setRefid

          public void setRefid(Reference ref)

      Sets a reference to an Ant datatype declared elsewhere. Only yields reasonable results for references PATH like structures or properties.
      Parameters:
        `ref` - reference

    - #### getRefid

          public Reference getRefid()

      Get the refid attribute.
      Returns:
        the refid attribute

    - #### setResource

          public void setResource(java.lang.String resource)

      The resource name of a property file to load
      Parameters:
        `resource` - resource on classpath

    - #### getResource

          public java.lang.String getResource()

      Get the resource attribute.
      Returns:
        the resource attribute

    - #### setEnvironment

          public void setEnvironment(java.lang.String env)

      Prefix to use when retrieving environment variables. Thus if you specify environment="myenv" you will be able to access OS-specific environment variables via property names "myenv.PATH" or "myenv.TERM".

      Note that if you supply a property name with a final "." it will not be doubled. ie environment="myenv." will still allow access of environment variables through "myenv.PATH" and "myenv.TERM". This functionality is currently only implemented on select platforms. Feel free to send patches to increase the number of platforms this functionality is supported on ;).

      Note also that properties are case sensitive, even if the environment variables on your operating system are not, e.g. it will be ${env.Path} not ${env.PATH} on Windows 2000.
      Parameters:
        `env` - prefix

    - #### getEnvironment

          public java.lang.String getEnvironment()

      Get the environment attribute.
      Returns:
        the environment attribute
      Since:
        Ant 1.5

    - #### setRuntime

          public void setRuntime(java.lang.String prefix)

      Prefix to use when retrieving Runtime properties.

      Properties `prefix.availableProcessors`, `prefix.freeMemory`, `prefix.totalMemory` and `prefix.maxMemory` will be defined with values that correspond to the corresponding methods of the `Runtime` class.

      Note that if you supply a prefix name with a final "." it will not be doubled. ie runtime="myrt." will still allow access of property through "myrt.availableProcessors" and "myrt.freeMemory".

      The property values are snapshots taken at the point in time when the `property` has been executed.

      Parameters:
        `prefix` - prefix
      Since:
        Ant 1.9.12

    - #### getRuntime

          public java.lang.String getRuntime()

      Get the runtime attribute.
      Returns:
        the runtime attribute
      Since:
        Ant 1.9.12

    - #### setClasspath

          public void setClasspath(Path classpath)

      The classpath to use when looking up a resource.
      Parameters:
        `classpath` - to add to any existing classpath

    - #### createClasspath

          public Path createClasspath()

      The classpath to use when looking up a resource.
      Returns:
        a path to be configured

    - #### setClasspathRef

          public void setClasspathRef(Reference r)

      the classpath to use when looking up a resource, given as reference to a <path> defined elsewhere
      Parameters:
        `r` - a reference to a classpath

    - #### getClasspath

          public Path getClasspath()

      Get the classpath used when looking up a resource.
      Returns:
        the classpath
      Since:
        Ant 1.5

    - #### setUserProperty

          @Deprecated
          public void setUserProperty(boolean userProperty)

      Deprecated. since 1.5.x. This was never a supported feature and has been deprecated without replacement.
      Parameters:
        `userProperty` - ignored

    - #### toString

          public java.lang.String toString()

      get the value of this property
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        the current value or the empty string

    - #### execute

          public void execute()
                       throws BuildException

      set the property in the project to the value. if the task was give a file, resource, env or runtime attribute here is where it is loaded
      Overrides:
        `execute` in class `Task`
      Throws:
        `BuildException` - on error

    - #### loadUrl

          protected void loadUrl(java.net.URL url)
                          throws BuildException

      load properties from a url
      Parameters:
        `url` - url to load from
      Throws:
        `BuildException` - on error

    - #### loadFile

          protected void loadFile(java.io.File file)
                           throws BuildException

      load properties from a file
      Parameters:
        `file` - file to load
      Throws:
        `BuildException` - on error

    - #### loadResource

          protected void loadResource(java.lang.String name)

      load properties from a resource in the current classpath
      Parameters:
        `name` - name of resource to load

    - #### loadEnvironment

          protected void loadEnvironment(java.lang.String prefix)

      load the environment values
      Parameters:
        `prefix` - prefix to place before them

    - #### loadRuntime

          protected void loadRuntime(java.lang.String prefix)

      load the runtime values
      Parameters:
        `prefix` - prefix to place before them
      Since:
        1.9.12

    - #### addProperties

          protected void addProperties(java.util.Properties props)

      iterate through a set of properties, resolve them then assign them
      Parameters:
        `props` - the properties to iterate over

    - #### addProperty

          protected void addProperty(java.lang.String n,
                                     java.lang.String v)

      add a name value pair to the project property set
      Parameters:
        `n` - name of property
        `v` - value to set

    - #### addProperty

          protected void addProperty(java.lang.String n,
                                     java.lang.Object v)

      add a name value pair to the project property set
      Parameters:
        `n` - name of property
        `v` - value to set
      Since:
        Ant 1.8