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

Field Summary

protected Path
classpath
protected String
env
protected File
file
protected String
name
protected String
prefix
protected Reference
ref
protected String
resource
protected URL
url
protected boolean
userProperty
protected 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()
Sole constructor.
Property(boolean userProperty)
Property(boolean userProperty, Project fallback)

Method Summary

protected void
addProperties(Properties props)
iterate through a set of properties, resolve them then assign them
protected void
addProperty(String n, 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()
String
getEnvironment()
File
getFile()
String
getName()
String
getPrefix()
Reference
getRefid()
String
getResource()
URL
getUrl()
String
getValue()
protected void
loadEnvironment(String prefix)
load the environment values
protected void
loadFile(File file)
load properties from a file
protected void
loadResource(String name)
load properties from a resource in the current classpath
protected void
loadUrl(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(String env)
Prefix to use when retrieving environment variables.
void
setFile(File file)
Filename of a property file to load.
void
setLocation(File location)
Sets the property to the absolute filename of the given file.
void
setName(String name)
The name of the property to set.
void
setPrefix(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(String resource)
The resource name of a property file to load
void
setUrl(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(String value)
The value of the property.
String
toString()
get the value of this property

Methods inherited from class org.apache.tools.ant.Task

execute, 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, log, log, setProject

Field Details

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 Details

Property

public Property()
Sole constructor.

Property

protected Property(boolean userProperty)
Since:
Ant 1.5

Property

protected Property(boolean userProperty,
                   Project fallback)
Since:
Ant 1.5

Method Details

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()
            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 interface Task

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)
            throws BuildException
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)
            throws BuildException
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

setFile

public void setFile(File file)
Filename of a property file to load.
Parameters:
file - filename

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

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

setResource

public void setResource(String resource)
The resource name of a property file to load
Parameters:
resource - resource on classpath

setUrl

public void setUrl(URL url)
The url from which to load properties.
Parameters:
url - url string

setUserProperty

public void setUserProperty(boolean userProperty)

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


setValue

public void setValue(String value)
The value of the property.
Parameters:
value - value to assign

toString

public String toString()
get the value of this property
Returns:
the current value or the empty string

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