Author: oheger
Date: Sat Jan 10 12:11:35 2009
New Revision: 733331
URL: http://svn.apache.org/viewvc?rev=733331&view=rev
Log:
CONFIGURATION-358: Improved documentation in the user's guide for hierarchical
configurations. Tried to make it more explicit that the features described for
XMLConfiguration apply to other hierarchical configuration implementations as
well.
Modified:
commons/proper/configuration/trunk/xdocs/changes.xml
commons/proper/configuration/trunk/xdocs/userguide/howto_xml.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=733331&r1=733330&r2=733331&view=diff
==============================================================================
--- commons/proper/configuration/trunk/xdocs/changes.xml (original)
+++ commons/proper/configuration/trunk/xdocs/changes.xml Sat Jan 10 12:11:35
2009
@@ -23,6 +23,9 @@
<body>
<release version="1.7" date="in SVN" description="">
+ <action dev="oheger" type="update" issue="CONFIGURATION-358">
+ Improvements of the user's guide for hierarchical configurations.
+ </action>
<action dev="oheger" type="fix" issue="CONFIGURATION-357">
The message of the ConversionException thrown by
AbstractConfiguration.getBigInteger() is now correct.
Modified: commons/proper/configuration/trunk/xdocs/userguide/howto_xml.xml
URL:
http://svn.apache.org/viewvc/commons/proper/configuration/trunk/xdocs/userguide/howto_xml.xml?rev=733331&r1=733330&r2=733331&view=diff
==============================================================================
--- commons/proper/configuration/trunk/xdocs/userguide/howto_xml.xml (original)
+++ commons/proper/configuration/trunk/xdocs/userguide/howto_xml.xml Sat Jan 10
12:11:35 2009
@@ -19,12 +19,12 @@
<document>
<properties>
- <title>XML Howto</title>
+ <title>Hierarchical configurations and XML Howto</title>
<author email="[email protected]">Oliver Heger</author>
</properties>
<body>
- <section name="Using XML based Configurations">
+ <section name="Using Hierarchical Configurations">
<p>
This section explains how to use hierarchical
and structured XML datasets.
@@ -33,14 +33,33 @@
<section name="Hierarchical properties">
<p>
- Because of its
- tree-like nature XML documents can represent data that
is
- structured in many ways. This section explains how to
deal with
- such structured documents and demonstrates the enhanced
query
- facilities supported by the <a
href="apidocs/org/apache/commons/configuration/XMLConfiguration.html">
- <code>XMLConfiguration</code></a> class.
+ Many sources of configuration data have a hierarchical or tree-like
+ nature. They can represent data that is structured in many ways.
+ Such configuration sources are represented by classes derived from
+ <a
href="../apidocs/org/apache/commons/configuration/HierarchicalConfiguration.html">
+ <code>HierarchicalConfiguration</code></a>.
+ </p>
+ <p>
+ Prominent examples of hierarchical configuration sources are XML
+ documents. They can be read and written using the
+ <a
href="../apidocs/org/apache/commons/configuration/XMLConfiguration.html">
+ <code>XMLConfiguration</code></a> class. This section explains how
+ to deal with such structured data and demonstrates the enhanced
query
+ facilities supported by <code>HierarchicalConfiguration</code>. We
+ use XML documents as examples for structured configuration sources,
+ but the information provided here (especially the rules for
accessing
+ properties) applies to other hierarchical configurations as well.
+ Examples for other hierarchical configuration classes are
+ <ul>
+ <li><a
href="../apidocs/org/apache/commons/configuration/CombinedConfiguration.html">
+ <code>CombinedConfiguration</code></a></li>
+ <li><a
href="../apidocs/org/apache/commons/configuration/HierarchicalINIConfiguration.html">
+ <code>HierarchicalINIConfiguration</code></a></li>
+ <li><a
href="../apidocs/org/apache/commons/configuration/plist/PropertyListConfiguration.html">
+ <code>PropertyListConfiguration</code></a></li>
+ </ul>
</p>
- <subsection name="Accessing properties defined in XML documents">
+ <subsection name="Accessing properties in hierarchical configurations">
<p>
We will start with a simple XML document to show some basics
about accessing properties. The following file named
@@ -89,6 +108,8 @@
<p>
If no exception was thrown, the properties
defined in the
XML document are now available in the configuration object.
+ Other hierarchical configuration classes that operate on files
+ have corresponding constructors and methods for loading their
data.
The following fragment shows how the properties can be
accessed:
</p>
<source><![CDATA[
@@ -101,8 +122,8 @@
]]></source>
<p>
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:
+ keys for accessing properties in hierarchical
configuration sources and about
+ features of <code>HierarchicalConfiguration</code> in general:
<ul>
<li>
Nested elements are accessed
using a dot notation. In
@@ -149,7 +170,7 @@
document can be processed.
</p>
</subsection>
- <subsection name="Structured XML">
+ <subsection name="Complex hierarchical structures">
<p>
Consider the following scenario: An application
operates on
database tables and wants to load a definition
of the database
@@ -333,7 +354,7 @@
These examples should make the usage of indices
quite clear.
Because each configuration key can contain an
arbitrary number
of indices it is possible to navigate through
complex structures of
- XML documents; each XML element can be uniquely
identified.
+ hierarchical configurations; each property can
be uniquely identified.
</p>
<p>
Sometimes dealing with long property keys may become
inconvenient,
@@ -388,7 +409,7 @@
for(Iterator it = fields.iterator(); it.hasNext();)
{
HierarchicalConfiguration sub = (HierarchicalConfiguration) it.next();
- // sub contains now all data about a single field
+ // sub contains all data about a single field
String fieldName = sub.getString("name");
String fieldType = sub.getString("type");
...
@@ -396,7 +417,7 @@
<p>
The configurations returned by the <code>configurationAt()</code> and
<code>configurationsAt()</code> method are in fact instances of the
- <a
href="apidocs/org/apache/commons/configuration/SubnodeConfiguration.html">
+ <a
href="../apidocs/org/apache/commons/configuration/SubnodeConfiguration.html">
<code>SubnodeConfiguration</code></a> class. The API documentation of
this class contains more information about its features and
limitations.
@@ -477,7 +498,7 @@
</field>
<field>
<name>version</name>
- <name>size</name> <== Newly added property
+ <name>size</name> <== Newly added property
<type>int</type>
</field>
</fields>
@@ -542,11 +563,16 @@
<code>HierarchicalConfiguration</code>.
</p>
</subsection>
- <subsection name="Escaping dot characters in XML tags">
+ <subsection name="Escaping dot characters in property names">
<p>
- In XML the dot character used as delimiter by most
configuration
- classes is a legal character that can occur in any tag. So the
- following XML document is completely valid:
+ Per default the dot character is used as delimiter by most
+ configuration classes (we will learn how to change this for
+ hierarchical configurations in a later section). In some
+ configuration formats however, dots can be contained in the
+ names of properties. For instance, in XML the dot is a legal
+ character that can occur in any tag. The same is true for the
names
+ of properties in windows ini files. So the following XML
+ document is completely valid:
</p>
<source><