HierarchicalConfiguration

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

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Configuration

Direct Known Subclasses:

AbstractHierarchicalFileConfiguration, HierarchicalReloadableConfiguration
```
public class HierarchicalConfiguration
extends AbstractConfiguration
implements java.io.Serializable, java.lang.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. Similarly 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.

Since the 1.3 release of Commons Configuration hierarchical configurations support an expression engine. This expression engine is responsible for evaluating the passed in configuration keys and map them to the stored properties. The examples above are valid for the default expression engine, which is used when a new HierarchicalConfiguration instance is created. With the setExpressionEngine() method a different expression engine can be set. For instance with XPathExpressionEngine there is an expression engine available that supports configuration keys in XPATH syntax.

In addition to the events common for all configuration classes hierarchical configurations support some more events that correspond to some specific methods and features:
EVENT_ADD_NODES
The addNodes() method was called; the event object contains the key, to which the nodes were added, and a collection with the new nodes as value.

EVENT_CLEAR_TREE
The clearTree() method was called; the event object stores the key of the removed sub tree.

EVENT_SUBNODE_CHANGED
A SubnodeConfiguration that was created from this configuration has been changed. The value property of the event object contains the original event object as it was sent by the subnode configuration.

Note:Configuration objects of this type can be read concurrently by multiple threads. However if one of these threads modifies the object, synchronization has to be performed manually.
Version:

$Id: HierarchicalConfiguration.java 1330666 2012-04-26 06:12:30Z oheger $

Author:

Oliver Heger

See Also:

Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type	Class	Description
`protected static class`	`HierarchicalConfiguration.BuilderVisitor`	A specialized visitor base class that can be used for storing the tree of configuration nodes.
`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

Fields
Modifier and Type	Field	Description
`static int`	`EVENT_ADD_NODES`	Constant for the add nodes event.
`static int`	`EVENT_CLEAR_TREE`	Constant for the clear tree event.
`static int`	`EVENT_SUBNODE_CHANGED`	Constant for the subnode configuration modified event.

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

Constructor Summary

Constructors
Constructor	Description
`HierarchicalConfiguration()`	Creates a new instance of `HierarchicalConfiguration`.
`HierarchicalConfiguration(HierarchicalConfiguration c)`	Creates a new instance of `HierarchicalConfiguration` and copies all data contained in the specified configuration into the new one.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method	Description
`void`	`addNodes(java.lang.String key, java.util.Collection<? extends ConfigurationNode> nodes)`	Adds a collection of nodes at the specified position of the configuration tree.
`protected void`	`addPropertyDirect(java.lang.String key, java.lang.Object obj)`	Adds the property with the specified key.
`void`	`clear()`	Clears this configuration.
`protected void`	`clearNode(HierarchicalConfiguration.Node node)`	Deprecated. Use the method `clearNode(ConfigurationNode)` instead
`protected void`	`clearNode(ConfigurationNode node)`	Clears the value of the specified node.
`void`	`clearProperty(java.lang.String key)`	Removes the property with the given key.
`protected static void`	`clearReferences(ConfigurationNode node)`	Clears all reference fields in a node structure.
`void`	`clearTree(java.lang.String key)`	Removes all values of the property with the given name and of keys that start with this name.
`java.lang.Object`	`clone()`	Creates a copy of this object.
`SubnodeConfiguration`	`configurationAt(java.lang.String key)`	Returns a hierarchical subnode configuration for the node specified by the given key.
`SubnodeConfiguration`	`configurationAt(java.lang.String key, boolean supportUpdates)`	Returns a hierarchical subnode configuration object that wraps the configuration node specified by the given key.
`java.util.List<HierarchicalConfiguration>`	`configurationsAt(java.lang.String key)`	Returns a list of sub configurations for all configuration nodes selected by the given key.
`boolean`	`containsKey(java.lang.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(java.lang.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 SubnodeConfiguration`	`createSubnodeConfiguration(ConfigurationNode node, java.lang.String subnodeKey)`	Creates a new subnode configuration for the specified node and sets its construction key.
`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 java.util.List<ConfigurationNode>`	`fetchNodeList(java.lang.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, java.util.Collection<ConfigurationNode> 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.
`java.util.Iterator<java.lang.String>`	`getKeys()`	Returns an iterator with all keys defined in this configuration.
`java.util.Iterator<java.lang.String>`	`getKeys(java.lang.String prefix)`	Returns an iterator with all keys defined in this configuration that start with the given prefix.
`int`	`getMaxIndex(java.lang.String key)`	Returns the maximum defined index for the given key.
`java.lang.Object`	`getProperty(java.lang.String key)`	Fetches the specified property.
`java.lang.Object`	`getReloadLock()`	Returns the object to synchronize on a reload.
`HierarchicalConfiguration.Node`	`getRoot()`	Returns the root node of this hierarchical configuration.
`ConfigurationNode`	`getRootNode()`	Returns the root node of this hierarchical configuration.
`Configuration`	`interpolatedConfiguration()`	Returns a configuration with the same content as this configuration, but with all variables replaced by their actual values.
`boolean`	`isEmpty()`	Checks if this configuration is empty.
`protected boolean`	`nodeDefined(HierarchicalConfiguration.Node node)`	Deprecated. Use the method `nodeDefined(ConfigurationNode)` instead.
`protected boolean`	`nodeDefined(ConfigurationNode node)`	Checks if the specified node is defined.
`protected void`	`removeNode(HierarchicalConfiguration.Node node)`	Deprecated. Use the method `removeNode(ConfigurationNode)` instead.
`protected void`	`removeNode(ConfigurationNode node)`	Removes the specified node from this configuration.
`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(java.lang.String key, java.lang.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.
`protected void`	`subnodeConfigurationChanged(ConfigurationEvent event)`	This method is always called when a subnode configuration created from this configuration has been modified.
`Configuration`	`subset(java.lang.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
addErrorLogListener, addProperty, append, clearPropertyDirect, copy, createInterpolator, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDefaultListDelimiter, getDelimiter, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getInterpolator, getList, getList, getListDelimiter, getLogger, getLong, getLong, getLong, getProperties, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, getSubstitutor, interpolate, interpolate, interpolateHelper, isDelimiterParsingDisabled, isScalarValue, isThrowExceptionOnMissing, resolveContainerStore, setDefaultListDelimiter, setDelimiter, setDelimiterParsingDisabled, setListDelimiter, setLogger, setThrowExceptionOnMissing

Methods inherited from class org.apache.commons.configuration.event.EventSource
addConfigurationListener, addErrorListener, clearConfigurationListeners, clearErrorListeners, createErrorEvent, createEvent, fireError, fireEvent, getConfigurationListeners, getErrorListeners, isDetailEvents, removeConfigurationListener, removeErrorListener, 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.
    
    Since:
    
    1.3
    
    See Also:
    
    Constant Field Values
  - EVENT_ADD_NODES
```
public static final int EVENT_ADD_NODES
```
    Constant for the add nodes event.
    
    Since:
    
    1.3
    
    See Also:
    
    Constant Field Values
  - EVENT_SUBNODE_CHANGED
```
public static final int EVENT_SUBNODE_CHANGED
```
    Constant for the subnode configuration modified event.
    
    Since:
    
    1.5
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - HierarchicalConfiguration
```
public HierarchicalConfiguration()
```
    Creates a new instance of HierarchicalConfiguration.
  - HierarchicalConfiguration
```
public HierarchicalConfiguration(HierarchicalConfiguration c)
```
    Creates a new instance of HierarchicalConfiguration and copies all data contained in the specified configuration into the new one.
    
    Parameters:
    
    c - the configuration that is to be copied (if null, this constructor will behave like the standard constructor)
    
    Since:
    
    1.4
- Method Detail
  - getReloadLock
```
public java.lang.Object getReloadLock()
```
    Returns the object to synchronize on a reload. This class is not reloadable so this object isn't important
    
    Returns:
    
    the lock object
  - 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 java.lang.Object getProperty(java.lang.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(java.lang.String key,
                                 java.lang.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(java.lang.String key,
                     java.util.Collection<? extends ConfigurationNode> 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. (However be aware that a ConfigurationNode object can only belong to a single configuration. So if nodes from one configuration are directly added to another one using this method, the structure of the source configuration will be broken. In this case you should clone the nodes to be added before calling addNodes().) 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
    
    Returns:
    
    a flag if this configuration is empty
  - subset
```
public Configuration subset(java.lang.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. The nodes selected by the prefix (it is possible that multiple nodes are selected) are mapped to the root node of the returned configuration, i.e. their children and attributes will become children and attributes of the new root node. However a value of the root node is only set if exactly one of the selected nodes contain a value (if multiple nodes have a value, there is simply no way to decide how these values are merged together). Note that the returned Configuration object is not connected to its source configuration: updates on the source configuration are not reflected in the subset and vice versa.
    
    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(java.lang.String key,
                                            boolean supportUpdates)
```
    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.
    
    With the supportUpdate flag the behavior of the returned SubnodeConfiguration regarding updates of its parent configuration can be determined. A subnode configuration operates on the same nodes as its parent, so changes at one configuration are normally directly visible for the other configuration. There are however changes of the parent configuration, which are not recognized by the subnode configuration per default. An example for this is a reload operation (for file-based configurations): Here the complete node set of the parent configuration is replaced, but the subnode configuration still references the old nodes. If such changes should be detected by the subnode configuration, the supportUpdates flag must be set to true. This causes the subnode configuration to reevaluate the key used for its creation each time it is accessed. This guarantees that the subnode configuration always stays in sync with its key, even if the parent configuration's data significantly changes. If such a change makes the key invalid - because it now no longer points to exactly one node -, the subnode configuration is not reconstructed, but keeps its old data. It is then quasi detached from its parent.
    
    Parameters:
    
    key - the key that selects the sub tree
    
    supportUpdates - a flag whether the returned subnode configuration should be able to handle updates of its parent
    
    Returns:
    
    a hierarchical configuration that contains this sub tree
    
    Since:
    
    1.5
    
    See Also:
    
    SubnodeConfiguration
  - configurationAt
```
public SubnodeConfiguration configurationAt(java.lang.String key)
```
    Returns a hierarchical subnode configuration for the node specified by the given key. This is a short form for configurationAt(key, <b>false</b>).
    
    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 java.util.List<HierarchicalConfiguration> configurationsAt(java.lang.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
  - createSubnodeConfiguration
```
protected SubnodeConfiguration createSubnodeConfiguration(ConfigurationNode node,
                                                          java.lang.String subnodeKey)
```
    Creates a new subnode configuration for the specified node and sets its construction key. A subnode configuration created this way will be aware of structural changes of its parent.
    
    Parameters:
    
    node - the node, for which a subnode configuration is to be created
    
    subnodeKey - the key used to construct the configuration
    
    Returns:
    
    the configuration for the given node
    
    Since:
    
    1.5
  - subnodeConfigurationChanged
```
protected void subnodeConfigurationChanged(ConfigurationEvent event)
```
    This method is always called when a subnode configuration created from this configuration has been modified. This implementation transforms the received event into an event of type EVENT_SUBNODE_CHANGED and notifies the registered listeners.
    
    Parameters:
    
    event - the event describing the change
    
    Since:
    
    1.5
  - containsKey
```
public boolean containsKey(java.lang.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
    
    Parameters:
    
    key - the key to be chekced
    
    Returns:
    
    a flag if this key is contained in this configuration
  - setProperty
```
public void setProperty(java.lang.String key,
                        java.lang.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
  - clear
```
public void clear()
```
    Clears this configuration. This is a more efficient implementation than the one inherited from the base class. It directly removes all data from the root node.
    
    Specified by:
    
    clear in interface Configuration
    
    Overrides:
    
    clear in class AbstractConfiguration
  - clearTree
```
public void clearTree(java.lang.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(java.lang.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 java.util.Iterator<java.lang.String> 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
    
    Returns:
    
    an iterator with the defined keys in this configuration
  - getKeys
```
public java.util.Iterator<java.lang.String> getKeys(java.lang.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. This implementation tries to locate a node whose key is the same as the passed in prefix. Then the subtree of this node is traversed, and the keys of all nodes encountered (including attributes) are added to the result set.
    
    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(java.lang.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 java.lang.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 EventSource
    
    Returns:
    
    the copy
    
    Since:
    
    1.2
  - interpolatedConfiguration
```
public Configuration interpolatedConfiguration()
```
    Returns a configuration with the same content as this configuration, but with all variables replaced by their actual values. This implementation is specific for hierarchical configurations. It clones the current configuration and runs a specialized visitor on the clone, which performs interpolation on the single configuration nodes.
    
    Overrides:
    
    interpolatedConfiguration in class AbstractConfiguration
    
    Returns:
    
    a configuration with all variables interpolated
    
    Since:
    
    1.5
  - fetchNodeList
```
protected java.util.List<ConfigurationNode> fetchNodeList(java.lang.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
```
@Deprecated
protected void findPropertyNodes(ConfigurationKey.KeyIterator keyPart,
                                 HierarchicalConfiguration.Node node,
                                 java.util.Collection<ConfigurationNode> 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
```
@Deprecated
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
```
@Deprecated
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
```
@Deprecated
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 cleared
  - 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 cleared
  - fetchAddNode
```
@Deprecated
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
```
@Deprecated
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
```
@Deprecated
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(java.lang.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
  - clearReferences
```
protected static void clearReferences(ConfigurationNode node)
```
    Clears all reference fields in a node structure. A configuration node can store a so-called "reference". The meaning of this data is determined by a concrete sub class. Typically such references are specific for a configuration instance. If this instance is cloned or copied, they must be cleared. This can be done using this method.
    
    Parameters:
    
    node - the root node of the node hierarchy, in which the references are to be cleared
    
    Since:
    
    1.4

Class HierarchicalConfiguration

Nested Class Summary

Field Summary

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

Constructor Summary

Method Summary

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

Methods inherited from class org.apache.commons.configuration.event.EventSource

Methods inherited from class java.lang.Object

Field Detail

EVENT_CLEAR_TREE

EVENT_ADD_NODES

EVENT_SUBNODE_CHANGED

Constructor Detail

HierarchicalConfiguration

HierarchicalConfiguration

Method Detail

getReloadLock

getRoot

setRoot

getRootNode

setRootNode

getDefaultExpressionEngine

setDefaultExpressionEngine

getExpressionEngine

setExpressionEngine

getProperty

addPropertyDirect

addNodes

isEmpty

subset

configurationAt

configurationAt

configurationsAt

createSubnodeConfiguration

createSubnodeConfiguration

subnodeConfigurationChanged

containsKey

setProperty

clear

clearTree

clearProperty

getKeys

getKeys

getMaxIndex

clone

interpolatedConfiguration

fetchNodeList

findPropertyNodes

nodeDefined

nodeDefined

removeNode

removeNode

clearNode

clearNode

fetchAddNode

findLastPathNode

createAddPath

createNode

clearReferences