commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r1152440 - in /commons/proper/configuration/trunk/src: changes/changes.xml site/xdoc/userguide/howto_xml.xml
Date Sat, 30 Jul 2011 09:59:00 GMT
Author: oheger
Date: Sat Jul 30 09:58:58 2011
New Revision: 1152440

[CONFIGURATION-452] Documentation updates.


Modified: commons/proper/configuration/trunk/src/changes/changes.xml
--- commons/proper/configuration/trunk/src/changes/changes.xml (original)
+++ commons/proper/configuration/trunk/src/changes/changes.xml Sat Jul 30 09:58:58 2011
@@ -23,6 +23,10 @@
     <release version="1.7" date="in SVN" description="">
+      <action dev="oheger" type="add" issue="CONFIGURATION-452">
+        XPathExpressionEngine now provides better support for the setProperty()
+        method.
+      </action>
       <action dev="oheger" type="add" issue="CONFIGURATION-448">
         The parsing of ini files has been improved for property definitions
         containing multiple separator characters.

Modified: commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_xml.xml
--- commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_xml.xml (original)
+++ commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_xml.xml Sat Jul 30 09:58:58
@@ -920,6 +920,49 @@ config.addProperty("tables/table[last()]
                 elements further children are added.
+                There is one gotcha with these keys described so far: they do
+                not work with the <code>setProperty()</code> method! This is
+                because <code>setProperty()</code> has to check whether the
+                passed in key already exists; therefore it needs a key which can
+                be interpreted by query methods. If you want to use
+                <code>setProperty()</code>, you can pass in regular keys (i.e.
+                without a whitespace separator). The method then tries to figure
+                out which part of the key already exists in the configuration
+                and adds new nodes as necessary. In principle such regular keys
+                can also be used with <code>addProperty()</code>. However, they
+                do not contain sufficient information to decide where new nodes
+                should be added.
+            </p>
+            <p>
+                To make this clearer let's go back to the example with the
+                tables. Consider that there is a configuration which already
+                contains information about some database tables. In order to add
+                a new table element in the configuration
+                <code>addProperty()</code> could be used as follows:
+            </p>
+            <source><![CDATA[
+config.addProperty("tables/table/name", "documents");
+         ]]></source>
+            <p>
+                In the configuration a <code>&lt;tables&gt;</code> element
+                already exists, also <code>&lt;table&gt;</code> and
+                <code>&lt;name&gt;</code> elements. How should the expression
+                engine know where new node structures are to be added? The
+                solution to this problem is to provide this information in the
+                key by stating:
+            </p>
+            <source><![CDATA[
+config.addProperty("tables table/name", "documents");
+         ]]></source>
+            <p>
+                Now it is clear that new nodes should be added as children of
+                the  <code>&lt;tables&gt;</code> element. More information
+                keys and how they play together with <code>addProperty()</code>
+                and <code>setProperty()</code> can be found in the Javadocs for
+                <a href="../apidocs/org/apache/commons/configuration/tree/xpath/XPathExpressionEngine.html">
+                <code>XPathExpressionEngine</code></a>.
+            </p>
+            <p>
                 <em>Note:</em> XPATH support is implemented through
                 <a href="">Commons JXPath</a>.
                 So when making use of this feature, be sure you include the

View raw message