commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r371351 - in /jakarta/commons/proper/configuration/trunk/xdocs: changes.xml howto_xml.xml
Date Sun, 22 Jan 2006 19:23:59 GMT
Author: oheger
Date: Sun Jan 22 11:23:50 2006
New Revision: 371351

Updated XML howto to cover the new configuration(s)At() methods; updated changes.xml


Modified: jakarta/commons/proper/configuration/trunk/xdocs/changes.xml
--- jakarta/commons/proper/configuration/trunk/xdocs/changes.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/changes.xml Sun Jan 22 11:23:50 2006
@@ -23,6 +23,19 @@
     <release version="1.3-SNAPSHOT" date="in SVN">
+      <action dev="oheger" type="add" issue="38075">
+        A new method configurationsAdd() was added to HierarchicalConfiguration
+        that provides a convenient way of iterating over complex list-like
+        structures without the need of manually constructing configuration keys
+        with indices.
+      </action>
+      <action dev="oheger" type="add">
+        A new class SubnodeConfiguration was introduced that wraps a configuration
+        node of a HierarchicalConfiguration. All operations performed on this
+        configuration use this wrapped node as root. The new configurationAt()
+        method of HierarchicalConfiguration returns such a SubnodeConfiguration
+        for a specified sub node.
+      </action>
       <action dev="oheger" type="add" issue="35753">
         With XPathExpressionEngine an expression engine for hierarchical
         configurations is now available that can evaluate XPATH expressions in

Modified: jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml
--- jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml Sun Jan 22 11:23:50 2006
@@ -333,6 +333,64 @@
 				of indices it is possible to navigate through complex structures of
 				XML documents; each XML element can be uniquely identified.
+            <p>
+                Sometimes dealing with long property keys may become inconvenient,
+                especially if always the same properties are accessed. For this
+                case <code>HierarchicalConfiguration</code> provides a short
+                with the <code>configurationAt()</code> method. This method can
+                be passed a key that selects exactly one node of the hierarchy
+                of nodes contained in a hierarchical configuration. Then a new
+                hierarchical configuration will be returned whose root node is
+                the selected node. So all property keys passed into that
+                configuration should be relative to the new root node. For
+                instance, if we are only interested in information about the
+                first database table, we could do something like that:
+            </p>
+   			<source><![CDATA[
+HierarchicalConfiguration sub = config.configurationAt("tables.table(0)");
+String tableName = sub.getString("name");  // only need to provide relative path
+List fieldNames = sub.getList("");
+            <p>
+                For dealing with complex list-like structures there is another
+                short cut. Often it will be necessary to iterate over all items
+                in the list and access their (sub) properties. A good example are
+                the fields of the tables in our demo configuration. When you want
+                to process all fields of a table (e.g. for constructing a
+                <code>CREATE TABLE</code> statement), you will need all information
+                stored for them in the configuration. An option would be to use
+                the <code>getList()</code> method to fetch the required data
+                by one:
+            </p>
+   			<source><![CDATA[
+List fieldNames = config.getList("tables.table(0)");
+List fieldTypes = config.getList("tables.table(0).fields.field.type");
+List ... // further calls for other data that might be stored in the config
+            <p>
+                But this is not very readable and will fail if not all field
+                elements contain the same set of data (for instance the
+                <code>type</code> property may be optional, then the list for
+                the types can contain less elements than the other lists). A
+                solution to these problems is the <code>configurationsAt()</code>
+                method, a close relative to the <code>configurationAt()</code>
+                method covered above. This method evaluates the passed in key and
+                collects all configuration nodes that match this criterion. Then
+                for each node a <code>HierarchicalConfiguration</code> object
+                created with this node as root node. A list with these configuration
+                objects is returned. As the following example shows this comes in
+                very handy when processing list-like structures:
+            </p>
+   			<source><![CDATA[
+List fields = config.configurationsAt("tables.table(0).fields.field");
+for(Iterator it = fields.iterator(); it.hasNext();)
+    HierarchicalConfiguration sub = (HierarchicalConfiguration);
+    // sub contains now all data about a single field
+    String fieldName = sub.getString("name");
+    String fieldType = sub.getString("type");
+    ...
 		<subsection name="Adding new properties">

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message