## org.apache.commons.configuration
Class SubnodeConfiguration

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

All Implemented Interfaces:
  Serializable, Cloneable, Configuration

    public class SubnodeConfiguration

extends HierarchicalConfiguration

A specialized hierarchical configuration class that wraps a single node of its parent configuration.

Configurations of this type are initialized with a parent configuration and a configuration node of this configuration. This node becomes the root node of the subnode configuration. All property accessor methods are evaluated relative to this root node. A good use case for a `SubnodeConfiguration` is when multiple properties from a specific sub tree of the whole configuration need to be accessed. Then a `SubnodeConfiguration` can be created with the parent node of the affected sub tree as root node. This allows for simpler property keys and is also more efficient.

A subnode configuration and its parent configuration operate on the same hierarchy of configuration nodes. So if modifications are performed at the subnode configuration, these changes are immideately visible in the parent configuration. Analogously will updates of the parent configuration affect the subnode configuration if the sub tree spanned by the subnode configuration's root node is involved.

When a subnode configuration is created, it inherits the settings of its parent configuration, e.g. some flags like the `throwExceptionOnMissing` flag or the settings for handling list delimiters) or the expression engine. If these settings are changed later in either the subnode or the parent configuration, the changes are not visible for each other. So you could create a subnode configuration, change its expression engine without affecting the parent configuration.

From its purpose this class is quite similar to ``SubsetConfiguration``. The difference is that a subset configuration of a hierarchical configuration may combine multiple configuration nodes from different sub trees of the configuration, while all nodes in a subnode configuration belong to the same sub tree. If an application can live with this limitation, it is recommended to use this class instead of `SubsetConfiguration` because creating a subset configuration is more expensive than creating a subnode configuration.

Since:
  1.3
Version:
  $Id: SubnodeConfiguration.java 439648 2006-09-02 20:42:10Z oheger $
Author:
  Oliver Heger
See Also:
  Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.commons.configuration.HierarchicalConfiguration
`HierarchicalConfiguration.BuilderVisitor, HierarchicalConfiguration.CloneVisitor, HierarchicalConfiguration.DefinedKeysVisitor, HierarchicalConfiguration.DefinedVisitor, HierarchicalConfiguration.Node, HierarchicalConfiguration.NodeVisitor`

Field Summary

Fields inherited from class org.apache.commons.configuration.HierarchicalConfiguration
`EVENT_ADD_NODES, EVENT_CLEAR_TREE`

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
`SubnodeConfiguration(HierarchicalConfiguration parent, ConfigurationNode root)` Creates a new instance of `SubnodeConfiguration` and initializes it with the parent configuration and the new root node.

Method Summary
`protected HierarchicalConfiguration.Node` `createNode(String name)` Creates a new node.
`protected SubnodeConfiguration` `createSubnodeConfiguration(ConfigurationNode node)` Returns a hierarchical configuration object for the given sub node.
`HierarchicalConfiguration` `getParent()` Returns the parent configuration of this subnode configuration.
`protected void` `initFromParent(HierarchicalConfiguration parentConfig)` Initializes this subnode configuration from the given parent configuration.
`protected Object` `interpolate(Object value)` Performs interpolation.

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

`addNodes, addPropertyDirect, clearNode, clearNode, clearProperty, clearTree, clone, configurationAt, configurationsAt, containsKey, createAddPath, fetchAddNode, fetchNodeList, findLastPathNode, findPropertyNodes, getDefaultExpressionEngine, getExpressionEngine, getKeys, getKeys, getMaxIndex, getProperty, getRoot, getRootNode, isEmpty, nodeDefined, nodeDefined, removeNode, removeNode, setDefaultExpressionEngine, setExpressionEngine, setProperty, setRoot, setRootNode, subset`

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

Constructor Detail

### SubnodeConfiguration

    public SubnodeConfiguration(HierarchicalConfiguration parent,
                                ConfigurationNode root)

  Creates a new instance of `SubnodeConfiguration` and initializes it with the parent configuration and the new root node.

  Parameters:
    `parent` - the parent configuration
    `root` - the root node of this subnode configuration

Method Detail

### getParent

    public HierarchicalConfiguration getParent()

  Returns the parent configuration of this subnode configuration.

  Returns:
    the parent configuration

### createSubnodeConfiguration

    protected SubnodeConfiguration createSubnodeConfiguration(ConfigurationNode node)

  Returns a hierarchical configuration object for the given sub node. This implementation will ensure that the returned `SubnodeConfiguration` object will have the same parent than this object.

  Overrides:
    `createSubnodeConfiguration` in class `HierarchicalConfiguration`
  Parameters:
    `node` - the sub node, for which the configuration is to be created
  Returns:
    a hierarchical configuration for this sub node

### createNode

    protected HierarchicalConfiguration.Node createNode(String name)

  Creates a new node. This task is delegated to the parent.

  Overrides:
    `createNode` in class `HierarchicalConfiguration`
  Parameters:
    `name` - the node's name
  Returns:
    the new node

### initFromParent

    protected void initFromParent(HierarchicalConfiguration parentConfig)

  Initializes this subnode configuration from the given parent configuration. This method is called by the constructor. It will copy many settings from the parent.

  Parameters:
    `parentConfig` - the parent configuration

### interpolate

    protected Object interpolate(Object value)

  Performs interpolation. This implementation will ask the parent configuration to perform the interpolation so that variables can be evaluated in the global context.

  Overrides:
    `interpolate` in class `AbstractConfiguration`
  Parameters:
    `value` - the value to be interpolated
  Returns:
    returns the value with variables substituted

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