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 and Description
ExpressionEngine	getExpressionEngine() Returns the expression engine used by this configuration.
int	getMaxIndex(String key) Returns the maximum defined index for the given key.
String	getRootElementName() Returns 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, get, get, getArray, getArray, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getCollection, getCollection, getDouble, getDouble, getDouble, getEncodedString, getEncodedString, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getKeys, getKeys, getList, getList, getList, getList, getLong, getLong, getLong, getProperties, getProperty, getShort, getShort, getShort, getString, getString, getStringArray, immutableSubset, isEmpty, size

Method Detail

getExpressionEngine

ExpressionEngine getExpressionEngine()

Returns 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)

Returns 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()

Returns 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

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

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

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

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