Property (Apache Ant API)
Keywords: org.apache.tools.ant.taskdefs.Property,Property class

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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

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 five ways to set properties:

- By supplying both the name and value attribute.
- 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 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.

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
`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
`description, location, target, taskName, taskType, wrapper`

Fields inherited from class org.apache.tools.ant.ProjectComponent
`project`

Constructor Summary
`` | `Property()`
`protected` | `Property(boolean userProperty)`
`protected` | `Property(boolean userProperty, Project fallback)`

Method Summary
`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.String v)` add a name value pair to the project property set
`Path` | `createClasspath()` The classpath to use when looking up a resource.
`void` | `execute()` set the property in the project to the value.
`Path` | `getClasspath()`
`java.lang.String` | `getEnvironment()`
`java.io.File` | `getFile()`
`java.lang.String` | `getName()`
`java.lang.String` | `getPrefix()`
`Reference` | `getRefid()`
`java.lang.String` | `getResource()`
`java.net.URL` | `getUrl()`
`java.lang.String` | `getValue()`
`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` | `loadUrl(java.net.URL url)` load properties from a url
`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` | `setRefid(Reference ref)` Sets a reference to an Ant datatype declared elsewhere.
`void` | `setResource(java.lang.String resource)` The resource name of a property file to load
`void` | `setUrl(java.net.URL url)` The url from which to load properties.
`void` | `setUserProperty(boolean userProperty)` Deprecated. This was never a supported feature and has been deprecated without replacement
`void` | `setValue(java.lang.String value)` The value of the property.
`java.lang.String` | `toString()` get the value of this property

Methods inherited from class org.apache.tools.ant.Task
`getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, maybeConfigure, perform, reconfigure, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType`

Methods inherited from class org.apache.tools.ant.ProjectComponent
`getProject, setProject`

Methods inherited from class java.lang.Object
`clone, 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()

### Property

    protected Property(boolean userProperty)

Since:
  Ant 1.5

### Property

    protected Property(boolean userProperty,
                       Project fallback)

Since:
  Ant 1.5

Method Detail

### 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()

### 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.String value)

  The value of the property.

  Parameters:
    `value` - value to assign

### getValue

    public java.lang.String getValue()

### setFile

    public void setFile(java.io.File file)

  Filename of a property file to load.

  Parameters:
    `file` - filename

### getFile

    public java.io.File getFile()

### 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()

### 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()

  Since:
    Ant 1.5

### 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()

### 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()

### 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()

  Since:
    Ant 1.5

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

### setClasspathRef

    public void setClasspathRef(Reference r)

  the classpath to use when looking up a resource, given as reference to a <path> defined elsewhere

### getClasspath

    public Path getClasspath()

  Since:
    Ant 1.5

### setUserProperty

    public void setUserProperty(boolean userProperty)

  Deprecated. This was never a supported feature and has been deprecated without replacement

### 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 or env attribute here is where it is loaded

  Overrides:
    `execute` in class `Task`
  Throws:
    `BuildException` - if something goes wrong with the build

### loadUrl

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

  load properties from a url

  Parameters:
    `url` - url to load from
    `BuildException`

### loadFile

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

  load properties from a file

  Parameters:
    `file` - file to load
    `BuildException`

### 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

### addProperties

    protected void addProperties(java.util.Properties props)

  iterate through a set of properties, resolve them then assign them

### 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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2000-2004 Apache Software Foundation. All Rights Reserved.