Class PropertyHelper
- All Implemented Interfaces:
- 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 property 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 SummaryNested ClassesModifier and TypeClassDescriptionstatic interfaceMarker interface for a PropertyHelper delegate.static interfaceObtains the names of all known properties.static interfaceLooks up a property's value based on its name.static interfaceSets or overrides a property.
- 
Constructor SummaryConstructors
- 
Method SummaryModifier and TypeMethodDescriptionvoidadd(PropertyHelper.Delegate delegate) Add the specified delegate object to this PropertyHelper.booleancontainsProperties(String value) Learn whether a String contains replaceable properties.voidcopyInheritedProperties(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.voidcopyUserProperties(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>> 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.Get theexpanders.Returns a copy of the inherited property hashtablespecial back door for subclasses, internal access to the hashtablesspecial back door for subclasses, internal access to the hashtablesspecial back door for subclasses, internal access to the hashtablesgetNext()Deprecated.use the delegate mechanism insteadGet this PropertyHelper's Project.Returns a copy of the properties table.getProperty(String name) Returns the value of a property, if it is set.getProperty(String ns, String name) Deprecated.namespaces are unnecessary.static ObjectgetProperty(Project project, String name) A helper static method to get a property from a particular project.static PropertyHelpergetPropertyHelper(Project project) Factory method to create a property processor.getPropertyHook(String ns, String name, boolean user) Deprecated.PropertyHelper chaining is deprecated.Returns the names of all known properties.Returns a copy of the user property hashtablegetUserProperty(String name) Returns the value of a user property, if it is set.getUserProperty(String ns, String name) Deprecated.namespaces are unnecessary.parseProperties(String value) Decode properties from a String representation.voidDeprecated.use the other mechanisms of this class insteadreplaceProperties(String value) Replaces${xxx}style constructions in the given value with the string value of the corresponding data types.Replaces${xxx}style constructions in the given value with the string value of the corresponding data types.voidsetInheritedProperty(String name, Object value) Sets an inherited user property, which cannot be overwritten by set/unset property calls.voidsetInheritedProperty(String ns, String name, Object value) Deprecated.namespaces are unnecessary.voidsetNewProperty(String name, Object value) Sets a property if no value currently exists.voidsetNewProperty(String ns, String name, Object value) Deprecated.namespaces are unnecessary.static voidsetNewProperty(Project project, String name, Object value) A helper static method to set a new property from a particular project.voidsetNext(PropertyHelper next) Deprecated.use the delegate mechanism insteadvoidSet the project for which this helper is performing property resolution.booleansetProperty(String name, Object value, boolean verbose) Default implementation of setProperty.booleansetProperty(String ns, String name, Object value, boolean verbose) Deprecated.namespaces are unnecessary.static voidsetProperty(Project project, String name, Object value) A helper static method to set a property from a particular project.booleansetPropertyHook(String ns, String name, Object value, boolean inherited, boolean user, boolean isNew) Deprecated.PropertyHelper chaining is deprecated.voidsetUserProperty(String name, Object value) Sets a user property, which cannot be overwritten by set/unset property calls.voidsetUserProperty(String ns, String name, Object value) Deprecated.namespaces are unnecessary.booleantestIfCondition(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.booleantestUnlessCondition(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 BooleanIf the given object can be interpreted as a true/false value, turn it into a matching Boolean - otherwise return null.
- 
Constructor Details- 
PropertyHelperprotected PropertyHelper()Default constructor.
 
- 
- 
Method Details- 
getProperty
- 
setProperty
- 
setNewProperty
- 
setProjectSet the project for which this helper is performing property resolution.- Parameters:
- p- the project instance.
 
- 
getProject
- 
setNextDeprecated.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.
 
- 
getNextDeprecated.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 setPropertyHookandgetPropertyHookmethods in this class.- Returns:
- the next property helper.
 
- 
getPropertyHelperFactory 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.
 
- 
getExpandersGet theexpanders.- Returns:
- the expanders.
- Since:
- Ant 1.8.0
 
- 
setPropertyHook@Deprecated public boolean setPropertyHook(String ns, String name, 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 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).
 
- 
getPropertyHookDeprecated.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(String value, Vector<String> fragments, Vector<String> propertyRefs) throws BuildException Deprecated.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.nullentries 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- }
 
- 
replacePropertiespublic String replaceProperties(String ns, String value, Hashtable<String, 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 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
         nullif the original string isnull.
- Throws:
- BuildException- if the string contains an opening- ${without a closing- }
 
- 
replacePropertiesReplaces${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
         nullif the original string isnull.
- Throws:
- BuildException- if the string contains an opening- ${without a closing- }
 
- 
parsePropertiesDecode 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
         nullif the original string isnull.
- Throws:
- BuildException- if the string contains an opening- ${without a closing- }
 
- 
containsPropertiesLearn whether a String contains replaceable properties.- Parameters:
- value- the String to check.
- Returns:
- trueif- valuecontains property notation.
 
- 
setPropertyDeprecated.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.
 
- 
setPropertyDefault 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.
 
- 
setNewPropertyDeprecated.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
 
- 
setNewPropertySets 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
 
- 
setUserPropertyDeprecated.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.
 
- 
setUserPropertySets a user property, which cannot be overwritten by set/unset property calls. Any previous value is overwritten.Does notconsult 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.
 
- 
setInheritedPropertyDeprecated.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.
 
- 
setInheritedPropertySets 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 notconsult 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.
 
- 
getPropertyDeprecated.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 nullfor no match or if anullname is provided.
 
- 
getPropertyReturns 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 PropertyEvaluatorinstead.- Specified by:
- getPropertyin 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 nullfor no match or if anullname is provided.
 
- 
getPropertyNames
- 
getUserPropertyDeprecated.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 nullfor no match or if anullname is provided.
 
- 
getUserPropertyReturns the value of a user property, if it is set.Does notconsult 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 nullfor no match or if anullname is provided.
 
- 
getProperties
- 
getUserProperties
- 
getInheritedProperties
- 
getInternalProperties
- 
getInternalUserProperties
- 
getInternalInheritedProperties
- 
copyInheritedPropertiesCopies 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
 
- 
copyUserPropertiesCopies 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
 
- 
addAdd the specified delegate object to this PropertyHelper. Delegates are processed in LIFO order.- Parameters:
- delegate- the delegate to add.
- Since:
- Ant 1.8.0
 
- 
getDelegatesGet the Collection of delegates of the specified type.- Type Parameters:
- D- desired type.
- Parameters:
- type- delegate type.
- Returns:
- Collection.
- Since:
- Ant 1.8.0
 
- 
getDelegateInterfacesprotected 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
 
- 
toBoolean
- 
testIfConditionReturns 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
 
- 
testUnlessConditionReturns 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
 
 
-