Package org.apache.commons.configuration2

# Interface ImmutableHierarchicalConfiguration

All Superinterfaces:
  `ImmutableConfiguration`

All Known Subinterfaces:
  `HierarchicalConfiguration<T>`

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

public interface ImmutableHierarchicalConfiguration extends ImmutableConfiguration

An interface for immutable hierarchical configurations.

There are some sources of configuration data that cannot be stored very well in a flat configuration object (like `BaseConfiguration`) because then their structure is lost. A prominent example are XML documents.

This interface extends the basic `ImmutableConfiguration` interface by structured access to configuration properties. An `ExpressionEngine` is used to evaluate complex property keys and to map them to nodes of a tree-like structure.

Since:
  2.0

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ExpressionEngine`
  `getExpressionEngine()`
  Gets the expression engine used by this configuration.
  `int`
  `getMaxIndex(String key)`
  Gets the maximum defined index for the given key.
  `String`
  `getRootElementName()`
  Gets the name of the root element of this configuration.
  `List<ImmutableHierarchicalConfiguration>`
  `immutableChildConfigurationsAt(String key)`
  Returns a list of immutable configurations for all direct child elements of the node selected by the given key.
  `ImmutableHierarchicalConfiguration`
  `immutableConfigurationAt(String key)`
  Returns an immutable hierarchical configuration for the node specified by the given key.
  `ImmutableHierarchicalConfiguration`
  `immutableConfigurationAt(String key, boolean supportUpdates)`
  Returns an immutable hierarchical configuration object that wraps the configuration node specified by the given key.
  `List<ImmutableHierarchicalConfiguration>`
  `immutableConfigurationsAt(String key)`
  Returns a list of immutable configurations for all configuration nodes selected by the given key.

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

  `containsKey, containsValue, entrySet, forEach, 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`

- ## Method Details

  - ### getExpressionEngine

    ExpressionEngine getExpressionEngine()
    Gets 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

  - ### getMaxIndex

    int getMaxIndex(String key)
    Gets 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

  - ### getRootElementName

    String getRootElementName()
    Gets the name of the root element of this configuration. This information may be of use in some cases, for example for sub configurations created using the `immutableConfigurationsAt()` method. The exact meaning of the string returned by this method is specific to a concrete implementation. For instance, an XML configuration might return the name of the document element.
    Returns:
      the name of the root element of this configuration

  - ### immutableChildConfigurationsAt

    List<ImmutableHierarchicalConfiguration> immutableChildConfigurationsAt(String key)
    Returns a list of immutable configurations for all direct child elements of the node selected by the given key. With this method it is possible to inspect the content of a hierarchical structure; all children of a given node can be queried without having to know their exact names. If the passed in key does not point to a single node, an empty list is returned. This is also the result if the node referred to by the key does not have child elements.
    Parameters:
      `key` - the key for selecting the desired parent node
    Returns:
      a collection with immutable configurations for all child nodes of the selected parent node

  - ### immutableConfigurationAt

    ImmutableHierarchicalConfiguration immutableConfigurationAt(String key)
    Returns an immutable hierarchical configuration for the node specified by the given key. This is a short form for `immutableConfigurationAt(key, <strong>false</strong>)`.
    Parameters:
      `key` - the key that selects the sub tree
    Returns:
      a hierarchical configuration that contains this sub tree

  - ### immutableConfigurationAt

    ImmutableHierarchicalConfiguration immutableConfigurationAt(String key, boolean supportUpdates)

    Returns an immutable hierarchical 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 `ImmutableConfiguration.immutableSubset(String)` method is that `immutableSubset()` supports arbitrary subsets of configuration nodes while `immutableConfigurationAt()` 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
      `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

  - ### immutableConfigurationsAt

    List<ImmutableHierarchicalConfiguration> immutableConfigurationsAt(String key)
    Returns a list of immutable 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 an immutable subnode configuration for each returned node (like `immutableConfigurationAt(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<ImmutableHierarchicalConfiguration> fields =
           config.immutableConfigurationsAt("tables.table(0).fields.field");
         for(Iterator<ImmutableHierarchicalConfiguration> it = fields.iterator();
           it.hasNext();)
         {
             ImmutableHierarchicalConfiguration sub = 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 immutable hierarchical configuration objects; each configuration represents one of the nodes selected by the passed in key