Author: oheger
Date: Tue Nov 4 13:12:45 2008
New Revision: 711408
URL: http://svn.apache.org/viewvc?rev=711408&view=rev
Log:
CONFIGURATION-336: Updated documentation and changes.xml.
Modified:
commons/proper/configuration/trunk/xdocs/changes.xml
commons/proper/configuration/trunk/xdocs/userguide/howto_utilities.xml
Modified: commons/proper/configuration/trunk/xdocs/changes.xml
URL:
http://svn.apache.org/viewvc/commons/proper/configuration/trunk/xdocs/changes.xml?rev=711408&r1=711407&r2=711408&view=diff
==============================================================================
--- commons/proper/configuration/trunk/xdocs/changes.xml (original)
+++ commons/proper/configuration/trunk/xdocs/changes.xml Tue Nov 4 13:12:45
2008
@@ -48,6 +48,15 @@
DefaultConfigurationBuilder now supports defining new configuration
providers in the configuration definition file.
</action>
+ <action dev="oheger" type="add" issue="CONFIGURATION-336">
+ When converting a flat configuration to a hierarchical one it is now
+ possible to specify the expression engine to be used for this purpose.
+ This may be necessary if the flat configuration contains keys with
+ special characters interpreted by the expression engine.
+ CombinedConfiguration defines the new setConversionExpressionEngine()
+ method. The expression engine passed to this method will be used when
+ converting flat child configurations to hierarchical ones.
+ </action>
<action dev="oheger" type="fix" issue="CONFIGURATION-334">
Made handling of parent nodes more consistent when setRoot() or
setRootNode() of HierarchicalConfiguration are involved.
Modified: commons/proper/configuration/trunk/xdocs/userguide/howto_utilities.xml
URL:
http://svn.apache.org/viewvc/commons/proper/configuration/trunk/xdocs/userguide/howto_utilities.xml?rev=711408&r1=711407&r2=711408&view=diff
==============================================================================
--- commons/proper/configuration/trunk/xdocs/userguide/howto_utilities.xml
(original)
+++ commons/proper/configuration/trunk/xdocs/userguide/howto_utilities.xml Tue
Nov 4 13:12:45 2008
@@ -102,6 +102,53 @@
object is created, and the properties of the source configuration are
copied into it.
</p>
+ <p>
+ Sometimes a flat configuration contains keys with special characters
+ that are not compatible with the expression engine of a hierarchical
+ configuration. For instance, a properties configuration could have the
+ following property:
+ </p>
+ <source><![CDATA[
+test(xy)=true
+]]></source>
+ <p>
+ When processing this property during conversion the default expression
+ engine of the resulting hierarchical configuration will interpret the
+ brackets as an index marker and try to convert the string between the
+ brackets into a number. In this example this fails with a
+ <code>NumberFormatException</code>! The cause for this problem is that
the
+ property key contains characters with a special meaning for the default
+ expression engine.
+ </p>
+ <p>
+ To solve this problem, it is possible to specify an alternative
expression
+ engine that will be used for the conversion. For instance, if you know
that
+ your property keys can contain brackets, you could use an instance of
+ <code>DefaultExpressionEngine</code> that is configured with a different
+ index marker. This could look as follows:
+ </p>
+ <source><![CDATA[
+DefaultExpressionEngine engineConvert = new DefaultExpressionEngine();
+engineConvert.setIndexStart("[");
+engineConvert.setIndexEnd("]");
+HierarchicalConfiguration hc =
+ ConfigurationUtils.convertToHierarchical(flatConfig, engineConvert);
+]]></source>
+ <p>
+ In this example an expression engine is constructed that uses square
+ brackets as index markers. Therefore normal brackets do not have a
+ special meaning and thus are no more problematic during conversion.
+ </p>
+ <p>
+ <em>Note:</em> When using a <a href="howto_combinedconfiguration.html">
+ CombinedConfiguration</a> flat configurations contained in the combined
+ configuration are also converted into hierarchical configurations using
+ the methods discussed here. The <code>CombinedConfiguration</code> class
+ defines the method <code>setConversionExpressionEngine()</code>, which
+ can be called to specify an expression engine to be used during this
+ conversion. The expression engine passed to this method will be
+ propagated to ConfigurationUtils.convertToHierarchical().
+ </p>
</subsection>
<subsection name="Converting between properties and configurations">
