org.apache.tools.ant
public class PropertyHelper extends Object implements GetProperty
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 | |
---|---|
interface | PropertyHelper.Delegate
Marker interface for a PropertyHelper delegate. |
interface | PropertyHelper.PropertyEvaluator
Looks up a property's value based on its name.
|
interface | PropertyHelper.PropertySetter
Sets or overrides a property.
|
Constructor Summary | |
---|---|
protected | PropertyHelper()
Default constructor. |
Method Summary | |
---|---|
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 | getDelegateInterfaces(PropertyHelper.Delegate d)
Get all Delegate interfaces (excluding Delegate itself) from the specified Delegate. |
protected List | getDelegates(Class type)
Get the Collection of delegates of the specified type.
|
Collection | getExpanders()
Get the expanders . |
Hashtable | getInheritedProperties()
Returns a copy of the inherited property hashtable
Does not contain properties held by implementations of delegates (like local properties). |
protected Hashtable | getInternalInheritedProperties()
special back door for subclasses, internal access to the hashtables
|
protected Hashtable | getInternalProperties()
special back door for subclasses, internal access to the hashtables |
protected Hashtable | getInternalUserProperties()
special back door for subclasses, internal access to the hashtables
|
PropertyHelper | getNext()
Get the next property helper in the chain.
|
Project | getProject()
Get this PropertyHelper's Project. |
Hashtable | 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 ns, String name)
Returns the value of a property, if it is set. |
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.
|
Object | getPropertyHook(String ns, String name, boolean user)
Get a property. |
Hashtable | getUserProperties()
Returns a copy of the user property hashtable
Does not contain properties held by implementations of delegates (like local properties). |
Object | getUserProperty(String ns, String name)
Returns the value of a user property, if it is set.
|
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. |
void | parsePropertyString(String value, Vector fragments, Vector propertyRefs)
Parses a string containing ${xxx} style property
references into two lists. |
String | replaceProperties(String ns, String value, Hashtable keys)
Replaces ${xxx} style constructions in the given value
with the string value of the corresponding data types.
|
String | replaceProperties(String value)
Replaces ${xxx} style constructions in the given value
with the string value of the corresponding data types.
|
void | setInheritedProperty(String ns, String name, Object value)
Sets an inherited user property, which cannot be overwritten by set/unset
property calls. |
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 ns, String name, Object value)
Sets a property if no value currently exists. |
void | setNewProperty(String name, Object value)
Sets a property if no value currently exists. |
void | setNext(PropertyHelper next)
Prior to Ant 1.8.0 there have been 2 ways to hook into property handling:
- you can replace the main PropertyHelper. |
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 ns, String name, Object value, boolean verbose)
Default implementation of setProperty. |
boolean | setProperty(String name, Object value, boolean verbose)
Default implementation of setProperty. |
boolean | setPropertyHook(String ns, String name, Object value, boolean inherited, boolean user, boolean isNew)
Sets a property. |
void | setUserProperty(String ns, String name, Object value)
Sets a user property, which cannot be overwritten by
set/unset property calls. |
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. |
Parameters: delegate the delegate to add.
Since: Ant 1.8.0
Parameters: value the String to check.
Returns: true
if value
contains property notation.
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
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
Parameters: d the Delegate to inspect.
Returns: Set
Since: Ant 1.8.0
Parameters: type delegate type.
Returns: Collection.
Since: Ant 1.8.0
Does not contain properties held by implementations of delegates (like local properties).
Returns: a hashtable containing just the inherited properties
Returns: the live hashtable inherited properties
Returns: the live hashtable of all properties
Returns: the live hashtable of user properties
Deprecated: use the delegate mechanism instead
Get 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
and getPropertyHook
methods in this class.
Returns: the next property helper.
Returns: Project
Does not contain properties held by implementations of delegates (like local properties).
Returns: a hashtable containing all properties (including user properties).
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
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 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.
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.
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.
Parameters: project the project for which the property helper is required.
Returns: the project's property helper.
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.
Does not contain properties held by implementations of delegates (like local properties).
Returns: a hashtable containing just the user properties
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 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.
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.
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
}
Deprecated: use the other mechanisms of this class instead
Parses 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 be null
. fragments List to add text fragments to.
Must not be null
. propertyRefs List to add property names to.
Must not be null
.
Throws: BuildException if the string contains an opening
${
without a closing
}
${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 String) 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
}
${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
}
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 be null
. value The new value of the property.
Must not be null
.
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
.
Parameters: project the project in question. name the property name value the value to use.
Since: Ant 1.8.0
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 be null
. value The new value of the property.
Must not be null
.
Since: Ant 1.6
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
Deprecated: use the delegate mechanism instead
Prior 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.
Parameters: p the project instance.
Parameters: project the project in question. name the property name value the value to use.
Since: Ant 1.8.0
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.
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.
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 be null
. value The new value of the property.
Must not be null
. 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).
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 be null
. value The new value of the property.
Must not be null
.
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
.
Since: Ant 1.8.0
Since: Ant 1.8.0
Since: Ant 1.8.0