Return-Path: 
 <commits-return-4088-apmail-commons-commits-archive=commons.apache.org@commons.apache.org>
Delivered-To: apmail-commons-commits-archive@locus.apache.org
Received: (qmail 33100 invoked from network); 4 Nov 2008 21:13:08 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2)
  by minotaur.apache.org with SMTP; 4 Nov 2008 21:13:08 -0000
Received: (qmail 57506 invoked by uid 500); 4 Nov 2008 21:13:13 -0000
Delivered-To: apmail-commons-commits-archive@commons.apache.org
Received: (qmail 57458 invoked by uid 500); 4 Nov 2008 21:13:13 -0000
Mailing-List: contact commits-help@commons.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:commits-help@commons.apache.org>
List-Unsubscribe: <mailto:commits-unsubscribe@commons.apache.org>
List-Post: <mailto:commits@commons.apache.org>
List-Id: <commits.commons.apache.org>
Reply-To: dev@commons.apache.org
Delivered-To: mailing list commits@commons.apache.org
Received: (qmail 57449 invoked by uid 99); 4 Nov 2008 21:13:13 -0000
Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136)
    by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 04 Nov 2008 13:13:13 -0800
X-ASF-Spam-Status: No, hits=-2000.0 required=10.0
	tests=ALL_TRUSTED
X-Spam-Check-By: apache.org
Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4)
    by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 04 Nov 2008 21:12:04 +0000
Received: by eris.apache.org (Postfix, from userid 65534)
	id 8F9082388879; Tue,  4 Nov 2008 13:12:46 -0800 (PST)
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r711408 - in /commons/proper/configuration/trunk/xdocs:
 changes.xml userguide/howto_utilities.xml
Date: Tue, 04 Nov 2008 21:12:46 -0000
To: commits@commons.apache.org
From: oheger@apache.org
X-Mailer: svnmailer-1.0.8
Message-Id: <20081104211246.8F9082388879@eris.apache.org>
X-Virus-Checked: Checked by ClamAV on apache.org

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">