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 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, e.g. 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, <b>false</b>).
      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