commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r1034120 - in /commons/proper/configuration/trunk/src/site/xdoc/userguide: howto_xml.xml user_guide.xml
Date Thu, 11 Nov 2010 21:00:56 GMT
Author: oheger
Date: Thu Nov 11 21:00:56 2010
New Revision: 1034120

Updated user guide with information about list delimiter parsing in XMLConfiguration.


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 Thu Nov 11 21:00:56
@@ -563,7 +563,11 @@ config.addProperty("tables.table.fields.
-		<subsection name="Escaping dot characters in property names">
+		<subsection name="Escaping special characters">
+            <p>
+                Some characters in property keys or values require a special
+                treatment.
+            </p>
                 Per default the dot character is used as delimiter by most
                 configuration classes (we will learn how to change this for
@@ -615,6 +619,55 @@ String complex = config.getString("test.
                 you should avoid dots in the tag names of your XML configuration
                 files or other configuration sources.
+            <p>
+                Another source of problems is related to list delimiter characters
+                in the values of properties. Like other configuration classes
+                <code>XMLConfiguration</code> implements
+                <a href="howto_basicfeatures.html#List_handling">list handling</a>.
+                This means that the values of XML elements and attributes are
+                checked whether they contain a list delimiter character. If this
+                is the case, the value is split, and a list property is created.
+                Per default this feature is enabled. Have a look at the
+                following example:
+            </p>
+   			<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+  <pi>3,1415</pi>
+            <p>
+                Here we use the comma as delimiter for fraction digits (as is
+                standard for some languages). However, the configuration will
+                interpret the comma as list delimiter character and assign the
+                property <em>pi</em> the two values 3 and 1415. This was not
+                desired.
+            </p>
+            <p>
+                XML has a natural way of defining list properties by simply
+                repeating elements. So defining multiple values of a property in
+                a single element or attribute is a rather untypical use case.
+                Unfortunately, early versions of Commons Configuration had list
+                delimiter splitting enabled per default. Later it became obvious
+                that this feature can cause serious problems related to the
+                interpretation of property values and the escaping of delimiter
+                characters. For reasons of backwards compatibility we have to
+                stick to this approach in the 1.x series though.
+            </p>
+            <p>
+                In the next major release the handling of lists will propably be
+                reworked. Therefore it is recommended not to use this feature.
+                You are save if you disable it immediately after the creation of
+                an <code>XMLConfiguration</code> object (and before a file is
+                loaded). This can be achieved as follows:
+            </p>
+   			<source><![CDATA[
+XMLConfiguration config = new XMLConfiguration();

Modified: commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml
--- commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml (original)
+++ commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml Thu Nov 11 21:00:56
@@ -83,7 +83,7 @@
         <li><a href="howto_xml.html#Complex_hierarchical_structures">Complex
hierarchical structures</a></li>
         <li><a href="howto_xml.html#Accessing_structured_properties">Accessing
structured properties</a></li>
         <li><a href="howto_xml.html#Adding_new_properties">Adding new properties</a></li>
-        <li><a href="howto_xml.html#Escaping_dot_characters_in_property_names">Escaping
dot characters in property names</a></li>
+        <li><a href="howto_xml.html#Escaping_special_characters">Escaping dot
characters in property names</a></li>
         <li><a href="howto_xml.html#Expression_engines">Expression engines</a></li>
           <li><a href="howto_xml.html#The_default_expression_engine">The default
expression engine</a></li>

View raw message