Package org.apache.commons.configuration2

# Interface HierarchicalConfiguration<T>

Type Parameters:
  `T` - the type of the nodes used by this hierarchical configuration

All Superinterfaces:
  `Configuration`, `ImmutableConfiguration`, `ImmutableHierarchicalConfiguration`, `NodeModelSupport<T>`, `SynchronizerSupport`

All Known Implementing Classes:
  `AbstractHierarchicalConfiguration`, `AbstractYAMLBasedConfiguration`, `BaseHierarchicalConfiguration`, `CombinedConfiguration`, `DynamicCombinedConfiguration`, `INIConfiguration`, `JSONConfiguration`, `PatternSubtreeConfigurationWrapper`, `PropertyListConfiguration`, `SubnodeConfiguration`, `XMLConfiguration`, `XMLPropertyListConfiguration`, `YAMLConfiguration`

public interface HierarchicalConfiguration<T> extends Configuration, ImmutableHierarchicalConfiguration, NodeModelSupport<T>

An interface for mutable hierarchical configurations.

This interface introduces methods for manipulating tree-like structured configuration sources. Also, all methods defined by the `Configuration` interface are available.

This interface does not make any assumptions about the concrete type of nodes used by an implementation; this is reflected by a generic type parameter. Concrete implementations may therefore define their own hierarchical structures.

Since:
  2.0

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addNodes(String key, Collection<? extends T> nodes)`
  Adds a collection of nodes at the specified position of the configuration tree.
  `List<HierarchicalConfiguration<T>>`
  `childConfigurationsAt(String key)`
  Returns a list with sub configurations for all child nodes of the node selected by the given key.
  `List<HierarchicalConfiguration<T>>`
  `childConfigurationsAt(String key, boolean supportUpdates)`
  Returns a list with sub configurations for all child nodes of the node selected by the given key allowing the caller to specify the `supportUpdates` flag.
  `void`
  `clearTree(String key)`
  Removes all values of the property with the given name and of keys that start with this name.
  `HierarchicalConfiguration<T>`
  `configurationAt(String key)`
  Returns a hierarchical subnode configuration for the node specified by the given key.
  `HierarchicalConfiguration<T>`
  `configurationAt(String key, boolean supportUpdates)`
  Returns a hierarchical sub configuration object that wraps the configuration node specified by the given key.
  `List<HierarchicalConfiguration<T>>`
  `configurationsAt(String key)`
  Returns a list of sub configurations for all configuration nodes selected by the given key.
  `List<HierarchicalConfiguration<T>>`
  `configurationsAt(String key, boolean supportUpdates)`
  Returns a list of sub configurations for all configuration nodes selected by the given key allowing the caller to specify the `supportUpdates` flag.
  `void`
  `setExpressionEngine(ExpressionEngine expressionEngine)`
  Sets the expression engine to be used by this configuration.

  ### Methods inherited from interface org.apache.commons.configuration2.Configuration

  `addProperty, clear, clearProperty, getInterpolator, installInterpolator, setInterpolator, setProperty, subset`

  ### Methods inherited from interface org.apache.commons.configuration2.ImmutableConfiguration

  `containsKey, get, get, getArray, getArray, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getCollection, getCollection, getDouble, getDouble, getDouble, getDuration, getDuration, getEncodedString, getEncodedString, getEnum, getEnum, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getKeys, getKeys, getKeys, getList, getList, getList, getList, getLong, getLong, getLong, getProperties, getProperty, getShort, getShort, getShort, getString, getString, getStringArray, immutableSubset, isEmpty, size`

  ### Methods inherited from interface org.apache.commons.configuration2.ImmutableHierarchicalConfiguration

  `getExpressionEngine, getMaxIndex, getRootElementName, immutableChildConfigurationsAt, immutableConfigurationAt, immutableConfigurationAt, immutableConfigurationsAt`

  ### Methods inherited from interface org.apache.commons.configuration2.tree.NodeModelSupport

  `getNodeModel`

  ### Methods inherited from interface org.apache.commons.configuration2.sync.SynchronizerSupport

  `getSynchronizer, lock, setSynchronizer, unlock`

- ## Method Details

  - ### setExpressionEngine

    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

  - ### addNodes

    void addNodes(String key, Collection<? extends T> 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 `BaseHierarchicalConfiguration` 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

  - ### configurationAt

    HierarchicalConfiguration<T> configurationAt(String key, boolean supportUpdates)

    Returns a hierarchical sub 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 `Configuration.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 sub configurations and when they should be used.

    With the `supportUpdate` flag the behavior of the returned sub configuration regarding updates of its parent configuration can be determined. If set to false, the configurations return on independent nodes structures. So changes made on one configuration cannot be seen by the other one. A value of true in contrast creates a direct connection between both configurations - they are then using the same underlying data structures as much as possible. There are however changes which break this connection; for instance, if the sub tree the sub configuration belongs to is completely removed from the parent configuration. If such a change happens, the sub configuration becomes detached from its parent. It can still be used in a normal way, but changes on it are not reflected by the parent and vice verse. Also, it is not possible to reattach a once detached sub configuration.

    Parameters:
      `key` - the key that selects the sub tree
      `supportUpdates` - a flag whether the returned sub configuration should be directly connected to its parent
    Returns:
      a hierarchical configuration that contains this sub tree
    See Also:
      - `SubnodeConfiguration`

  - ### configurationAt

    HierarchicalConfiguration<T> configurationAt(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
    See Also:
      - `SubnodeConfiguration`

  - ### configurationsAt

    List<HierarchicalConfiguration<T>> 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 sub 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();)
         {
             BaseHierarchicalConfiguration sub = (BaseHierarchicalConfiguration) 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");
             ...

    The configuration objects returned are not connected to the parent configuration.
    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

  - ### configurationsAt

    List<HierarchicalConfiguration<T>> configurationsAt(String key, boolean supportUpdates)
    Returns a list of sub configurations for all configuration nodes selected by the given key allowing the caller to specify the `supportUpdates` flag. This method works like `configurationsAt(String)`, but with the additional boolean parameter it can be specified whether the returned configurations react on updates of the parent configuration.
    Parameters:
      `key` - the key for selecting the desired nodes
      `supportUpdates` - a flag whether the returned sub configuration should be directly connected to its parent
    Returns:
      a list with hierarchical configuration objects; each configuration represents one of the nodes selected by the passed in key
    See Also:
      - `configurationsAt(String, boolean)`

  - ### childConfigurationsAt

    List<HierarchicalConfiguration<T>> childConfigurationsAt(String key)
    Returns a list with sub configurations for all child nodes of the node selected by the given key. This method works like `ImmutableHierarchicalConfiguration.immutableChildConfigurationsAt(String)`, but returns a list with mutable configuration objects. The configuration objects returned are not connected to the parent configuration.
    Parameters:
      `key` - the key for selecting the desired parent node
    Returns:
      a collection with `HierarchicalConfiguration` objects for all child nodes of the selected parent node

  - ### childConfigurationsAt

    List<HierarchicalConfiguration<T>> childConfigurationsAt(String key, boolean supportUpdates)
    Returns a list with sub configurations for all child nodes of the node selected by the given key allowing the caller to specify the `supportUpdates` flag.
    Parameters:
      `key` - the key for selecting the desired parent node
      `supportUpdates` - a flag whether the returned sub configuration should be directly connected to its parent
    Returns:
      a collection with `HierarchicalConfiguration` objects for all child nodes of the selected parent node

  - ### clearTree

    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