Author: oheger
Date: Sun Jan 22 11:23:50 2006
New Revision: 371351
URL: http://svn.apache.org/viewcvs?rev=371351&view=rev
Log:
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/howto_xml.xml
Modified: jakarta/commons/proper/configuration/trunk/xdocs/changes.xml
URL:
http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/xdocs/changes.xml?rev=371351&r1=371350&r2=371351&view=diff
==============================================================================
--- 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 @@
<body>
<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
URL:
http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml?rev=371351&r1=371350&r2=371351&view=diff
==============================================================================
--- 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>
+ <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
cut
+ 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("fields.field.name");
+]]></source>
+ <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
one
+ by one:
+ </p>
+ <source><![CDATA[
+List fieldNames = config.getList("tables.table(0).fields.field.name");
+List fieldTypes = config.getList("tables.table(0).fields.field.type");
+List ... // further calls for other data that might be stored in the config
+]]></source>
+ <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
is
+ 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) it.next();
+ // sub contains now all data about a single field
+ String fieldName = sub.getString("name");
+ String fieldType = sub.getString("type");
+ ...
+]]></source>
</subsection>
<subsection name="Adding new properties">
<p>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
