PropertyHelper (Apache Ant API)
Date: 2008-06-27

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.tools.ant
Class PropertyHelper

    java.lang.Object
      org.apache.tools.ant.PropertyHelper

    public class PropertyHelper

extends java.lang.Object

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.

Since:
  Ant 1.6

Constructor Summary
`protected` | `PropertyHelper()` Default constructor.

Method Summary
`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 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()` Get the next property helper in the chain.
`Project` | `getProject()` Get this PropertyHelper's Project.
`java.util.Hashtable` | `getProperties()` Returns a copy of the properties table.
`java.lang.Object` | `getProperty(java.lang.String ns, java.lang.String name)` Returns the value of a property, if it is set.
`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)` Get a property.
`java.util.Hashtable` | `getUserProperties()` Returns a copy of the user property hashtable
`java.lang.Object` | `getUserProperty(java.lang.String ns, java.lang.String name)` Returns the value of a user property, if it is set.
`void` | `parsePropertyString(java.lang.String value, java.util.Vector fragments, java.util.Vector propertyRefs)` Parses a string containing `${xxx}` style property references into two lists.
`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 ns, java.lang.String name, java.lang.Object value)` Sets an inherited user property, which cannot be overwritten by set/unset property calls.
`void` | `setNewProperty(java.lang.String ns, java.lang.String name, java.lang.Object value)` Sets a property if no value currently exists.
`void` | `setNext(PropertyHelper next)` There are 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.
`boolean` | `setProperty(java.lang.String ns, java.lang.String name, java.lang.Object value, boolean verbose)` Default implementation of setProperty.
`boolean` | `setPropertyHook(java.lang.String ns, java.lang.String name, java.lang.Object value, boolean inherited, boolean user, boolean isNew)` Sets a property.
`void` | `setUserProperty(java.lang.String ns, java.lang.String name, java.lang.Object value)` Sets a user property, which cannot be overwritten by set/unset property calls.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### PropertyHelper

    protected PropertyHelper()

  Default constructor.

Method Detail

### 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

    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)

  Parameters:
    `next` - the next property helper in the chain.

### getNext

    public PropertyHelper getNext()

  Get the next property helper in the chain.

  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.

### setPropertyHook

    public boolean setPropertyHook(java.lang.String ns,
                                   java.lang.String name,
                                   java.lang.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.

  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).

### getPropertyHook

    public java.lang.Object getPropertyHook(java.lang.String ns,
                                            java.lang.String name,
                                            boolean user)

  Get a property. If all hooks return null, the default tables will be used.

  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

    public void parsePropertyString(java.lang.String value,
                                    java.util.Vector fragments,
                                    java.util.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.

  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 `}`

### replaceProperties

    public java.lang.String replaceProperties(java.lang.String ns,
                                              java.lang.String value,
                                              java.util.Hashtable keys)
                                       throws BuildException

  Replaces `${xxx}` style constructions in the given value with the string value of the corresponding data types.

  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 `}`

### setProperty

    public boolean setProperty(java.lang.String ns,
                               java.lang.String name,
                               java.lang.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.

  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.

### setNewProperty

    public void setNewProperty(java.lang.String ns,
                               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:
    `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

### setUserProperty

    public void setUserProperty(java.lang.String ns,
                                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.

  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`.

### setInheritedProperty

    public void setInheritedProperty(java.lang.String ns,
                                     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.

  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`.

### getProperty

    public java.lang.Object getProperty(java.lang.String ns,
                                        java.lang.String name)

  Returns the value of a property, if it is set. You can override this method in order to plug your own storage.

  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.

### getUserProperty

    public java.lang.Object getUserProperty(java.lang.String ns,
                                            java.lang.String name)

  Returns the value of a user property, if it is set.

  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.

### getProperties

    public java.util.Hashtable getProperties()

  Returns a copy of the properties table.

  Returns:
    a hashtable containing all properties (including user properties).

### getUserProperties

    public java.util.Hashtable getUserProperties()

  Returns a copy of the user property hashtable

  Returns:
    a hashtable containing just the user properties

### getInternalProperties

    protected java.util.Hashtable getInternalProperties()

  special back door for subclasses, internal access to the hashtables

  Returns:
    the live hashtable of all properties

### getInternalUserProperties

    protected java.util.Hashtable getInternalUserProperties()

  special back door for subclasses, internal access to the hashtables

  Returns:
    the live hashtable of user properties

### getInternalInheritedProperties

    protected java.util.Hashtable 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`.

  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`.

  Parameters:
    `other` - the project to copy the properties to. Must not be null.
  Since:
    Ant 1.6

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD