Author: oheger
Date: Sat Dec 30 08:04:03 2006
New Revision: 491243
URL: http://svn.apache.org/viewvc?view=rev&rev=491243
Log:
CONFIGURATION-192: Documentation updates
Modified:
jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/interpol/ConfigurationInterpolator.java
jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationfactory.xml
jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml
jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml
Modified:
jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/interpol/ConfigurationInterpolator.java
URL:
http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/interpol/ConfigurationInterpolator.java?view=diff&rev=491243&r1=491242&r2=491243
==============================================================================
---
jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/interpol/ConfigurationInterpolator.java
(original)
+++
jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/interpol/ConfigurationInterpolator.java
Sat Dec 30 08:04:03 2006
@@ -66,6 +66,15 @@
* <td>With this prefix a lookup object is associated that is able to resolve
* system properties.</td>
* </tr>
+ * <tr>
+ * <td valign="top">const</td>
+ * <td>The <code>const</code> prefix indicates that a variable is to be
+ * interpreted as a constant member field of a class (i.e. a field with the
+ * <b>static final</b> modifiers). The name of the variable must be of the form
+ * <code><full qualified class name>.<field name></code>, e.g.
+ *
<code>org.apache.commons.configuration.interpol.ConfigurationInterpolator.PREFIX_CONSTANTS
+ * </code>.</td>
+ * </tr>
* </table>
* </p>
* <p>
Modified:
jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationfactory.xml
URL:
http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationfactory.xml?view=diff&rev=491243&r1=491242&r2=491243
==============================================================================
---
jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationfactory.xml
(original)
+++
jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationfactory.xml
Sat Dec 30 08:04:03 2006
@@ -459,7 +459,12 @@
<dd>
With this element an instance of
<code>SystemConfiguration</code>
is added to the resulting configuration allowing access to
- system properties.
+ system properties. <em>Note:</em> This element is only
+ present for reasons of backward compatibility. With the
+ interpolation features introduced in version 1.4 (see
+ <a href="howto_basicfeatures.html#Variable_Interpolation">
+ Variable Interpolation</a> for more details) there is a much
+ easier way of accessing system properties.
</dd>
</dl>
</p>
@@ -553,6 +558,17 @@
by calling <code>System.setProperty("config.file",
"myfile.properties");</code>
or using the <code>-D</code> command line switch when starting your
Java application).
+ </p>
+ <p>
+ <em>Note:</em> Configuration definition files for
+ <code>ConfigurationFactory</code> are treated differently than other
+ configuration sources. So the standard interpolation features as
+ described in the section
+ <a href="howto_basicfeatures.html#Variable_Interpolation">
+ Variable Interpolation</a> do not work here. The variable
+ substitution facilities described in this section are specific to
+ <code>ConfigurationFactory</code> and differ from the default
+ handling of variables.
</p>
</subsection>
</section>
Modified: jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml
URL:
http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml?view=diff&rev=491243&r1=491242&r2=491243
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml
(original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml Sat
Dec 30 08:04:03 2006
@@ -112,8 +112,11 @@
<subsection name="Lists and arrays">
<p>
- Commons Configuration has the ability to return easily a list of
values,
- for example if your file contains a list of comma separated values:
+ As was already pointed out in the section
+ <a href="howto_basicfeatures.html#List_handling">List handling</a>
+ of <em>Basic features</em>, Commons Configuration has the ability to
+ return easily a list of values. For example a properties file can
+ contain a list of comma separated values:
</p>
<source>
# chart colors
@@ -138,80 +141,10 @@
colors.pie = #0000FF;
</source>
<p>
- The <code>addProperty()</code> and <code>setProperty()</code> methods
- also implement special list handling. The property value that is
passed
- to these methods can be a list or an array resulting in a property
- with multiple values. If the property value is a string, it is
checked
- whether it contains the <em>list delimiter character</em>. If this is
- the case, the string is splitted, and its single parts are added one
- by one. The list delimiter character is the comma by default. It is
- also applied to the properties when the configuration file is loaded
- (that's the reason why the example above with the comma separated
list
- of chart colors works). By using the <code>setListDelimiter()</code>
- method you can set it to a different character. Here are some
examples:
- </p>
-<source>
-// Change the list delimiter character to a slash
-config.setListDelimiter('/');
-// Now add some properties
-config.addProperty("greeting", "Hello, how are you?");
-config.addProperty("colors.pie",
- new String[] { "#FF0000", "#00FF00", "#0000FF" });
-config.addProperty("colors.graph", "#808080/#00FFCC/#6422FF");
-
-// Access data
-String salut = config.getString("greeting");
-List colPie = config.getList("colors.pie");
-String[] colGraph = config.getStringArray("colors.graph");
-
-String firstPieColor = config.getString("colors.pie");
-</source>
- <p>
- In this example the list delimiter character is changed from a comma
- to a slash. Because of this the <code>greeting</code> property won't
- be splitted, but remains a single string. The string passed as value
- for the <code>colors.graph</code> property in opposite contains the
- new delimiter character and thus will result in a property with three
- values.
- </p>
- <p>
- Of interest is also the last line of the example fragment. Here the
- <code>getString()</code> method is called for a property that has
- multiple values. This call will return the first value of the list.
- </p>
- <p>
- If you want to change the list delimiter character for all
configuration
- objects, you can use the static
<code>setDefaultListDelimiter()</code>
- method of <code>AbstractConfiguration</code>. It is also possible to
- disable splitting of string properties at all for a Configuration
- instance by calling its <code>setDelimiterParsingDisabled()</code>
- method with a value of <b>true</b>.
- </p>
- <p>
- <em>Note:</em> The list handling and string splitting facilities
- described in this section are not specific to
<code>PropertiesConfiguration</code>,
- but are also supported by other configuration classes.
- </p>
- </subsection>
-
- <subsection name="Variable Interpolation">
- <p>
- If you are familiar with Ant or Maven, you have most certainly
already encountered
- the variables (like <code>${token}</code>) that are automatically
expanded when the
- configuration file is loaded. Commons Configuration supports this
feature as well,
- here is an example:
- </p>
-<source>
-application.name = Killer App
-application.version = 1.6.2
-
-application.title = ${application.name} ${application.version}
-</source>
- <p>
- If you now retrieve the value for the <code>application.title</code>
- property, the result will be <code>Killer App 1.6.2</code>. As for
- list handling, variable interpolation is a feature supported by other
- configuration classes as well.
+ All of the features related to list handling described for
+ <code>AbstractConfiguration</code> also apply to properties files,
+ including changing the list delimiter or disabling list handling at
+ all.
</p>
</subsection>
Modified: jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml
URL:
http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml?view=diff&rev=491243&r1=491242&r2=491243
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml Sat Dec 30
08:04:03 2006
@@ -50,12 +50,18 @@
<li><a href="overview.html#Mixing_Configuration_Sources">Mixing
Configuration Sources</a></li>
<li><a href="overview.html#The_Configuration_interface">The
Configuration interface</a></li>
</ul>
+ <li><a
href="howto_basicfeatures.html#Basic_features_and_AbstractConfiguration">Basic
features and AbstractConfiguration</a></li>
+ <ul>
+ <li><a
href="howto_basicfeatures.html#Handling_of_missing_properties">Handling of
missing properties</a></li>
+ <li><a href="howto_basicfeatures.html#List_handling">List
handling</a></li>
+ <li><a href="howto_basicfeatures.html#Variable_Interpolation">Variable
Interpolation</a></li>
+ <li><a
href="howto_basicfeatures.html#Customizing_interpolation">Customizing
interpolation</a></li>
+ </ul>
<li><a href="howto_properties.html#Properties_files">Properties
files</a></li>
<ul>
<li><a
href="howto_properties.html#Using_PropertiesConfiguration">Using
PropertiesConfiguration</a></li>
<li><a href="howto_properties.html#Includes">Includes</a></li>
<li><a href="howto_properties.html#Lists_and_arrays">Lists and
arrays</a></li>
- <li><a href="howto_properties.html#Variable_Interpolation">Variable
Interpolation</a></li>
<li><a href="howto_properties.html#Saving">Saving</a></li>
<li><a href="howto_properties.html#Special_Characters">Special
Characters</a></li>
<li><a href="howto_properties.html#Layout_Objects">Layout
Objects</a></li>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
