Author: oheger
Date: Sat Oct 27 11:33:49 2007
New Revision: 589172
URL: http://svn.apache.org/viewvc?rev=589172&view=rev
Log:
CONFIGURATION-273: Added a section about the new interpolatedConfiguration()
method to the user guide
Modified:
commons/proper/configuration/trunk/xdocs/changes.xml
commons/proper/configuration/trunk/xdocs/userguide/howto_utilities.xml
commons/proper/configuration/trunk/xdocs/userguide/user_guide.xml
Modified: commons/proper/configuration/trunk/xdocs/changes.xml
URL:
http://svn.apache.org/viewvc/commons/proper/configuration/trunk/xdocs/changes.xml?rev=589172&r1=589171&r2=589172&view=diff
==============================================================================
--- commons/proper/configuration/trunk/xdocs/changes.xml (original)
+++ commons/proper/configuration/trunk/xdocs/changes.xml Sat Oct 27 11:33:49
2007
@@ -23,6 +23,12 @@
<body>
<release version="1.5-SNAPSHOT" date="in SVN" description="">
+ <action dev="oheger" type="add" issue="CONFIGURATION-273">
+ A new method interpolatedConfiguration() was added to
AbstractConfiguration.
+ This method returns a configuration with the same type and
+ content as the original configuration, however all variables have been
+ resolved.
+ </action>
<action dev="oheger" type="fix" issue="CONFIGURATION-299">
Resolving of variables with the prefix const (constant fields) caused
a ClassCastException under certain circumstances if non-String fields
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=589172&r1=589171&r2=589172&view=diff
==============================================================================
--- commons/proper/configuration/trunk/xdocs/userguide/howto_utilities.xml
(original)
+++ commons/proper/configuration/trunk/xdocs/userguide/howto_utilities.xml Sat
Oct 27 11:33:49 2007
@@ -151,6 +151,44 @@
</p>
</subsection>
+ <subsection name="Interpolation of all variables">
+ <p>
+ Another issue with the integration of <em>Commons Configuration</em> with
+ native Java applications can be variables: Configuration implementations
+ are able to detect variables like <code>${myReference}</code> or
+ <code>${sys:java.version}</code> in the values of their properties and
+ substitute them by their current values (see the section
+ <a href="howto_basicfeatures.html#Variable_Interpolation">Variable
+ Interpolation</a> for more details). External components probably do not
+ know how to handle such placeholders when processing configuration files
+ written by <em>Commons Configuration</em>.
+ </p>
+ <p>
+ <code><a
href="apidocs/org/apache/commons/configuration/AbstractConfiguration.html">
+ AbstractConfiguration</a></code> provides the method
+ <code>interpolatedConfiguration()</code>. This method creates a clone of
+ the current configuration and then performs interpolation on all of its
+ properties. So the result of this method is a configuration object with
+ basically the same content as the original configuration, but with all
+ variables replaced by their actual values (as far as this was possible).
+ The following code fragment shows how a
+ <code><a
href="apidocs/org/apache/commons/configuration/PropertiesConfiguration.html">
+ PropertiesConfiguration</a></code> object can be saved in a way that the
+ resulting properties file does not contain any variables:
+ </p>
+ <source><![CDATA[
+// Load a properties file (which may contain variables)
+PropertiesConfiguration config = new
PropertiesConfiguration("config.properties");
+
+// Perform interpolation on all variables
+PropertiesConfiguration extConfig =
+ (PropertiesConfiguration) config.interpolatedConfiguration();
+
+// Save the interpolated configuration (no more variables)
+extConfig.save("external_config.properties");
+]]></source>
+ </subsection>
+
<subsection name="Handling of runtime exceptions">
<p>
Section <a href="howto_events.html#Error_listeners">Error listeners</a>
Modified: commons/proper/configuration/trunk/xdocs/userguide/user_guide.xml
URL:
http://svn.apache.org/viewvc/commons/proper/configuration/trunk/xdocs/userguide/user_guide.xml?rev=589172&r1=589171&r2=589172&view=diff
==============================================================================
--- commons/proper/configuration/trunk/xdocs/userguide/user_guide.xml (original)
+++ commons/proper/configuration/trunk/xdocs/userguide/user_guide.xml Sat Oct
27 11:33:49 2007
@@ -143,6 +143,7 @@
<li><a href="howto_utilities.html#Copy_a_configuration">Copy a
configuration</a></li>
<li><a
href="howto_utilities.html#Converting_a_flat_configuration_into_a_hierarchical_one">Converting
a flat configuration into a hierarchical one</a></li>
<li><a
href="howto_utilities.html#Converting_between_properties_and_configurations">Converting
between properties and configurations</a></li>
+ <li><a
href="howto_utilities.html#Interpolation_of_all_variables">Interpolation of all
variables</a></li>
<li><a
href="howto_utilities.html#Handling_of_runtime_exceptions">Handling of runtime
exceptions</a></li>
</ul>
</ul>
