org.apache.tools.antClass PropertyHelper
- java.lang.Object
- org.apache.tools.ant.PropertyHelper
- All Implemented Interfaces:
- GetProperty
public class PropertyHelper extends java.lang.Object implements GetPropertyDeals 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 toparseProperties
inside the ParseProperties class which in turn uses thePropertyExpander delegates
to find properties inside the string and this class to expand the property names found into the corresponding values.When
looking up a property value
this class will first consult allPropertyEvaluator
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 allPropertySetter
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
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method and Description void
add(PropertyHelper.Delegate delegate)
Add the specified delegate object to this PropertyHelper.boolean
containsProperties(java.lang.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 java.util.Set<java.lang.Class<? extends PropertyHelper.Delegate>>
getDelegateInterfaces(PropertyHelper.Delegate d)
Get all Delegate interfaces (excluding Delegate itself) from the specified Delegate.protected <D extends PropertyHelper.Delegate>
java.util.List<D>getDelegates(java.lang.Class<D> type)
Get the Collection of delegates of the specified type.java.util.Collection<PropertyExpander>
getExpanders()
Get theexpanders
.java.util.Hashtable<java.lang.String,java.lang.Object>
getInheritedProperties()
Returns a copy of the inherited property hashtableprotected java.util.Hashtable<java.lang.String,java.lang.Object>
getInternalInheritedProperties()
special back door for subclasses, internal access to the hashtablesprotected java.util.Hashtable<java.lang.String,java.lang.Object>
getInternalProperties()
special back door for subclasses, internal access to the hashtablesprotected java.util.Hashtable<java.lang.String,java.lang.Object>
getInternalUserProperties()
special back door for subclasses, internal access to the hashtablesPropertyHelper
getNext()
Deprecated.use the delegate mechanism insteadProject
getProject()
Get this PropertyHelper's Project.java.util.Hashtable<java.lang.String,java.lang.Object>
getProperties()
Returns a copy of the properties table.static java.lang.Object
getProperty(Project project, java.lang.String name)
A helper static method to get a property from a particular project.java.lang.Object
getProperty(java.lang.String name)
Returns the value of a property, if it is set.java.lang.Object
getProperty(java.lang.String ns, java.lang.String name)
Deprecated.namespaces are unnecessary.static PropertyHelper
getPropertyHelper(Project project)
Factory method to create a property processor.java.lang.Object
getPropertyHook(java.lang.String ns, java.lang.String name, boolean user)
Deprecated.PropertyHelper chaining is deprecated.java.util.Hashtable<java.lang.String,java.lang.Object>
getUserProperties()
Returns a copy of the user property hashtablejava.lang.Object
getUserProperty(java.lang.String name)
Returns the value of a user property, if it is set.java.lang.Object
getUserProperty(java.lang.String ns, java.lang.String name)
Deprecated.namespaces are unnecessary.java.lang.Object
parseProperties(java.lang.String value)
Decode properties from a String representation.void
parsePropertyString(java.lang.String value, java.util.Vector<java.lang.String> fragments, java.util.Vector<java.lang.String> propertyRefs)
Deprecated.use the other mechanisms of this class insteadjava.lang.String
replaceProperties(java.lang.String value)
Replaces${xxx}
style constructions in the given value with the string value of the corresponding data types.java.lang.String
replaceProperties(java.lang.String ns, java.lang.String value, java.util.Hashtable<java.lang.String,java.lang.Object> keys)
Replaces${xxx}
style constructions in the given value with the string value of the corresponding data types.void
setInheritedProperty(java.lang.String name, java.lang.Object value)
Sets an inherited user property, which cannot be overwritten by set/unset property calls.void
setInheritedProperty(java.lang.String ns, java.lang.String name, java.lang.Object value)
Deprecated.namespaces are unnecessary.static void
setNewProperty(Project project, java.lang.String name, java.lang.Object value)
A helper static method to set a new property from a particular project.void
setNewProperty(java.lang.String name, java.lang.Object value)
Sets a property if no value currently exists.void
setNewProperty(java.lang.String ns, java.lang.String name, java.lang.Object value)
Deprecated.namespaces are unnecessary.void
setNext(PropertyHelper next)
Deprecated.use the delegate mechanism insteadvoid
setProject(Project p)
Set the project for which this helper is performing property resolution.static void
setProperty(Project project, java.lang.String name, java.lang.Object value)
A helper static method to set a property from a particular project.boolean
setProperty(java.lang.String name, java.lang.Object value, boolean verbose)
Default implementation of setProperty.boolean
setProperty(java.lang.String ns, java.lang.String name, java.lang.Object value, boolean verbose)
Deprecated.namespaces are unnecessary.boolean
setPropertyHook(java.lang.String ns, java.lang.String name, java.lang.Object value, boolean inherited, boolean user, boolean isNew)
Deprecated.PropertyHelper chaining is deprecated.void
setUserProperty(java.lang.String name, java.lang.Object value)
Sets a user property, which cannot be overwritten by set/unset property calls.void
setUserProperty(java.lang.String ns, java.lang.String name, java.lang.Object value)
Deprecated.namespaces are unnecessary.boolean
testIfCondition(java.lang.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(java.lang.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 java.lang.Boolean
toBoolean(java.lang.Object value)
If the given object can be interpreted as a true/false value, turn it into a matching Boolean - otherwise return null.
Method Detail
getProperty
public static java.lang.Object getProperty(Project project, java.lang.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
setProperty
public static void setProperty(Project project, java.lang.String name, java.lang.Object value)A helper static method to set a property from a particular project.
- Parameters:
project
- the project in question.name
- the property namevalue
- the value to use.- Since:
- Ant 1.8.0
setNewProperty
public static void setNewProperty(Project project, java.lang.String name, java.lang.Object value)A helper static method to set a new property from a particular project.
- Parameters:
project
- the project in question.name
- the property namevalue
- the value to use.- 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.
getProject
public Project getProject()Get this PropertyHelper's Project.
- Returns:
- Project
setNext
@Deprecated public void setNext(PropertyHelper next)Deprecated. use the delegate mechanism insteadPrior to Ant 1.8.0 there have been 2 ways to hook into property handling: - you can replace the main PropertyHelper. The replacement is required to support the same semantics (of course :-) - you can chain a property helper capable of storing some properties. Again, you are required to respect the immutability semantics (at least for non-dynamic properties)As of Ant 1.8.0 this method is never invoked by any code inside of Ant itself.
- Parameters:
next
- the next property helper in the chain.
getNext
@Deprecated public PropertyHelper getNext()Deprecated. use the delegate mechanism insteadGet the next property helper in the chain.As of Ant 1.8.0 this method is never invoked by any code inside of Ant itself except the
setPropertyHook
andgetPropertyHook
methods in this class.
- Returns:
- the next property helper.
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.
getExpanders
public java.util.Collection<PropertyExpander> getExpanders()Get theexpanders
.
- Returns:
- the expanders.
- Since:
- Ant 1.8.0
setPropertyHook
@Deprecated public boolean setPropertyHook(java.lang.String ns, java.lang.String name, java.lang.Object value, boolean inherited, boolean user, boolean isNew)Deprecated. PropertyHelper chaining is deprecated.Sets a property. Any existing property of the same name is overwritten, unless it is a user property. If all helpers return false, the property will be saved in the default properties table by setProperty.As of Ant 1.8.0 this method is never invoked by any code inside of Ant itself.
- Parameters:
ns
- The namespace that the property is in (currently not used.name
- The name of property to set. Must not benull
.value
- The new value of the property. Must not benull
.inherited
- True if this property is inherited (an [sub]ant[call] property).user
- True if this property is a user property.isNew
- True is this is a new property.- Returns:
- true if this helper has stored the property, false if it couldn't. Each helper should delegate to the next one (unless it has a good reason not to).
getPropertyHook
@Deprecated public java.lang.Object getPropertyHook(java.lang.String ns, java.lang.String name, boolean user)Deprecated. PropertyHelper chaining is deprecated.Get a property. If all hooks return null, the default tables will be used.As of Ant 1.8.0 this method is never invoked by any code inside of Ant itself.
- Parameters:
ns
- namespace of the sought property.name
- name of the sought property.user
- True if this is a user property.- Returns:
- The property, if returned by a hook, or null if none.
parsePropertyString
@Deprecated public void parsePropertyString(java.lang.String value, java.util.Vector<java.lang.String> fragments, java.util.Vector<java.lang.String> propertyRefs) throws BuildExceptionDeprecated. use the other mechanisms of this class insteadParses a string containing${xxx}
style property references into two lists. The first list is a collection of text fragments, while the other is a set of string property names.null
entries in the first list indicate a property reference from the second list.Delegates to
parsePropertyStringDefault
.As of Ant 1.8.0 this method is never invoked by any code inside of Ant itself except {ProjectHelper#parsePropertyString ProjectHelper.parsePropertyString}.
- Parameters:
value
- Text to parse. Must not benull
.fragments
- List to add text fragments to. Must not benull
.propertyRefs
- List to add property names to. Must not benull
.- Throws:
BuildException
- if the string contains an opening${
without a closing}
replaceProperties
public java.lang.String replaceProperties(java.lang.String ns, java.lang.String value, java.util.Hashtable<java.lang.String,java.lang.Object> keys) throws BuildExceptionReplaces${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 benull
, in which case this method returns immediately with no effect.keys
- Mapping (String to Object) of property names to their values. Ifnull
, only project properties will be used.- Returns:
- the original string with the properties replaced, or
null
if the original string isnull
.- Throws:
BuildException
- if the string contains an opening${
without a closing}
replaceProperties
public java.lang.String replaceProperties(java.lang.String value) throws BuildExceptionReplaces${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 benull
, in which case this method returns immediately with no effect.- Returns:
- the original string with the properties replaced, or
null
if the original string isnull
.- Throws:
BuildException
- if the string contains an opening${
without a closing}
parseProperties
public java.lang.Object parseProperties(java.lang.String value) throws BuildExceptionDecode 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 benull
, in which case this method returns immediately with no effect.- Returns:
- the original string with the properties replaced, or
null
if the original string isnull
.- Throws:
BuildException
- if the string contains an opening${
without a closing}
containsProperties
public boolean containsProperties(java.lang.String value)Learn whether a String contains replaceable properties.
- Parameters:
value
- the String to check.- Returns:
true
ifvalue
contains property notation.
setProperty
@Deprecated public boolean setProperty(java.lang.String ns, java.lang.String name, java.lang.Object value, boolean verbose)Deprecated. namespaces are unnecessary.Default implementation of setProperty. Will be called from Project. This is the original 1.5 implementation, with calls to the hook added.Delegates to the three-arg version, completely ignoring the ns parameter.
- Parameters:
ns
- The namespace for the property (currently not used).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.
setProperty
public boolean setProperty(java.lang.String name, java.lang.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.
setNewProperty
@Deprecated public void setNewProperty(java.lang.String ns, java.lang.String name, java.lang.Object value)Deprecated. namespaces are unnecessary.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.Delegates to the two-arg version, completely ignoring the ns parameter.
- Parameters:
ns
- The namespace for the property (currently not used).name
- The name of property to set. Must not benull
.value
- The new value of the property. Must not benull
.- Since:
- Ant 1.6
setNewProperty
public void setNewProperty(java.lang.String name, java.lang.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 benull
.value
- The new value of the property. Must not benull
.- Since:
- Ant 1.8.0
setUserProperty
@Deprecated public void setUserProperty(java.lang.String ns, java.lang.String name, java.lang.Object value)Deprecated. namespaces are unnecessary.Sets a user property, which cannot be overwritten by set/unset property calls. Any previous value is overwritten.Delegates to the two-arg version, completely ignoring the ns parameter.
- Parameters:
ns
- The namespace for the property (currently not used).name
- The name of property to set. Must not benull
.value
- The new value of the property. Must not benull
.
setUserProperty
public void setUserProperty(java.lang.String name, java.lang.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 benull
.value
- The new value of the property. Must not benull
.
setInheritedProperty
@Deprecated public void setInheritedProperty(java.lang.String ns, java.lang.String name, java.lang.Object value)Deprecated. namespaces are unnecessary.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.Delegates to the two-arg version, completely ignoring the ns parameter.
- Parameters:
ns
- The namespace for the property (currently not used).name
- The name of property to set. Must not benull
.value
- The new value of the property. Must not benull
.
setInheritedProperty
public void setInheritedProperty(java.lang.String name, java.lang.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 benull
.value
- The new value of the property. Must not benull
.
getProperty
@Deprecated public java.lang.Object getProperty(java.lang.String ns, java.lang.String name)Deprecated. namespaces are unnecessary.Returns the value of a property, if it is set. You can override this method in order to plug your own storage.Delegates to the one-arg version ignoring the ns parameter.
- Parameters:
ns
- The namespace for the property (currently not used).name
- The name of the property. May benull
, in which case the return value is alsonull
.- Returns:
- the property value, or
null
for no match or if anull
name is provided.
getProperty
public java.lang.Object getProperty(java.lang.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 interfaceGetProperty
- Parameters:
name
- The name of the property. May benull
, in which case the return value is alsonull
.- Returns:
- the property value, or
null
for no match or if anull
name is provided.
getUserProperty
@Deprecated public java.lang.Object getUserProperty(java.lang.String ns, java.lang.String name)Deprecated. namespaces are unnecessary.Returns the value of a user property, if it is set.Delegates to the one-arg version ignoring the ns parameter.
- Parameters:
ns
- The namespace for the property (currently not used).name
- The name of the property. May benull
, in which case the return value is alsonull
.- Returns:
- the property value, or
null
for no match or if anull
name is provided.
getUserProperty
public java.lang.Object getUserProperty(java.lang.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 benull
, in which case the return value is alsonull
.- Returns:
- the property value, or
null
for no match or if anull
name is provided.
getProperties
public java.util.Hashtable<java.lang.String,java.lang.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).
getUserProperties
public java.util.Hashtable<java.lang.String,java.lang.Object> getUserProperties()Returns a copy of the user property hashtableDoes not contain properties held by implementations of delegates (like local properties).
- Returns:
- a hashtable containing just the user properties
getInheritedProperties
public java.util.Hashtable<java.lang.String,java.lang.Object> getInheritedProperties()Returns a copy of the inherited property hashtableDoes not contain properties held by implementations of delegates (like local properties).
- Returns:
- a hashtable containing just the inherited properties
getInternalProperties
protected java.util.Hashtable<java.lang.String,java.lang.Object> getInternalProperties()special back door for subclasses, internal access to the hashtables
- Returns:
- the live hashtable of all properties
getInternalUserProperties
protected java.util.Hashtable<java.lang.String,java.lang.Object> getInternalUserProperties()special back door for subclasses, internal access to the hashtables
- Returns:
- the live hashtable of user properties
getInternalInheritedProperties
protected java.util.Hashtable<java.lang.String,java.lang.Object> getInternalInheritedProperties()special back door for subclasses, internal access to the hashtables
- Returns:
- the live hashtable inherited properties
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
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
getDelegates
protected <D extends PropertyHelper.Delegate> java.util.List<D> getDelegates(java.lang.Class<D> type)Get the Collection of delegates of the specified type.
- Type Parameters:
D
- desired type.- Parameters:
type
- delegate type.- Returns:
- Collection.
- Since:
- Ant 1.8.0
getDelegateInterfaces
protected static java.util.Set<java.lang.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
toBoolean
public static java.lang.Boolean toBoolean(java.lang.Object value)If the given object can be interpreted as a true/false value, turn it into a matching Boolean - otherwise return null.
- Parameters:
value
- Object- Returns:
- Boolean
- Since:
- Ant 1.8.0
testIfCondition
public boolean testIfCondition(java.lang.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.
- Parameters:
value
- Object- Returns:
- boolean
- Since:
- Ant 1.8.0
testUnlessCondition
public boolean testUnlessCondition(java.lang.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.
- Parameters:
value
- Object- Returns:
- boolean
- Since:
- Ant 1.8.0