NOT FINAL. API MAY CHANGE
Deals with properties - substitution, dynamic properties, etc.
This is the same code as in Ant1.5. The main addition is the ability
to chain multiple PropertyHelpers and to replace the default.
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
.
other
- the project to copy the properties to. Must not be null.
- 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
.
other
- the project to copy the properties to. Must not be null.
- Ant 1.6
getNext
public PropertyHelper getNext()
Get the next property helper in the chain.
- the next property helper.
getProperties
public Hashtable getProperties()
Returns a copy of the properties table.
- a hashtable containing all properties
(including user properties).
getProperty
public Object getProperty(String ns,
String name)
Returns the value of a property, if it is set. You can override
this method in order to plug your own storage.
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
.
- 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.
project
- the project fro which the property helper is required.
- the project's property helper.
getPropertyHook
public Object getPropertyHook(String ns,
String name,
boolean user)
Get a property. If all hooks return null, the default
tables will be used.
ns
- namespace of the sought property.name
- name of the sought property.user
- True if this is a user property.
- The property, if returned by a hook, or null if none.
getUserProperties
public Hashtable getUserProperties()
Returns a copy of the user property hashtable
- a hashtable containing just the user properties
getUserProperty
public Object getUserProperty(String ns,
String name)
Returns the value of a user property, if it is set.
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
.
- the property value, or
null
for no match
or if a null
name is provided.
parsePropertyString
public void parsePropertyString(String value,
Vector fragments,
Vector propertyRefs)
throws BuildException
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.
It can be overridden with a more efficient or customized version.
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
}
replaceProperties
public String replaceProperties(String ns,
String value,
Hashtable keys)
throws BuildException
Replaces ${xxx}
style constructions in the given value
with the string value of the corresponding data types.
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.
- the original string with the properties replaced, or
null
if the original string is null
.
BuildException
- if the string contains an opening
${
without a closing
}
setInheritedProperty
public void setInheritedProperty(String ns,
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.
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
.
setNewProperty
public void setNewProperty(String ns,
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.
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
.
- Ant 1.6
setNext
public void setNext(PropertyHelper next)
There are 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)
next
- the next property helper in the chain.
setProject
public void setProject(Project p)
Set the project for which this helper is performing property resolution
p
- the project instance.
setProperty
public boolean setProperty(String ns,
String name,
Object value,
boolean verbose)
Default implementation of setProperty. Will be called from Project.
This is the original 1.5 implementation, with calls to the hook
added.
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.
- true if the property is set.
setPropertyHook
public boolean setPropertyHook(String ns,
String name,
Object value,
boolean inherited,
boolean user,
boolean isNew)
Sets a property. Any existing property of the same name
is overwritten, unless it is a user property. Will be called
from setProperty().
If all helpers return false, the property will be saved in
the default properties table by setProperty.
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.
- 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).
setUserProperty
public void setUserProperty(String ns,
String name,
Object value)
Sets a user property, which cannot be overwritten by
set/unset property calls. Any previous value is overwritten.
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
.