org.apache.tools.ant.taskdefs
Class Property

java.lang.Object
  extended by org.apache.tools.ant.ProjectComponent
      extended by org.apache.tools.ant.Task
          extended by 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:

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
target, taskName, taskType, wrapper
 
Fields inherited from class org.apache.tools.ant.ProjectComponent
description, location, project
 
Constructor Summary
  Property()
          Constructor for Property.
protected Property(boolean userProperty)
          Constructor for Property.
protected Property(boolean userProperty, Project fallback)
          Constructor for Property.
 
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.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.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 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 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.

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.

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

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

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 or env 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

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