Author: oheger
Date: Thu Nov 11 21:00:56 2010
New Revision: 1034120
URL: http://svn.apache.org/viewvc?rev=1034120&view=rev
Log:
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/user_guide.xml
Modified:
commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_xml.xml
URL:
http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_xml.xml?rev=1034120&r1=1034119&r2=1034120&view=diff
==============================================================================
--- 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 2010
@@ -563,7 +563,11 @@ config.addProperty("tables.table.fields.
<code>HierarchicalConfiguration</code>.
</p>
</subsection>
- <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>
<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>
+ <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" ?>
+
+<configuration>
+ <pi>3,1415</pi>
+</configuration>
+]]></source>
+ <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();
+config.setDelimiterParsingDisabled(true);
+config.setAttributeSplittingDisabled(true);
+config.load("config.xml");
+]]></source>
</subsection>
</section>
Modified:
commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml
URL:
http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml?rev=1034120&r1=1034119&r2=1034120&view=diff
==============================================================================
--- 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 2010
@@ -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>
<ul>
<li><a href="howto_xml.html#The_default_expression_engine">The
default expression engine</a></li>
