Java Doc for HierarchicalConfiguration.java in  » Library » Apache-commons-configuration-1.4-src » org » apache » commons » configuration » Java Source Code / Java DocumentationJava Source Code and Java Documentation

A specialized configuration class that extends its base class by the ability of keeping more structure in the stored properties.

There are some sources of configuration data that cannot be stored very well in a BaseConfiguration object because then their structure is lost. This is especially true for XML documents. This class can deal with such structured configuration sources by storing the properties in a tree-like organization.

The internal used storage form allows for a more sophisticated access to single properties. As an example consider the following XML document:

 <database>
 <tables>
 <table>
 <name>users</name>
 <fields>
 <field>
 <name>lid</name>
 <type>long</name>
 </field>
 <field>
 <name>usrName</name>
 <type>java.lang.String</type>
 </field>
 ...
 </fields>
 </table>
 <table>
 <name>documents</name>
 <fields>
 <field>
 <name>docid</name>
 <type>long</type>
 </field>
 ...
 </fields>
 </table>
 ...
 </tables>
 </database>
 

If this document is parsed and stored in a HierarchicalConfiguration object (which can be done by one of the sub classes), there are enhanced possibilities of accessing properties. The keys for querying information can contain indices that select a certain element if there are multiple hits.

For instance the key tables.table(0).name can be used to find out the name of the first table. In opposite tables.table.name would return a collection with the names of all available tables. Similarily the key tables.table(1).fields.field.name returns a collection with the names of all fields of the second table. If another index is added after the field element, a single field can be accessed: tables.table(1).fields.field(0).name.

There is a getMaxIndex() method that returns the maximum allowed index that can be added to a given property key. This method can be used to iterate over all values defined for a certain property.

Returns a hierarchical subnode configuration object that wraps the configuration node specified by the given key.

Returns a hierarchical subnode 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 HierarchicalConfiguration.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 subnode configurations and when they should be used.

 List fields = config.configurationsAt("tables.table(0).fields.field");
 for(Iterator it = fields.iterator(); it.hasNext();)
 {
 HierarchicalConfiguration sub = (HierarchicalConfiguration) 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");
 ...