org.apache.tools.ant.taskdefs

Class 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:

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

UNKNOWN: name="name" description="One of these, when using the name attribute" name="noname" description="One of these, when not using the name attribute" category="property"

Field Summary
protected Pathclasspath
protected Stringenv
protected Filefile
protected Stringname
protected Stringprefix
protected Referenceref
protected Stringresource
protected URLurl
protected booleanuserProperty
protected Stringvalue
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 voidaddProperties(Properties props)
iterate through a set of properties, resolve them then assign them
protected voidaddProperty(String n, String v)
add a name value pair to the project property set
PathcreateClasspath()
The classpath to use when looking up a resource.
voidexecute()
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
PathgetClasspath()
Get the classpath used when looking up a resource.
StringgetEnvironment()
Get the environment attribute.
FilegetFile()
Get the file attribute.
StringgetName()
Get the property name.
StringgetPrefix()
Get the prefix attribute.
ReferencegetRefid()
Get the refid attribute.
StringgetResource()
Get the resource attribute.
URLgetUrl()
Get the url attribute.
StringgetValue()
Get the property value.
protected voidloadEnvironment(String prefix)
load the environment values
protected voidloadFile(File file)
load properties from a file
protected voidloadResource(String name)
load properties from a resource in the current classpath
protected voidloadUrl(URL url)
load properties from a url
voidsetClasspath(Path classpath)
The classpath to use when looking up a resource.
voidsetClasspathRef(Reference r)
the classpath to use when looking up a resource, given as reference to a <path> defined elsewhere
voidsetEnvironment(String env)
Prefix to use when retrieving environment variables.
voidsetFile(File file)
Filename of a property file to load.
voidsetLocation(File location)
Sets the property to the absolute filename of the given file.
voidsetName(String name)
The name of the property to set.
voidsetPrefix(String prefix)
Prefix to apply to properties loaded using file or resource.
voidsetRefid(Reference ref)
Sets a reference to an Ant datatype declared elsewhere.
voidsetResource(String resource)
The resource name of a property file to load
voidsetUrl(URL url)
The url from which to load properties.
voidsetUserProperty(boolean userProperty)
voidsetValue(String value)
The value of the property.
StringtoString()
get the value of this property

Field Detail

classpath

protected Path classpath

env

protected String env

file

protected File file

name

protected String name

prefix

protected String prefix

ref

protected Reference ref

resource

protected String resource

url

protected URL url

userProperty

protected boolean userProperty

value

protected String value

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

addProperties

protected void addProperties(Properties props)
iterate through a set of properties, resolve them then assign them

Parameters: props the properties to iterate over

addProperty

protected void addProperty(String n, String v)
add a name value pair to the project property set

Parameters: n name of property v value to set

createClasspath

public Path createClasspath()
The classpath to use when looking up a resource.

Returns: a path to be configured

execute

public void execute()
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

Throws: BuildException on error

getClasspath

public Path getClasspath()
Get the classpath used when looking up a resource.

Returns: the classpath

Since: Ant 1.5

getEnvironment

public String getEnvironment()
Get the environment attribute.

Returns: the environment attribute

Since: Ant 1.5

getFile

public File getFile()
Get the file attribute.

Returns: the file attribute

getName

public String getName()
Get the property name.

Returns: the property name

getPrefix

public String getPrefix()
Get the prefix attribute.

Returns: the prefix attribute

Since: Ant 1.5

getRefid

public Reference getRefid()
Get the refid attribute.

Returns: the refid attribute

getResource

public String getResource()
Get the resource attribute.

Returns: the resource attribute

getUrl

public URL getUrl()
Get the url attribute.

Returns: the url attribute

getValue

public String getValue()
Get the property value.

Returns: the property value

loadEnvironment

protected void loadEnvironment(String prefix)
load the environment values

Parameters: prefix prefix to place before them

loadFile

protected void loadFile(File file)
load properties from a file

Parameters: file file to load

Throws: BuildException on error

loadResource

protected void loadResource(String name)
load properties from a resource in the current classpath

Parameters: name name of resource to load

loadUrl

protected void loadUrl(URL url)
load properties from a url

Parameters: url url to load from

Throws: BuildException on error

setClasspath

public void setClasspath(Path classpath)
The classpath to use when looking up a resource.

Parameters: classpath to add to any existing classpath

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

setEnvironment

public void setEnvironment(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

UNKNOWN: group="noname"

setFile

public void setFile(File file)
Filename of a property file to load.

Parameters: file filename

UNKNOWN: group="noname"

setLocation

public void setLocation(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

UNKNOWN: group="name"

setName

public void setName(String name)
The name of the property to set.

Parameters: name property name

setPrefix

public void setPrefix(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

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

UNKNOWN: group="name"

setResource

public void setResource(String resource)
The resource name of a property file to load

Parameters: resource resource on classpath

UNKNOWN: group="noname"

setUrl

public void setUrl(URL url)
The url from which to load properties.

Parameters: url url string

UNKNOWN: group="noname"

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

UNKNOWN: ignore="true"

setValue

public void setValue(String value)
The value of the property.

Parameters: value value to assign

UNKNOWN: group="name"

toString

public String toString()
get the value of this property

Returns: the current value or the empty string