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"

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()
protected Property(boolean userProperty)
protected Property(boolean userProperty, Project fallback)
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()
StringgetEnvironment()
FilegetFile()
StringgetName()
StringgetPrefix()
ReferencegetRefid()
StringgetResource()
URLgetUrl()
StringgetValue()
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()

Property

protected Property(boolean userProperty)

Since: Ant 1.5

Property

protected Property(boolean userProperty, Project fallback)

Since: Ant 1.5

Method Detail

addProperties

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

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.

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

getClasspath

public Path getClasspath()

Since: Ant 1.5

getEnvironment

public String getEnvironment()

Since: Ant 1.5

getFile

public File getFile()

getName

public String getName()

getPrefix

public String getPrefix()

Since: Ant 1.5

getRefid

public Reference getRefid()

getResource

public String getResource()

getUrl

public URL getUrl()

getValue

public String getValue()

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

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

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

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: This was never a supported feature and has been deprecated without replacement

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

Copyright B) 2000-2007 Apache Software Foundation. All Rights Reserved.