org.apache.tools.ant

Class PropertyHelper

java.lang.Object

org.apache.tools.ant.PropertyHelper

All Implemented Interfaces:

GetProperty

public class PropertyHelper
extends Object
implements GetProperty

Deals with properties - substitution, dynamic properties, etc.

This code has been heavily restructured for Ant 1.8.0. It is expected that custom PropertyHelper implementation that used the older chaining mechanism of Ant 1.6 won't work in all cases, and its usage is deprecated. The preferred way to customize Ant's property handling is by adding delegates of the appropriate subinterface and have this implementation use them.

When expanding a string that may contain properties this class will delegate the actual parsing to parseProperties inside the ParseProperties class which in turn uses the PropertyExpander delegates to find properties inside the string and this class to expand the propertiy names found into the corresponding values.

When looking up a property value this class will first consult all PropertyEvaluator delegates and fall back to an internal map of "project properties" if no evaluator matched the property name.

When setting a property value this class will first consult all PropertySetter delegates and fall back to an internal map of "project properties" if no setter matched the property name.

Since:

Ant 1.6

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	PropertyHelper.Delegate Marker interface for a PropertyHelper delegate.
static interface	PropertyHelper.PropertyEvaluator Looks up a property's value based on its name.
static interface	PropertyHelper.PropertySetter Sets or overrides a property.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	PropertyHelper() Default constructor.

Method Summary

Modifier and Type	Method and Description
void	add(PropertyHelper.Delegate delegate) Add the specified delegate object to this PropertyHelper.
boolean	containsProperties(String value) Learn whether a String contains replaceable properties.
void	copyInheritedProperties(Project other) Copies all user properties that have not been set on the command line or a GUI tool from this instance to the Project instance given as the argument.
void	copyUserProperties(Project other) Copies all user properties that have been set on the command line or a GUI tool from this instance to the Project instance given as the argument.
protected static Set<Class<? extends PropertyHelper.Delegate>>	getDelegateInterfaces(PropertyHelper.Delegate d) Get all Delegate interfaces (excluding Delegate itself) from the specified Delegate.
protected <D extends PropertyHelper.Delegate> List<D>	getDelegates(Class<D> type) Get the Collection of delegates of the specified type.
Collection<PropertyExpander>	getExpanders() Get the expanders.
Hashtable<String,Object>	getInheritedProperties() Returns a copy of the inherited property hashtable
protected Hashtable<String,Object>	getInternalInheritedProperties() special back door for subclasses, internal access to the hashtables
protected Hashtable<String,Object>	getInternalProperties() special back door for subclasses, internal access to the hashtables
protected Hashtable<String,Object>	getInternalUserProperties() special back door for subclasses, internal access to the hashtables
Project	getProject() Get this PropertyHelper's Project.
Hashtable<String,Object>	getProperties() Returns a copy of the properties table.
static Object	getProperty(Project project, String name) A helper static method to get a property from a particular project.
Object	getProperty(String name) Returns the value of a property, if it is set.
static PropertyHelper	getPropertyHelper(Project project) Factory method to create a property processor.
Hashtable<String,Object>	getUserProperties() Returns a copy of the user property hashtable
Object	getUserProperty(String name) Returns the value of a user property, if it is set.
Object	parseProperties(String value) Decode properties from a String representation.
String	replaceProperties(String value) Replaces ${xxx} style constructions in the given value with the string value of the corresponding data types.
String	replaceProperties(String ns, String value, Hashtable<String,Object> keys) Replaces ${xxx} style constructions in the given value with the string value of the corresponding data types.
void	setInheritedProperty(String name, Object value) Sets an inherited user property, which cannot be overwritten by set/unset property calls.
static void	setNewProperty(Project project, String name, Object value) A helper static method to set a new property from a particular project.
void	setNewProperty(String name, Object value) Sets a property if no value currently exists.
void	setProject(Project p) Set the project for which this helper is performing property resolution.
static void	setProperty(Project project, String name, Object value) A helper static method to set a property from a particular project.
boolean	setProperty(String name, Object value, boolean verbose) Default implementation of setProperty.
void	setUserProperty(String name, Object value) Sets a user property, which cannot be overwritten by set/unset property calls.
boolean	testIfCondition(Object value) Returns true if the value is null or an empty string, can be interpreted as a true value or cannot be interpreted as a false value and a property of the value's name exists.
boolean	testUnlessCondition(Object value) Returns true if the value is null or an empty string, can be interpreted as a false value or cannot be interpreted as a true value and a property of the value's name doesn't exist.
static Boolean	toBoolean(Object value) If the given object can be interpreted as a true/false value, turn it into a matching Boolean - otherwise return null.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PropertyHelper

protected PropertyHelper()

Default constructor.

Method Detail

add

public void add(PropertyHelper.Delegate delegate)

Add the specified delegate object to this PropertyHelper. Delegates are processed in LIFO order.

Parameters:

delegate - the delegate to add.

Since:

Ant 1.8.0

containsProperties

public boolean containsProperties(String value)

Learn whether a String contains replaceable properties.

Parameters:

value - the String to check.

Returns:

true if value contains property notation.

copyInheritedProperties

public void copyInheritedProperties(Project other)

Copies all user properties that have not been set on the command line or a GUI tool from this instance to the Project instance given as the argument.

To copy all "user" properties, you will also have to call copyUserProperties.

Does not copy properties held by implementations of delegates (like local properties).

Parameters:

other - the project to copy the properties to. Must not be null.

Since:

Ant 1.6

copyUserProperties

public void copyUserProperties(Project other)

Copies all user properties that have been set on the command line or a GUI tool from this instance to the Project instance given as the argument.

To copy all "user" properties, you will also have to call copyInheritedProperties.

Does not copy properties held by implementations of delegates (like local properties).

Parameters:

other - the project to copy the properties to. Must not be null.

Since:

Ant 1.6

getDelegateInterfaces

protected static Set<Class<? extends PropertyHelper.Delegate>> getDelegateInterfaces(PropertyHelper.Delegate d)

Get all Delegate interfaces (excluding Delegate itself) from the specified Delegate.

Parameters:

d - the Delegate to inspect.

Returns:

Set<Class>

Since:

Ant 1.8.0

getDelegates

protected <D extends PropertyHelper.Delegate> List<D> getDelegates(Class<D> type)

Get the Collection of delegates of the specified type.

Parameters:

type - delegate type.

Returns:

Collection.

Since:

Ant 1.8.0

getExpanders

public Collection<PropertyExpander> getExpanders()

Get the expanders.

Returns:

the expanders.

Since:

Ant 1.8.0

getInheritedProperties

public Hashtable<String,Object> getInheritedProperties()

Returns a copy of the inherited property hashtable

Does not contain properties held by implementations of delegates (like local properties).

Returns:

a hashtable containing just the inherited properties

getInternalInheritedProperties

protected Hashtable<String,Object> getInternalInheritedProperties()

special back door for subclasses, internal access to the hashtables

Returns:

the live hashtable inherited properties

getInternalProperties

protected Hashtable<String,Object> getInternalProperties()

special back door for subclasses, internal access to the hashtables

Returns:

the live hashtable of all properties

getInternalUserProperties

protected Hashtable<String,Object> getInternalUserProperties()

special back door for subclasses, internal access to the hashtables

Returns:

the live hashtable of user properties

getProject

public Project getProject()

Get this PropertyHelper's Project.

Returns:

Project

getProperties

public Hashtable<String,Object> getProperties()

Returns a copy of the properties table.

Does not contain properties held by implementations of delegates (like local properties).

Returns:

a hashtable containing all properties (including user properties).

getProperty

public static Object getProperty(Project project,
                                 String name)

A helper static method to get a property from a particular project.

Parameters:

project - the project in question.

name - the property name

Returns:

the value of the property if present, null otherwise.

Since:

Ant 1.8.0

getProperty

public Object getProperty(String name)

Returns the value of a property, if it is set.

This is the method that is invoked by {Project#getProperty Project.getProperty}.

You can override this method in order to plug your own storage but the recommended approach is to add your own implementation of PropertyEvaluator instead.

Specified by:

getProperty in interface GetProperty

Parameters:

name - The name of the property. May be null, in which case the return value is also null.

Returns:

the property value, or null for no match or if a null name is provided.

getPropertyHelper

public static PropertyHelper getPropertyHelper(Project project)

Factory method to create a property processor. Users can provide their own or replace it using "ant.PropertyHelper" reference. User tasks can also add themselves to the chain, and provide dynamic properties.

Parameters:

project - the project for which the property helper is required.

Returns:

the project's property helper.

getUserProperties

public Hashtable<String,Object> getUserProperties()

Returns a copy of the user property hashtable

Does not contain properties held by implementations of delegates (like local properties).

Returns:

a hashtable containing just the user properties

getUserProperty

public Object getUserProperty(String name)

Returns the value of a user property, if it is set.

Does not consult any delegates.

Parameters:

name - The name of the property. May be null, in which case the return value is also null.

Returns:

the property value, or null for no match or if a null name is provided.

parseProperties

public Object parseProperties(String value)
                       throws BuildException

Decode properties from a String representation. If the entire contents of the String resolve to a single property, that value is returned. Otherwise a String is returned.

Parameters:

value - The string to be scanned for property references. May be null, in which case this method returns immediately with no effect.

Returns:

the original string with the properties replaced, or null if the original string is null.

Throws:

BuildException - if the string contains an opening ${ without a closing }

replaceProperties

public String replaceProperties(String value)
                         throws BuildException

Replaces ${xxx} style constructions in the given value with the string value of the corresponding data types.

Parameters:

value - The string to be scanned for property references. May be null, in which case this method returns immediately with no effect.

Returns:

the original string with the properties replaced, or null if the original string is null.

Throws:

BuildException - if the string contains an opening ${ without a closing }

replaceProperties

public String replaceProperties(String ns,
                                String value,
                                Hashtable<String,Object> keys)
                         throws BuildException

Replaces ${xxx} style constructions in the given value with the string value of the corresponding data types.

Delegates to the one-arg version, completely ignoring the ns and keys parameters.

Parameters:

ns - The namespace for the property.

value - The string to be scanned for property references. May be null, in which case this method returns immediately with no effect.

keys - Mapping (String to Object) of property names to their values. If null, only project properties will be used.

Returns:

the original string with the properties replaced, or null if the original string is null.

Throws:

BuildException - if the string contains an opening ${ without a closing }

setInheritedProperty

public void setInheritedProperty(String name,
                                 Object value)

Sets an inherited user property, which cannot be overwritten by set/unset property calls. Any previous value is overwritten. Also marks these properties as properties that have not come from the command line.

Does not consult any delegates.

Parameters:

name - The name of property to set. Must not be null.

value - The new value of the property. Must not be null.

setNewProperty

public static void setNewProperty(Project project,
                                  String name,
                                  Object value)

A helper static method to set a new property from a particular project.

Parameters:

project - the project in question.

name - the property name

value - the value to use.

Since:

Ant 1.8.0

setNewProperty

public void setNewProperty(String name,
                           Object value)

Sets a property if no value currently exists. If the property exists already, a message is logged and the method returns with no other effect.

Parameters:

name - The name of property to set. Must not be null.

value - The new value of the property. Must not be null.

Since:

Ant 1.8.0

setProject

public void setProject(Project p)

Set the project for which this helper is performing property resolution.

Parameters:

p - the project instance.

setProperty

public static void setProperty(Project project,
                               String name,
                               Object value)

A helper static method to set a property from a particular project.

Parameters:

project - the project in question.

name - the property name

value - the value to use.

Since:

Ant 1.8.0

setProperty

public boolean setProperty(String name,
                           Object value,
                           boolean verbose)

Default implementation of setProperty. Will be called from Project.

Parameters:

name - The name of the property.

value - The value to set the property to.

verbose - If this is true output extra log messages.

Returns:

true if the property is set.

setUserProperty

public void setUserProperty(String name,
                            Object value)

Sets a user property, which cannot be overwritten by set/unset property calls. Any previous value is overwritten.

Does not consult any delegates.

Parameters:

name - The name of property to set. Must not be null.

value - The new value of the property. Must not be null.

testIfCondition

public boolean testIfCondition(Object value)

Returns true if the value is null or an empty string, can be interpreted as a true value or cannot be interpreted as a false value and a property of the value's name exists.

Since:

Ant 1.8.0

testUnlessCondition

public boolean testUnlessCondition(Object value)

Returns true if the value is null or an empty string, can be interpreted as a false value or cannot be interpreted as a true value and a property of the value's name doesn't exist.

Since:

Ant 1.8.0

toBoolean

public static Boolean toBoolean(Object value)

If the given object can be interpreted as a true/false value, turn it into a matching Boolean - otherwise return null.

Since:

Ant 1.8.0