public class PropertyHelper extends java.lang.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.
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.
|
Modifier | Constructor and Description |
---|---|
protected |
PropertyHelper()
Default constructor.
|
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 |
getDelegateInterfaces(PropertyHelper.Delegate d)
Get all Delegate interfaces (excluding Delegate itself) from the specified Delegate.
|
protected java.util.List |
getDelegates(java.lang.Class type)
Get the Collection of delegates of the specified type.
|
java.util.Collection |
getExpanders()
Get the
expanders . |
java.util.Hashtable |
getInheritedProperties()
Returns a copy of the inherited property hashtable
|
protected java.util.Hashtable |
getInternalInheritedProperties()
special back door for subclasses, internal access to the hashtables
|
protected java.util.Hashtable |
getInternalProperties()
special back door for subclasses, internal access to the hashtables
|
protected java.util.Hashtable |
getInternalUserProperties()
special back door for subclasses, internal access to the hashtables
|
PropertyHelper |
getNext()
Deprecated.
use the delegate mechanism instead
|
Project |
getProject()
Get this PropertyHelper's Project.
|
java.util.Hashtable |
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 |
getUserProperties()
Returns a copy of the user property hashtable
|
java.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 fragments,
java.util.Vector propertyRefs)
Deprecated.
use the other mechanisms of this class instead
|
java.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 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 instead
|
void |
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.
|
public static java.lang.Object getProperty(Project project, java.lang.String name)
project
- the project in question.name
- the property namepublic static void setProperty(Project project, java.lang.String name, java.lang.Object value)
project
- the project in question.name
- the property namevalue
- the value to use.public static void setNewProperty(Project project, java.lang.String name, java.lang.Object value)
project
- the project in question.name
- the property namevalue
- the value to use.public void setProject(Project p)
p
- the project instance.public Project getProject()
public void setNext(PropertyHelper next)
As of Ant 1.8.0 this method is never invoked by any code inside of Ant itself.
next
- the next property helper in the chain.public PropertyHelper getNext()
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.
public static PropertyHelper getPropertyHelper(Project project)
project
- the project for which the property helper is required.public java.util.Collection getExpanders()
expanders
.public boolean setPropertyHook(java.lang.String ns, java.lang.String name, java.lang.Object value, boolean inherited, boolean user, boolean isNew)
As of Ant 1.8.0 this method is never invoked by any code inside of Ant itself.
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.public java.lang.Object getPropertyHook(java.lang.String ns, java.lang.String name, boolean user)
As of Ant 1.8.0 this method is never invoked by any code inside of Ant itself.
ns
- namespace of the sought property.name
- name of the sought property.user
- True if this is a user property.public void parsePropertyString(java.lang.String value, java.util.Vector fragments, java.util.Vector propertyRefs) throws BuildException
${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}.
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
.BuildException
- if the string contains an opening
${
without a closing
}
public java.lang.String replaceProperties(java.lang.String ns, java.lang.String value, java.util.Hashtable keys) throws BuildException
${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.
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.null
if the original string is null
.BuildException
- if the string contains an opening
${
without a closing
}
public java.lang.String replaceProperties(java.lang.String value) throws BuildException
${xxx}
style constructions in the given value
with the string value of the corresponding data types.value
- The string to be scanned for property references.
May be null
, in which case this
method returns immediately with no effect.null
if the original string is null
.BuildException
- if the string contains an opening
${
without a closing
}
public java.lang.Object parseProperties(java.lang.String value) throws BuildException
value
- The string to be scanned for property references.
May be null
, in which case this
method returns immediately with no effect.null
if the original string is null
.BuildException
- if the string contains an opening
${
without a closing
}
public boolean containsProperties(java.lang.String value)
value
- the String to check.true
if value
contains property notation.public boolean setProperty(java.lang.String ns, java.lang.String name, java.lang.Object value, boolean verbose)
Delegates to the three-arg version, completely ignoring the ns parameter.
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.public boolean setProperty(java.lang.String name, java.lang.Object value, boolean verbose)
name
- The name of the property.value
- The value to set the property to.verbose
- If this is true output extra log messages.public void setNewProperty(java.lang.String ns, java.lang.String name, java.lang.Object value)
Delegates to the two-arg version, completely ignoring the ns parameter.
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
.public void setNewProperty(java.lang.String name, java.lang.Object value)
name
- The name of property to set.
Must not be null
.value
- The new value of the property.
Must not be null
.public void setUserProperty(java.lang.String ns, java.lang.String name, java.lang.Object value)
Delegates to the two-arg version, completely ignoring the ns parameter.
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
.public void setUserProperty(java.lang.String name, java.lang.Object value)
Does not
consult any delegates.
name
- The name of property to set.
Must not be null
.value
- The new value of the property.
Must not be null
.public void setInheritedProperty(java.lang.String ns, java.lang.String name, java.lang.Object value)
Delegates to the two-arg version, completely ignoring the ns parameter.
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
.public void setInheritedProperty(java.lang.String name, java.lang.Object value)
Does not
consult any delegates.
name
- The name of property to set.
Must not be null
.value
- The new value of the property.
Must not be null
.public java.lang.Object getProperty(java.lang.String ns, java.lang.String name)
Delegates to the one-arg version ignoring the ns parameter.
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
.null
for no match
or if a null
name is provided.public java.lang.Object getProperty(java.lang.String name)
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.
getProperty
in interface GetProperty
name
- The name of the property.
May be null
, in which case
the return value is also null
.null
for no match
or if a null
name is provided.public java.lang.Object getUserProperty(java.lang.String ns, java.lang.String name)
Delegates to the one-arg version ignoring the ns parameter.
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
.null
for no match
or if a null
name is provided.public java.lang.Object getUserProperty(java.lang.String name)
Does not
consult any delegates.
name
- The name of the property.
May be null
, in which case
the return value is also null
.null
for no match
or if a null
name is provided.public java.util.Hashtable getProperties()
Does not contain properties held by implementations of delegates (like local properties).
public java.util.Hashtable getUserProperties()
Does not contain properties held by implementations of delegates (like local properties).
public java.util.Hashtable getInheritedProperties()
Does not contain properties held by implementations of delegates (like local properties).
protected java.util.Hashtable getInternalProperties()
protected java.util.Hashtable getInternalUserProperties()
protected java.util.Hashtable getInternalInheritedProperties()
public void copyInheritedProperties(Project other)
To copy all "user" properties, you will also have to call
copyUserProperties
.
Does not copy properties held by implementations of delegates (like local properties).
other
- the project to copy the properties to. Must not be null.public void copyUserProperties(Project other)
To copy all "user" properties, you will also have to call
copyInheritedProperties
.
Does not copy properties held by implementations of delegates (like local properties).
other
- the project to copy the properties to. Must not be null.public void add(PropertyHelper.Delegate delegate)
delegate
- the delegate to add.protected java.util.List getDelegates(java.lang.Class type)
type
- delegate type.protected static java.util.Set getDelegateInterfaces(PropertyHelper.Delegate d)
d
- the Delegate to inspect.public static java.lang.Boolean toBoolean(java.lang.Object value)
public boolean testIfCondition(java.lang.Object value)
public boolean testUnlessCondition(java.lang.Object value)