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