## org.apache.commons.configuration
Class HierarchicalConfiguration

    java.lang.Object
      org.apache.commons.configuration.event.EventSource
          org.apache.commons.configuration.AbstractConfiguration
              org.apache.commons.configuration.HierarchicalConfiguration

All Implemented Interfaces:
  Serializable, Cloneable, Configuration

Direct Known Subclasses:
  AbstractHierarchicalFileConfiguration, CombinedConfiguration, SubnodeConfiguration

    public class HierarchicalConfiguration

extends AbstractConfiguration
implements Serializable, Cloneable

A specialized configuration class that extends its base class by the ability of keeping more structure in the stored properties.

There are some sources of configuration data that cannot be stored very well in a `BaseConfiguration` object because then their structure is lost. This is especially true for XML documents. This class can deal with such structured configuration sources by storing the properties in a tree-like organization.

The internal used storage form allows for a more sophisticated access to single properties. As an example consider the following XML document:

     <database>
       <tables>
         <table>
           <name>users</name>
           <fields>
             <field>
               <name>lid</name>
               <type>long</name>
             </field>
             <field>
               <name>usrName</name>
               <type>java.lang.String</type>
             </field>
            ...
           </fields>
         </table>
         <table>
           <name>documents</name>
           <fields>
             <field>
               <name>docid</name>
               <type>long</type>
             </field>
             ...
           </fields>
         </table>
         ...
       </tables>
     </database>

If this document is parsed and stored in a `HierarchicalConfiguration` object (which can be done by one of the sub classes), there are enhanced possibilities of accessing properties. The keys for querying information can contain indices that select a certain element if there are multiple hits.

For instance the key `tables.table(0).name` can be used to find out the name of the first table. In opposite `tables.table.name` would return a collection with the names of all available tables. Similarily the key `tables.table(1).fields.field.name` returns a collection with the names of all fields of the second table. If another index is added after the `field` element, a single field can be accessed: `tables.table(1).fields.field(0).name`.

There is a `getMaxIndex()` method that returns the maximum allowed index that can be added to a given property key. This method can be used to iterate over all values defined for a certain property.

Version:
  $Id: HierarchicalConfiguration.java,v 1.14 2004/12/02 22:05:52 ebourg Exp $
Author:
  Oliver Heger
See Also:
  Serialized Form

Nested Class Summary
`protected static class` `HierarchicalConfiguration.BuilderVisitor` A specialized visitor base class that can be used for storing the tree of configuration nodes.
`(package private) static class` `HierarchicalConfiguration.CloneVisitor` A specialized visitor that is able to create a deep copy of a node hierarchy.
`(package private) class` `HierarchicalConfiguration.DefinedKeysVisitor` A specialized visitor that fills a list with keys that are defined in a node hierarchy.
`(package private) static class` `HierarchicalConfiguration.DefinedVisitor` A specialized visitor that checks if a node is defined.
`static class` `HierarchicalConfiguration.Node` A data class for storing (hierarchical) property information.
`static class` `HierarchicalConfiguration.NodeVisitor` Definition of a visitor class for traversing a node and all of its children.

Field Summary
`static int` `EVENT_ADD_NODES` Constant for the add nodes event.
`static int` `EVENT_CLEAR_TREE` Constant for the clear tree event.

Fields inherited from class org.apache.commons.configuration.AbstractConfiguration
`END_TOKEN, EVENT_ADD_PROPERTY, EVENT_CLEAR, EVENT_CLEAR_PROPERTY, EVENT_SET_PROPERTY, START_TOKEN`

Constructor Summary
`HierarchicalConfiguration()` Creates a new instance of `HierarchicalConfiguration`.

Method Summary
`void` `addNodes(String key, Collection nodes)` Adds a collection of nodes at the specified position of the configuration tree.
`protected void` `addPropertyDirect(String key, Object obj)` Adds the property with the specified key.
`protected void` `clearNode(ConfigurationNode node)` Clears the value of the specified node.
`protected void` `clearNode(HierarchicalConfiguration.Node node)` Deprecated. Use the method ``clearNode(ConfigurationNode)`` instead
`void` `clearProperty(String key)` Removes the property with the given key.
`void` `clearTree(String key)` Removes all values of the property with the given name and of keys that start with this name.
`Object` `clone()` Creates a copy of this object.
`SubnodeConfiguration` `configurationAt(String key)` Returns a hierarchical subnode configuration object that wraps the configuration node specified by the given key.
`List` `configurationsAt(String key)` Returns a list of sub configurations for all configuration nodes selected by the given key.
`boolean` `containsKey(String key)` Checks if the specified key is contained in this configuration.

`protected HierarchicalConfiguration.Node`

`createAddPath(ConfigurationKey.KeyIterator keyIt, HierarchicalConfiguration.Node root)`
Deprecated. Adding new properties is now to a major part delegated to the `ExpressionEngine` associated with this configuration instance. This method will no longer be called. Developers who want to modify the process of adding new properties should consider implementing their own expression engine.

`protected HierarchicalConfiguration.Node` `createNode(String name)` Creates a new `Node` object with the specified name.
`protected SubnodeConfiguration` `createSubnodeConfiguration(ConfigurationNode node)` Creates a subnode configuration for the specified node.

`protected HierarchicalConfiguration.Node`

`fetchAddNode(ConfigurationKey.KeyIterator keyIt, HierarchicalConfiguration.Node startNode)`
Deprecated. Adding new properties is now to a major part delegated to the `ExpressionEngine` associated with this configuration instance. This method will no longer be called. Developers who want to modify the process of adding new properties should consider implementing their own expression engine.

`protected List` `fetchNodeList(String key)` Helper method for fetching a list of all nodes that are addressed by the specified key.

`protected HierarchicalConfiguration.Node`

`findLastPathNode(ConfigurationKey.KeyIterator keyIt, HierarchicalConfiguration.Node node)`
Deprecated. Adding new properties is now to a major part delegated to the `ExpressionEngine` associated with this configuration instance. This method will no longer be called. Developers who want to modify the process of adding new properties should consider implementing their own expression engine.

`protected void` `findPropertyNodes(ConfigurationKey.KeyIterator keyPart, HierarchicalConfiguration.Node node, Collection nodes)` Deprecated. Property keys are now evaluated by the expression engine associated with the configuration; this method will no longer be called. If you want to modify the way properties are looked up, consider implementing you own `ExpressionEngine` implementation.
`static ExpressionEngine` `getDefaultExpressionEngine()` Returns the default expression engine.
`ExpressionEngine` `getExpressionEngine()` Returns the expression engine used by this configuration.
`Iterator` `getKeys()` Returns an iterator with all keys defined in this configuration.
`Iterator` `getKeys(String prefix)` Returns an iterator with all keys defined in this configuration that start with the given prefix.
`int` `getMaxIndex(String key)` Returns the maximum defined index for the given key.
`Object` `getProperty(String key)` Fetches the specified property.
`HierarchicalConfiguration.Node` `getRoot()` Returns the root node of this hierarchical configuration.
`ConfigurationNode` `getRootNode()` Returns the root node of this hierarchical configuration.
`boolean` `isEmpty()` Checks if this configuration is empty.
`protected boolean` `nodeDefined(ConfigurationNode node)` Checks if the specified node is defined.
`protected boolean` `nodeDefined(HierarchicalConfiguration.Node node)` Deprecated. Use the method ``nodeDefined(ConfigurationNode)`` instead.
`protected void` `removeNode(ConfigurationNode node)` Removes the specified node from this configuration.
`protected void` `removeNode(HierarchicalConfiguration.Node node)` Deprecated. Use the method ``removeNode(ConfigurationNode)`` instead.
`static void` `setDefaultExpressionEngine(ExpressionEngine engine)` Sets the default expression engine.
`void` `setExpressionEngine(ExpressionEngine expressionEngine)` Sets the expression engine to be used by this configuration.
`void` `setProperty(String key, Object value)` Sets the value of the specified property.
`void` `setRoot(HierarchicalConfiguration.Node node)` Sets the root node of this hierarchical configuration.
`void` `setRootNode(ConfigurationNode rootNode)` Sets the root node of this hierarchical configuration.
`Configuration` `subset(String prefix)` Creates a new `Configuration` object containing all keys that start with the specified prefix.

Methods inherited from class org.apache.commons.configuration.AbstractConfiguration

`addProperty, clear, clearPropertyDirect, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDefaultListDelimiter, getDelimiter, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getList, getList, getListDelimiter, getLong, getLong, getLong, getProperties, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, interpolate, interpolate, interpolateHelper, isDelimiterParsingDisabled, isThrowExceptionOnMissing, resolveContainerStore, setDefaultListDelimiter, setDelimiter, setDelimiterParsingDisabled, setListDelimiter, setThrowExceptionOnMissing`

Methods inherited from class org.apache.commons.configuration.event.EventSource
`addConfigurationListener, clearConfigurationListeners, createEvent, fireEvent, getConfigurationListeners, isDetailEvents, removeConfigurationListener, setDetailEvents`

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

Field Detail

### EVENT_CLEAR_TREE

    public static final int EVENT_CLEAR_TREE

  Constant for the clear tree event.

  See Also:
    Constant Field Values

### EVENT_ADD_NODES

    public static final int EVENT_ADD_NODES

  Constant for the add nodes event.

  See Also:
    Constant Field Values

Constructor Detail

### HierarchicalConfiguration

    public HierarchicalConfiguration()

  Creates a new instance of `HierarchicalConfiguration`.

Method Detail

### getRoot

    public HierarchicalConfiguration.Node getRoot()

  Returns the root node of this hierarchical configuration. This method exists for backwards compatibility only. New code should use the ``getRootNode()`` method instead, which operates on the preferred data type `ConfigurationNode`.

  Returns:
    the root node

### setRoot

    public void setRoot(HierarchicalConfiguration.Node node)

  Sets the root node of this hierarchical configuration. This method exists for backwards compatibility only. New code should use the ``setRootNode(ConfigurationNode)`` method instead, which operates on the preferred data type `ConfigurationNode`.

  Parameters:
    `node` - the root node

### getRootNode

    public ConfigurationNode getRootNode()

  Returns the root node of this hierarchical configuration.

  Returns:
    the root node
  Since:
    1.3

### setRootNode

    public void setRootNode(ConfigurationNode rootNode)

  Sets the root node of this hierarchical configuration.

  Parameters:
    `rootNode` - the root node
  Since:
    1.3

### getDefaultExpressionEngine

    public static ExpressionEngine getDefaultExpressionEngine()

  Returns the default expression engine.

  Returns:
    the default expression engine
  Since:
    1.3

### setDefaultExpressionEngine

    public static void setDefaultExpressionEngine(ExpressionEngine engine)

  Sets the default expression engine. This expression engine will be used if no specific engine was set for an instance. It is shared between all hierarchical configuration instances. So modifying its properties will impact all instances, for which no specific engine is set.

  Parameters:
    `engine` - the new default expression engine
  Since:
    1.3

### getExpressionEngine

    public ExpressionEngine getExpressionEngine()

  Returns the expression engine used by this configuration. This method will never return null; if no specific expression engine was set, the default expression engine will be returned.

  Returns:
    the current expression engine
  Since:
    1.3

### setExpressionEngine

    public void setExpressionEngine(ExpressionEngine expressionEngine)

  Sets the expression engine to be used by this configuration. All property keys this configuration has to deal with will be interpreted by this engine.

  Parameters:
    `expressionEngine` - the new expression engine; can be null, then the default expression engine will be used
  Since:
    1.3

### getProperty

    public Object getProperty(String key)

  Fetches the specified property. This task is delegated to the associated expression engine.

  Specified by:
    `getProperty` in interface `Configuration`
  Parameters:
    `key` - the key to be looked up
  Returns:
    the found value

### addPropertyDirect

    protected void addPropertyDirect(String key,
                                     Object obj)

  Adds the property with the specified key. This task will be delegated to the associated `ExpressionEngine`, so the passed in key must match the requirements of this implementation.

  Specified by:
    `addPropertyDirect` in class `AbstractConfiguration`
  Parameters:
    `key` - the key of the new property
    `obj` - the value of the new property

### addNodes

    public void addNodes(String key,
                         Collection nodes)

  Adds a collection of nodes at the specified position of the configuration tree. This method works similar to `addProperty()`, but instead of a single property a whole collection of nodes can be added - and thus complete configuration sub trees. E.g. with this method it is possible to add parts of another `HierarchicalConfiguration` object to this object. If the passed in key refers to an existing and unique node, the new nodes are added to this node. Otherwise a new node will be created at the specified position in the hierarchy.

  Parameters:
    `key` - the key where the nodes are to be added; can be null , then they are added to the root node
    `nodes` - a collection with the `Node` objects to be added

### isEmpty

    public boolean isEmpty()

  Checks if this configuration is empty. Empty means that there are no keys with any values, though there can be some (empty) nodes.

  Specified by:
    `isEmpty` in interface `Configuration`
  Specified by:
    `isEmpty` in class `AbstractConfiguration`
  Returns:
    a flag if this configuration is empty

### subset

    public Configuration subset(String prefix)

  Creates a new `Configuration` object containing all keys that start with the specified prefix. This implementation will return a `HierarchicalConfiguration` object so that the structure of the keys will be saved.

  Specified by:
    `subset` in interface `Configuration`
  Overrides:
    `subset` in class `AbstractConfiguration`
  Parameters:
    `prefix` - the prefix of the keys for the subset
  Returns:
    a new configuration object representing the selected subset
  See Also:
    `SubsetConfiguration`

### configurationAt

    public SubnodeConfiguration configurationAt(String key)

  Returns a hierarchical subnode configuration object that wraps the configuration node specified by the given key. This method provides an easy means of accessing sub trees of a hierarchical configuration. In the returned configuration the sub tree can directly be accessed, it becomes the root node of this configuration. Because of this the passed in key must select exactly one configuration node; otherwise an `IllegalArgumentException` will be thrown.

  The difference between this method and the ``subset(String)`` method is that `subset()` supports arbitrary subsets of configuration nodes while `configurationAt()` only returns a single sub tree. Please refer to the documentation of the `SubnodeConfiguration` class to obtain further information about subnode configurations and when they should be used.

  Parameters:
    `key` - the key that selects the sub tree
  Returns:
    a hierarchical configuration that contains this sub tree
  Since:
    1.3
  See Also:
    `SubnodeConfiguration`

### configurationsAt

    public List configurationsAt(String key)

  Returns a list of sub configurations for all configuration nodes selected by the given key. This method will evaluate the passed in key (using the current `ExpressionEngine`) and then create a subnode configuration for each returned node (like ``configurationAt(String)``}). This is especially useful when dealing with list-like structures. As an example consider the configuration that contains data about database tables and their fields. If you need access to all fields of a certain table, you can simply do

       List fields = config.configurationsAt("tables.table(0).fields.field");
       for(Iterator it = fields.iterator(); it.hasNext();)
       {
           HierarchicalConfiguration sub = (HierarchicalConfiguration) it.next();
           // now the children and attributes of the field node can be
           // directly accessed
           String fieldName = sub.getString("name");
           String fieldType = sub.getString("type");
           ...

  Parameters:
    `key` - the key for selecting the desired nodes
  Returns:
    a list with hierarchical configuration objects; each configuration represents one of the nodes selected by the passed in key
  Since:
    1.3

### createSubnodeConfiguration

    protected SubnodeConfiguration createSubnodeConfiguration(ConfigurationNode node)

  Creates a subnode configuration for the specified node. This method is called by `configurationAt()` and `configurationsAt()`.

  Parameters:
    `node` - the node, for which a subnode configuration is to be created
  Returns:
    the configuration for the given node
  Since:
    1.3

### containsKey

    public boolean containsKey(String key)

  Checks if the specified key is contained in this configuration. Note that for this configuration the term "contained" means that the key has an associated value. If there is a node for this key that has no value but children (either defined or undefined), this method will still return false .

  Specified by:
    `containsKey` in interface `Configuration`
  Specified by:
    `containsKey` in class `AbstractConfiguration`
  Parameters:
    `key` - the key to be chekced
  Returns:
    a flag if this key is contained in this configuration

### setProperty

    public void setProperty(String key,
                            Object value)

  Sets the value of the specified property.

  Specified by:
    `setProperty` in interface `Configuration`
  Overrides:
    `setProperty` in class `AbstractConfiguration`
  Parameters:
    `key` - the key of the property to set
    `value` - the new value of this property

### clearTree

    public void clearTree(String key)

  Removes all values of the property with the given name and of keys that start with this name. So if there is a property with the key "foo" and a property with the key "foo.bar", a call of `clearTree("foo")` would remove both properties.

  Parameters:
    `key` - the key of the property to be removed

### clearProperty

    public void clearProperty(String key)

  Removes the property with the given key. Properties with names that start with the given key (i.e. properties below the specified key in the hierarchy) won't be affected.

  Specified by:
    `clearProperty` in interface `Configuration`
  Overrides:
    `clearProperty` in class `AbstractConfiguration`
  Parameters:
    `key` - the key of the property to be removed

### getKeys

    public Iterator getKeys()

  Returns an iterator with all keys defined in this configuration. Note that the keys returned by this method will not contain any indices. This means that some structure will be lost.

  Specified by:
    `getKeys` in interface `Configuration`
  Specified by:
    `getKeys` in class `AbstractConfiguration`
  Returns:
    an iterator with the defined keys in this configuration

### getKeys

    public Iterator getKeys(String prefix)

  Returns an iterator with all keys defined in this configuration that start with the given prefix. The returned keys will not contain any indices.

  Specified by:
    `getKeys` in interface `Configuration`
  Overrides:
    `getKeys` in class `AbstractConfiguration`
  Parameters:
    `prefix` - the prefix of the keys to start with
  Returns:
    an iterator with the found keys
  See Also:
    `Configuration.getKeys()`

### getMaxIndex

    public int getMaxIndex(String key)

  Returns the maximum defined index for the given key. This is useful if there are multiple values for this key. They can then be addressed separately by specifying indices from 0 to the return value of this method.

  Parameters:
    `key` - the key to be checked
  Returns:
    the maximum defined index for this key

### clone

    public Object clone()

  Creates a copy of this object. This new configuration object will contain copies of all nodes in the same structure. Registered event listeners won't be cloned; so they are not registered at the returned copy.

  Overrides:
    `clone` in class `Object`
  Returns:
    the copy
  Since:
    1.2

### fetchNodeList

    protected List fetchNodeList(String key)

  Helper method for fetching a list of all nodes that are addressed by the specified key.

  Parameters:
    `key` - the key
  Returns:
    a list with all affected nodes (never null )

### findPropertyNodes

    protected void findPropertyNodes(ConfigurationKey.KeyIterator keyPart,
                                     HierarchicalConfiguration.Node node,
                                     Collection nodes)

  Deprecated. Property keys are now evaluated by the expression engine associated with the configuration; this method will no longer be called. If you want to modify the way properties are looked up, consider implementing you own `ExpressionEngine` implementation.

  Recursive helper method for fetching a property. This method processes all facets of a configuration key, traverses the tree of properties and fetches the the nodes of all matching properties.

  Parameters:
    `keyPart` - the configuration key iterator
    `node` - the actual node
    `nodes` - here the found nodes are stored

### nodeDefined

    protected boolean nodeDefined(HierarchicalConfiguration.Node node)

  Deprecated. Use the method ``nodeDefined(ConfigurationNode)`` instead.

  Checks if the specified node is defined.

  Parameters:
    `node` - the node to be checked
  Returns:
    a flag if this node is defined

### nodeDefined

    protected boolean nodeDefined(ConfigurationNode node)

  Checks if the specified node is defined.

  Parameters:
    `node` - the node to be checked
  Returns:
    a flag if this node is defined

### removeNode

    protected void removeNode(HierarchicalConfiguration.Node node)

  Deprecated. Use the method ``removeNode(ConfigurationNode)`` instead.

  Removes the specified node from this configuration. This method ensures that parent nodes that become undefined by this operation are also removed.

  Parameters:
    `node` - the node to be removed

### removeNode

    protected void removeNode(ConfigurationNode node)

  Removes the specified node from this configuration. This method ensures that parent nodes that become undefined by this operation are also removed.

  Parameters:
    `node` - the node to be removed

### clearNode

    protected void clearNode(HierarchicalConfiguration.Node node)

  Deprecated. Use the method ``clearNode(ConfigurationNode)`` instead

  Clears the value of the specified node. If the node becomes undefined by this operation, it is removed from the hierarchy.

  Parameters:
    `node` - the node to be cleard

### clearNode

    protected void clearNode(ConfigurationNode node)

  Clears the value of the specified node. If the node becomes undefined by this operation, it is removed from the hierarchy.

  Parameters:
    `node` - the node to be cleard

### fetchAddNode

    protected HierarchicalConfiguration.Node fetchAddNode(ConfigurationKey.KeyIterator keyIt,
                                                          HierarchicalConfiguration.Node startNode)

  Deprecated. Adding new properties is now to a major part delegated to the `ExpressionEngine` associated with this configuration instance. This method will no longer be called. Developers who want to modify the process of adding new properties should consider implementing their own expression engine.

  Returns a reference to the parent node of an add operation. Nodes for new properties can be added as children of this node. If the path for the specified key does not exist so far, it is created now.

  Parameters:
    `keyIt` - the iterator for the key of the new property
    `startNode` - the node to start the search with
  Returns:
    the parent node for the add operation

### findLastPathNode

    protected HierarchicalConfiguration.Node findLastPathNode(ConfigurationKey.KeyIterator keyIt,
                                                              HierarchicalConfiguration.Node node)

  Deprecated. Adding new properties is now to a major part delegated to the `ExpressionEngine` associated with this configuration instance. This method will no longer be called. Developers who want to modify the process of adding new properties should consider implementing their own expression engine.

  Finds the last existing node for an add operation. This method traverses the configuration tree along the specified key. The last existing node on this path is returned.

  Parameters:
    `keyIt` - the key iterator
    `node` - the actual node
  Returns:
    the last existing node on the given path

### createAddPath

    protected HierarchicalConfiguration.Node createAddPath(ConfigurationKey.KeyIterator keyIt,
                                                           HierarchicalConfiguration.Node root)

  Deprecated. Adding new properties is now to a major part delegated to the `ExpressionEngine` associated with this configuration instance. This method will no longer be called. Developers who want to modify the process of adding new properties should consider implementing their own expression engine.

  Creates the missing nodes for adding a new property. This method ensures that there are corresponding nodes for all components of the specified configuration key.

  Parameters:
    `keyIt` - the key iterator
    `root` - the base node of the path to be created
  Returns:
    the last node of the path

### createNode

    protected HierarchicalConfiguration.Node createNode(String name)

  Creates a new `Node` object with the specified name. This method can be overloaded in derived classes if a specific node type is needed. This base implementation always returns a new object of the `Node` class.

  Parameters:
    `name` - the name of the new node
  Returns:
    the new node

Copyright © 2001-2006 The Apache Software Foundation. All Rights Reserved.