## 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.HierarchicalReloadableConfiguration
                      org.apache.commons.configuration.SubnodeConfiguration

All Implemented Interfaces:
  Serializable, Cloneable, Configuration, Reloadable

    public class SubnodeConfiguration

extends HierarchicalReloadableConfiguration

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

There are however changes at the parent configuration, which cause the subnode configuration to become detached. An example for such a change is a reload operation of a file-based configuration, which replaces all nodes of the parent configuration. The subnode configuration per default still references the old nodes. Another example are list structures: a subnode configuration can be created to point on the ith element of the list. Now list elements can be added or removed, so that the list elements' indices change. In such a scenario the subnode configuration would always point to the same list element, regardless of its current index.

To solve these problems and make a subnode configuration aware of such structural changes of its parent, it is possible to associate a subnode configuration with a configuration key. This can be done by calling the `setSubnodeKey()` method. If here a key is set, the subnode configuration will evaluate it on each access, thus ensuring that it is always in sync with its parent. In this mode the subnode configuration really behaves like a live-view on its parent. The price for this is a decreased performance because now an additional evaluation has to be performed on each property access. So this mode should only be used if necessary; if for instance a subnode configuration is only used for a temporary convenient access to a complex configuration, there is no need to make it aware for structural changes of its parent. If a subnode configuration is created using the `configurationAt()` method of `HierarchicalConfiguration` (which should be the preferred way), with an additional boolean parameter it can be specified whether the resulting subnode configuration should be aware of structural changes or not. Then the configuration key will be automatically set.

Note: At the moment support for creating a subnode configuration that is aware of structural changes of its parent from another subnode configuration (a "sub subnode configuration") is limited. This only works if

1. the subnode configuration that serves as the parent for the new subnode configuration is itself associated with a configuration key and
2. the key passed in to create the new subnode configuration is not too complex (if configuration keys are used that contain indices, a corresponding key that is valid from the parent configuration's point of view cannot be constructed).

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 1210178 2011-12-04 18:58:51Z oheger $
Author:
  Commons Configuration team
See Also:
  Serialized Form

Nested Class Summary

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

Field Summary

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

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
`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 ConfigurationInterpolator` `createInterpolator()` Creates a ConfigurationInterpolator with a chain to the parent's interpolator.
`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.
`protected SubnodeConfiguration` `createSubnodeConfiguration(ConfigurationNode node, String subnodeKey)` Returns a hierarchical configuration object for the given sub node that is aware of structural changes of its parent.
`HierarchicalConfiguration` `getParent()` Returns the parent configuration of this subnode configuration.
`ConfigurationNode` `getRootNode()` Returns the root node for this configuration.
`String` `getSubnodeKey()` Returns the key that was used to construct this configuration.
`protected void` `initFromParent(HierarchicalConfiguration parentConfig)` Initializes this subnode configuration from the given parent configuration.
`void` `setSubnodeKey(String subnodeKey)` Sets the key to the root node of this subnode configuration.

Methods inherited from class org.apache.commons.configuration.HierarchicalReloadableConfiguration
`getReloadLock`

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

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

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

`addErrorLogListener, addProperty, append, clearPropertyDirect, copy, 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`

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

### getSubnodeKey

    public String getSubnodeKey()

  Returns the key that was used to construct this configuration. If here a non-null value is returned, the subnode configuration will always check its parent for structural changes and reconstruct itself if necessary.

  Returns:
    the key for selecting this configuration's root node
  Since:
    1.5

### setSubnodeKey

    public void setSubnodeKey(String subnodeKey)

  Sets the key to the root node of this subnode configuration. If here a key is set, the subnode configuration will behave like a live-view on its parent for this key. See the class comment for more details.

  Parameters:
    `subnodeKey` - the key used to construct this configuration
  Since:
    1.5

### getRootNode

    public ConfigurationNode getRootNode()

  Returns the root node for this configuration. If a subnode key is set, this implementation re-evaluates this key to find out if this subnode configuration needs to be reconstructed. This ensures that the subnode configuration is always synchronized with its parent configuration.

  Overrides:
    `getRootNode` in class `HierarchicalConfiguration`
  Returns:
    the root node of this configuration
  Since:
    1.5
  See Also:
    `setSubnodeKey(String)`

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

### createSubnodeConfiguration

    protected SubnodeConfiguration createSubnodeConfiguration(ConfigurationNode node,
                                                              String subnodeKey)

  Returns a hierarchical configuration object for the given sub node that is aware of structural changes of its parent. Works like the method with the same name, but also sets the subnode key for the new subnode configuration, so it can check whether the parent has been changed. This only works if this subnode configuration has itself a valid subnode key. So if a subnode configuration that should be aware of structural changes is created from an already existing subnode configuration, this subnode configuration must also be aware of such changes.

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

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

### createInterpolator

    protected ConfigurationInterpolator createInterpolator()

  Creates a ConfigurationInterpolator with a chain to the parent's interpolator.

  Overrides:
    `createInterpolator` in class `AbstractConfiguration`
  Returns:
    the new interpolator

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