Author: oheger
Date: Sun Nov 20 11:39:51 2005
New Revision: 345780
URL: http://svn.apache.org/viewcvs?rev=345780&view=rev
Log:
Dcoumentation updates
Modified:
jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/AbstractHierarchicalFileConfiguration.java
jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/PropertiesConfiguration.java
jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/XMLConfiguration.java
jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml
jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml
Modified:
jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/AbstractHierarchicalFileConfiguration.java
URL:
http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/AbstractHierarchicalFileConfiguration.java?rev=345780&r1=345779&r2=345780&view=diff
==============================================================================
---
jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/AbstractHierarchicalFileConfiguration.java
(original)
+++
jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/AbstractHierarchicalFileConfiguration.java
Sun Nov 20 11:39:51 2005
@@ -27,7 +27,11 @@
import org.apache.commons.configuration.reloading.ReloadingStrategy;
/**
- * Base class for implementing file based hierarchical configurations.
+ * <p>Base class for implementing file based hierarchical configurations.</p>
+ * <p>This class serves an analogous purpose as the
+ * <code>[EMAIL PROTECTED] AbstractFileConfiguration}</code> class for non
hierarchical
+ * configurations. It behaves in exactly the same way, so please refer to the
+ * documentation of <code>AbstractFileConfiguration</code> for further
details.</p>
*
* @since 1.2
*
Modified:
jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/PropertiesConfiguration.java
URL:
http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/PropertiesConfiguration.java?rev=345780&r1=345779&r2=345780&view=diff
==============================================================================
---
jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/PropertiesConfiguration.java
(original)
+++
jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/PropertiesConfiguration.java
Sun Nov 20 11:39:51 2005
@@ -67,8 +67,15 @@
* is placed at the end of the line that continues below.
* </li>
* <li>
- * If <i>value</i> is a list of strings, each token is separated
- * by a comma ',' by default.
+ * <i>value</i> can contain <em>value delimiters</em> and will then be
interpreted
+ * as a list of tokens. Default value delimiter is the comma ','. So the
+ * following property definition
+ * <pre>
+ * key = This property, has multiple, values
+ * </pre>
+ * will result in a property with three values. You can change the value
+ * delmiter using the <code>[EMAIL PROTECTED]
AbstractConfiguration#setDelimiter(char)}</code>
+ * method. Setting the delimiter to 0 will disable value splitting
completely.
* </li>
* <li>
* Commas in each token are escaped placing a backslash right before
Modified:
jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/XMLConfiguration.java
URL:
http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/XMLConfiguration.java?rev=345780&r1=345779&r2=345780&view=diff
==============================================================================
---
jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/XMLConfiguration.java
(original)
+++
jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/XMLConfiguration.java
Sun Nov 20 11:39:51 2005
@@ -67,6 +67,35 @@
* other documents (e.g. to a DTD), these references are resolved based on the
* path set for this configuration.</p>
*
+ * <p>By inheriting from <code>[EMAIL PROTECTED] AbstractConfiguration}</code>
this class
+ * provides some extended functionaly, e.g. interpolation of property values.
+ * Like in <code>[EMAIL PROTECTED] PropertiesConfiguration}</code> property
values can
+ * contain delimiter characters (the comma ',' per default) and are then
splitted
+ * into multiple values. This works for XML attributes and text content of
+ * elements as well. The delimiter can be escaped by a backslash. As an example
+ * consider the following XML fragment:</p>
+ *
+ * <p>
+ * <pre>
+ * <config>
+ * <array>10,20,30,40</array>
+ * <scalar>3\,1415</scalar>
+ * <cite text="To be or not to be\, this is the question!"/>
+ * </config>
+ * </pre>
+ * </p>
+ * <p>Here the content of the <code>array</code> element will be splitted at
+ * the commas, so the <code>array</code> key will be assigned 4 values. In the
+ * <code>scalar</code> property and the <code>text</code> attribute of the
+ * <code>cite</code> element the comma is escaped, so that no splitting is
+ * performed.</p>
+ *
+ * <p><code>XMLConfiguration</code> implements the <code>[EMAIL PROTECTED]
FileConfiguration}</code>
+ * interface and thus provides full support for loading XML documents from
+ * different sources like files, URLs, or streams. A full description of these
+ * features can be found in the documentation of
+ * <code>[EMAIL PROTECTED] AbstractFileConfiguration}</code>.</p>
+ *
* @since commons-configuration 1.0
*
* @author Jörg Schaible
Modified: jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml
URL:
http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml?rev=345780&r1=345779&r2=345780&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml
(original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml Sun
Nov 20 11:39:51 2005
@@ -56,6 +56,26 @@
<li>in the classpath</li>
</ul>
</p>
+ <p>
+ Instead of using a constructor that takes a file name you can also
+ invoke one of the <code>load()</code> methods. There are several
+ overloaded variants that allow to load properties from
+ <ul>
+ <li>a file, specified by either a path or a
<code>java.io.File</code>
+ object</li>
+ <li>a URL</li>
+ <li>an input stream or a reader.</li>
+ </ul>
+ </p>
+ <p>
+ Note that the <code>load()</code> methods do not empty the
+ configuration before new data is loaded. This makes it easy to
+ construct union configurations by simply calling <code>load()</code>
+ multiple times. But if you want to reuse a <code>Configuration</code>
+ object and load a different file, remember to call the
+ <code>clear()</code> method first to ensure that old properties are
+ wiped out.
+ </p>
</subsection>
<subsection name="Includes">
Modified: jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml
URL:
http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml?rev=345780&r1=345779&r2=345780&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml Sun Nov 20
11:39:51 2005
@@ -28,7 +28,7 @@
This section explains how to use hierarchical
and structured XML datasets.
</p>
- </section>
+ </section>
<section name="Hierarchical properties">
<p>
@@ -52,8 +52,13 @@
<text>#000000</text>
<header>#008000</header>
<link normal="#000080" visited="#800080"/>
+ <default>${colors.header}</default>
</colors>
<rowsPerPage>15</rowsPerPage>
+ <buttons>
+ <name>OK,Cancel,Help</name>
+ </buttons>
+ <numberFormat pattern="###\,###.##"/>
</gui-definition>
]]></source>
<p>
@@ -84,14 +89,17 @@
The following fragment shows how the properties can be
accessed:
</p>
<source><![CDATA[
-String backColor = config.getString("color.background");
-String textColor = config.getString("color.text");
-String linkNormal = config.getString("[EMAIL PROTECTED]");
+String backColor = config.getString("colors.background");
+String textColor = config.getString("colors.text");
+String linkNormal = config.getString("[EMAIL PROTECTED]");
+String defColor = config.getString("colors.default");
int rowsPerPage = config.getInt("rowsPerPage");
+List buttons = config.getList("buttons.name");
]]></source>
<p>
- This listing demonstrates some important points
of constructing
- keys for accessing properties load from XML
documents:
+ This listing demonstrates some important points
about constructing
+ keys for accessing properties load from XML
documents and about
+ features of <code>XMLConfiguration</code> in general:
<ul>
<li>
Nested elements are accessed
using a dot notation. In
@@ -110,6 +118,27 @@
Attributes of XML elements are
accessed in a XPath like
notation.
</li>
+ <li>
+ Interpolation can be used as in
<code>PropertiesConfiguration</code>.
+ Here the <code><default></code> element in the
+ <code>colors</code> section refers to another color.
+ </li>
+ <li>
+ Lists of properties can be defined in a short form
using
+ the delimiter character (which is the comma by
default).
+ In this example the <code>buttons.name</code> property
+ has the three values <em>OK</em>, <em>Cancel</em>, and
+ <em>Help</em>, so it is queried using the
<code>getList()</code>
+ method. This works in attributes, too. Using the static
+ <code>setDelimiter()</code> method of
+ <code>AbstractConfiguration</code> you can globally
+ define a different delimiter character or -
+ by setting the delimiter to 0 - disabling this
mechanism
+ completely. Placing a backslash before a delimiter
+ character will escape it. This is demonstrated in the
+ <code>pattern</code> attribute of the
<code>numberFormat</code>
+ element.
+ </li>
</ul>
</p>
<p>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
