commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject svn commit: r952622 [2/3] - in /commons/proper/configuration/trunk: conf/ src/java/org/apache/commons/configuration/ src/java/org/apache/commons/configuration/interpol/ src/java/org/apache/commons/configuration/reloading/ src/java/org/apache/commons/co...
Date Tue, 08 Jun 2010 11:56:31 GMT
Modified: commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_properties.xml
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_properties.xml?rev=952622&r1=952621&r2=952622&view=diff
==============================================================================
--- commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_properties.xml (original)
+++ commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_properties.xml Tue Jun  8 11:56:30 2010
@@ -1,210 +1,210 @@
-<?xml version="1.0"?>
-<!--
-   Licensed to the Apache Software Foundation (ASF) under one or more
-   contributor license agreements.  See the NOTICE file distributed with
-   this work for additional information regarding copyright ownership.
-   The ASF licenses this file to You under the Apache License, Version 2.0
-   (the "License"); you may not use this file except in compliance with
-   the License.  You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
--->
-
-<document>
-  <properties>
-    <title>Properties files</title>
-    <author email="smanux@lfjr.net">Emmanuel Bourg</author>
-    <author email="oliver.heger@t-online.de">Oliver Heger</author>
-  </properties>
-
-  <body>
-
-    <section name="Properties files">
-      <p>
-        Properties files are a popular mean of configuring applications. Of course Commons Configuration
-        supports this format and enhance significantly the basic <code>java.util.Properties</code> class.
-        This section introduces the features of the  <code>PropertiesConfiguration</code> class.
-      </p>
-
-      <subsection name="Loading">
-        <p>
-          At first lets consider that the whole configuration data of an application consists in
-          a single properties file named <code>usergui.properties</code> with the following content:
-        </p>
-        <source><![CDATA[
-# Properties definining the GUI
-colors.background = #FFFFFF
-]]></source>
-
-        <p>
-          To load this file, you'll write:
-        </p>
-<source>
-Configuration config = new PropertiesConfiguration("usergui.properties");
-</source>
-        <p>
-          If you do not specify an absolute path, the file will be searched automatically
-          in the following locations:
-          <ul>
-            <li>in the current directory</li>
-            <li>in the user home directory</li>
-            <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">
-        <p>
-          If a property is named "<code>include</code>" and the value of that property is the
-          name of a file on the disk, that file will be included into the configuration. Here is
-          an example:
-        </p>
-<source>
-# usergui.properties
-
-include = colors.properties
-include = sizes.properties
-</source>
-
-<source>
-# colors.properties
-
-colors.background = #FFFFFF
-</source>
-
-      </subsection>
-
-      <subsection name="Automatic Reloading">
-        <p>
-          A common issue with properties file is to handle the reloading of the file when it
-          changes. Typically you would use a thread monitoring the date of the file and reloading
-          the <code>Properties</code> when a more recent date is detected. Commons Configuration
-          integrates this mechanism out of the box, to enable it, just specify a reloading strategy
-          on your configuration:
-        </p>
-<source>
-PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties");
-config.setReloadingStrategy(new FileChangedReloadingStrategy());
-</source>
-        <p>
-          Now everytime you edit manually the <code>usergui.properties</code> file, the
-          configuration is automatically refreshed and the modified values are immediately
-          available to your application.
-        </p>
-
-      </subsection>
-
-      <subsection name="Saving">
-        <p>
-          To save your configuration, just call the <code>save()</code> method:
-        </p>
-<source>
-PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties");
-config.setProperty("colors.background", "#000000);
-config.save();
-</source>
-        <p>
-          You can also save a copy of the configuration to another file:
-        </p>
-<source>
-PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties");
-config.setProperty("colors.background", "#000000);
-config.save("usergui.backup.properties);
-</source>
-        <p>
-          And if you don't want to bother saving your configuration everytime it changes,
-          you can enable the automatic saving mode:
-        </p>
-<source>
-PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties");
-config.setAutoSave(true);
-config.setProperty("colors.background", "#000000); // the configuration is saved after this call
-</source>
-
-      </subsection>
-
-      <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:
-        </p>
-<source>
-# chart colors
-colors.pie = #FF0000, #00FF00, #0000FF
-</source>
-        <p>
-          You don't have to split the value manually, you can retrieve an array directly with:
-        </p>
-<source>
-String[] colors = config.getStringArray("colors.pie");
-</source>
-        <p>
-          Alternatively, you can specify a list of values in your properties file by using
-          the same key on several lines:
-        </p>
-<source>
-# chart colors
-colors.pie = #FF0000;
-colors.pie = #00FF00;
-colors.pie = #0000FF;
-</source>
-      </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>
-      </subsection>
-
-      <subsection name="Special Characters">
-        <p>
-          If you need a special character in a property like a line feed, a tabulation or
-          an unicode character, you can specify it with the same escaped notation used for
-          Java Strings. The list separator ("," by default), can also be escaped:
-        </p>
-        <source><![CDATA[
-key = This \n string \t contains \, escaped \\ characters \u0020
-]]></source>
-      </subsection>
-
-
-
-    </section>
-
-  </body>
-</document>
+<?xml version="1.0"?>
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+
+<document>
+  <properties>
+    <title>Properties files</title>
+    <author email="smanux@lfjr.net">Emmanuel Bourg</author>
+    <author email="oliver.heger@t-online.de">Oliver Heger</author>
+  </properties>
+
+  <body>
+
+    <section name="Properties files">
+      <p>
+        Properties files are a popular mean of configuring applications. Of course Commons Configuration
+        supports this format and enhance significantly the basic <code>java.util.Properties</code> class.
+        This section introduces the features of the  <code>PropertiesConfiguration</code> class.
+      </p>
+
+      <subsection name="Loading">
+        <p>
+          At first lets consider that the whole configuration data of an application consists in
+          a single properties file named <code>usergui.properties</code> with the following content:
+        </p>
+        <source><![CDATA[
+# Properties definining the GUI
+colors.background = #FFFFFF
+]]></source>
+
+        <p>
+          To load this file, you'll write:
+        </p>
+<source>
+Configuration config = new PropertiesConfiguration("usergui.properties");
+</source>
+        <p>
+          If you do not specify an absolute path, the file will be searched automatically
+          in the following locations:
+          <ul>
+            <li>in the current directory</li>
+            <li>in the user home directory</li>
+            <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">
+        <p>
+          If a property is named "<code>include</code>" and the value of that property is the
+          name of a file on the disk, that file will be included into the configuration. Here is
+          an example:
+        </p>
+<source>
+# usergui.properties
+
+include = colors.properties
+include = sizes.properties
+</source>
+
+<source>
+# colors.properties
+
+colors.background = #FFFFFF
+</source>
+
+      </subsection>
+
+      <subsection name="Automatic Reloading">
+        <p>
+          A common issue with properties file is to handle the reloading of the file when it
+          changes. Typically you would use a thread monitoring the date of the file and reloading
+          the <code>Properties</code> when a more recent date is detected. Commons Configuration
+          integrates this mechanism out of the box, to enable it, just specify a reloading strategy
+          on your configuration:
+        </p>
+<source>
+PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties");
+config.setReloadingStrategy(new FileChangedReloadingStrategy());
+</source>
+        <p>
+          Now everytime you edit manually the <code>usergui.properties</code> file, the
+          configuration is automatically refreshed and the modified values are immediately
+          available to your application.
+        </p>
+
+      </subsection>
+
+      <subsection name="Saving">
+        <p>
+          To save your configuration, just call the <code>save()</code> method:
+        </p>
+<source>
+PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties");
+config.setProperty("colors.background", "#000000);
+config.save();
+</source>
+        <p>
+          You can also save a copy of the configuration to another file:
+        </p>
+<source>
+PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties");
+config.setProperty("colors.background", "#000000);
+config.save("usergui.backup.properties);
+</source>
+        <p>
+          And if you don't want to bother saving your configuration everytime it changes,
+          you can enable the automatic saving mode:
+        </p>
+<source>
+PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties");
+config.setAutoSave(true);
+config.setProperty("colors.background", "#000000); // the configuration is saved after this call
+</source>
+
+      </subsection>
+
+      <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:
+        </p>
+<source>
+# chart colors
+colors.pie = #FF0000, #00FF00, #0000FF
+</source>
+        <p>
+          You don't have to split the value manually, you can retrieve an array directly with:
+        </p>
+<source>
+String[] colors = config.getStringArray("colors.pie");
+</source>
+        <p>
+          Alternatively, you can specify a list of values in your properties file by using
+          the same key on several lines:
+        </p>
+<source>
+# chart colors
+colors.pie = #FF0000;
+colors.pie = #00FF00;
+colors.pie = #0000FF;
+</source>
+      </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>
+      </subsection>
+
+      <subsection name="Special Characters">
+        <p>
+          If you need a special character in a property like a line feed, a tabulation or
+          an unicode character, you can specify it with the same escaped notation used for
+          Java Strings. The list separator ("," by default), can also be escaped:
+        </p>
+        <source><![CDATA[
+key = This \n string \t contains \, escaped \\ characters \u0020
+]]></source>
+      </subsection>
+
+
+
+    </section>
+
+  </body>
+</document>

Propchange: commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_properties.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_xml.xml
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_xml.xml?rev=952622&r1=952621&r2=952622&view=diff
==============================================================================
--- commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_xml.xml (original)
+++ commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_xml.xml Tue Jun  8 11:56:30 2010
@@ -1,573 +1,573 @@
-<?xml version="1.0"?>
-<!--
-   Licensed to the Apache Software Foundation (ASF) under one or more
-   contributor license agreements.  See the NOTICE file distributed with
-   this work for additional information regarding copyright ownership.
-   The ASF licenses this file to You under the Apache License, Version 2.0
-   (the "License"); you may not use this file except in compliance with
-   the License.  You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
--->
-
-<document>
-
- <properties>
-  <title>XML Howto</title>
-  <author email="oliver.heger@t-online.de">Oliver Heger</author>
- </properties>
-
-<body>		
-	<section name="Using XML based Configurations">
-		<p>
- 	 		This section explains how to use hierarchical
-    		and structured XML datasets.
-    	</p>
-    </section>
-
-	<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 <code>XMLConfiguration</code> class..
-		</p>
-        <subsection name="Accessing properties defined in XML documents">
-            <p>
-                We will start with a simple XML document to show some basics
-                about accessing properties. The following file named
-                <code>gui.xml</code> is used as example document:
-            </p>
-   			<source><![CDATA[
-<?xml version="1.0" encoding="ISO-8859-1" ?>
-<gui-definition>
-  <colors>
-    <background>#808080</background>
-    <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>
-				(As becomes obvious, this tutorial does not bother with good
-				design of XML documents, the example file should rather 
-				demonstrate the different ways of accessing properties.)
-				To access the data stored in this document it must be loaded
-                by <code>XMLConfiguration</code>. Like other file based
-                configuration classes <code>XMLConfiguration</code> supports
-                many ways of specifying the file to process. One way is to
-                pass the file name to the constructor as shown in the following
-                code fragment:
-			</p>
-   			<source><![CDATA[
-try
-{
-    XMLConfiguration config = new XMLConfiguration("tables.xml");
-    // do something with config
-}
-catch(ConfigurationException cex)
-{
-    // something went wrong, e.g. the file was not found
-}
-]]></source>
-			<p>
-				If no exception was thrown, the properties defined in the
-                XML document are now available in the configuration object.
-                The following fragment shows how the properties can be accessed:
-			</p>
-   			<source><![CDATA[
-String backColor = config.getString("colors.background");
-String textColor = config.getString("colors.text");
-String linkNormal = config.getString("colors.link[@normal]");
-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 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
-						the example document there is an element
-						<code>&lt;text&gt;</code> in the body of the
-						<code>&lt;color&gt;</code> element. The corresponding
-						key is <code>color.text</code>.
-					</li>
-					<li>
-						The root element is ignored when constructing keys. In
-						the example you do not write
-						<code>gui-definition.color.text</code>, but only
-						<code>color.text</code>.
-					</li>
-					<li>
-						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>&lt;default&gt;</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>
-                In the next section will show how data in a more complex XML
-                document can be processed.
-            </p>
-        </subsection>
-		<subsection name="Structured XML">
-			<p>
-				Consider the following scenario: An application operates on
-				database tables and wants to load a definition of the database
-				schema from its configuration. A XML document provides this
-				information. It could look as follows:
-			</p>
-   			<source><![CDATA[
-<?xml version="1.0" encoding="ISO-8859-1" ?>
-
-<database>
-  <tables>
-    <table tableType="system">
-      <name>users</name>
-      <fields>
-        <field>
-          <name>uid</name>
-          <type>long</type>
-        </field>
-        <field>
-          <name>uname</name>
-          <type>java.lang.String</type>
-        </field>
-        <field>
-          <name>firstName</name>
-          <type>java.lang.String</type>
-        </field>
-        <field>
-          <name>lastName</name>
-          <type>java.lang.String</type>
-        </field>
-        <field>
-          <name>email</name>
-          <type>java.lang.String</type>
-        </field>
-      </fields>
-    </table>
-    <table tableType="application">
-      <name>documents</name>
-      <fields>
-        <field>
-          <name>docid</name>
-          <type>long</type>
-        </field>
-        <field>
-          <name>name</name>
-          <type>java.lang.String</type>
-        </field>
-        <field>
-          <name>creationDate</name>
-          <type>java.util.Date</type>
-        </field>
-        <field>
-          <name>authorID</name>
-          <type>long</type>
-        </field>
-        <field>
-          <name>version</name>
-          <type>int</type>
-        </field>
-      </fields>
-    </table>
-  </tables>
-</database>
-]]></source>
-			<p>
-				This XML is quite self explanatory; there is an arbitrary number
-				of table elements, each of it has a name and a list of fields.
-				A field in turn consists of a name and a data type. This
-                XML document (let's call it <code>tables.xml</code>) can be
-                loaded in exactly the same way as the simple document in the
-                section before.
-			</p>
-			<p>
-				When we now want to access some of the properties we face a
-                problem: the syntax for	constructing configuration keys we
-                learned so far is not powerful enough to access all of the data
-                stored in the tables document.
-			</p>
-			<p>
-				Because the document contains a list of tables some properties
-				are defined more than once. E.g. the configuration key
-				<code>tables.table.name</code> refers to a <code>name</code>
-				element inside a <code>table</code> element inside a
-				<code>tables</code> element. This constellation happens to
-				occur twice in the tables document.
-			</p>
-			<p>
-				Multiple definitions of a property do not cause problems and are
-				supported by all classes of Configuration. If such a property
-				is queried using <code>getProperty()</code>, the method
-				recognizes that there are multiple values for that property and
-				returns a collection with all these values. So we could write
-			</p>
-   			<source><![CDATA[
-Object prop = config.getProperty("tables.table.name");
-if(prop instanceof Collection)
-{
-	System.out.println("Number of tables: " + ((Collection) prop).size());
-}
-]]></source>
-			<p>
-				An alternative to this code would be the <code>getList()</code>
-				method of <code>Configuration</code>. If a property is known to
-				have multiple values (as is the table name property in this example),
-				<code>getList()</code> allows to retrieve all values at once.
-				<b>Note:</b> it is legal to call <code>getString()</code>
-				or one of the other getter methods on a property with multiple
-				values; it returns the first element of the list.
-			</p>
-		</subsection>
-		<subsection name="Accessing structured properties">
-			<p>
-				Okay, we can obtain a list with the name of all defined
-				tables. In the same way we can retrieve a list with the names
-				of all table fields: just pass the key
-				<code>tables.table.fields.field.name</code> to the
-				<code>getList()</code> method. In our example this list
-				would contain 10 elements, the names of all fields of all tables.
-				This is fine, but how do we know, which field belongs to
-				which table?
-			</p>
-			<p>
-				When working with such hierarchical structures the configuration keys
-				used to query properties can have an extended syntax. All components
-				of a key can be appended by a numerical value in parentheses that
-				determines the index of the affected property. So if we have two
-				<code>table</code> elements we can exactly specify, which one we
-				want to address by appending the corresponding index. This is
-				explained best by some examples:
-			</p>
-			<p>
-				We will now provide some configuration keys and show the results
-				of a <code>getProperty()</code> call with these keys as arguments.
-				<dl>
-					<dt><code>tables.table(0).name</code></dt>
-					<dd>
-						Returns the name of the first table (all indices are 0 based),
-						in this example the string <em>users</em>.
-					</dd>
-					<dt><code>tables.table(0)[@tableType]</code></dt>
-					<dd>
-						Returns the value of the tableType attribute of the first
-						table (<em>system</em>).
-					</dd>
-					<dt><code>tables.table(1).name</code></dt>
-					<dd>
-						Analogous to the first example returns the name of the
-						second table (<em>documents</em>).
-					</dd>
-					<dt><code>tables.table(2).name</code></dt>
-					<dd>
-						Here the name of a third table is queried, but because there
-						are only two tables result is <b>null</b>. The fact that a
-						<b>null</b> value is returned for invalid indices can be used
-						to find out how many values are defined for a certain property:
-						just increment the index in a loop as long as valid objects
-						are returned.
-					</dd>
-					<dt><code>tables.table(1).fields.field.name</code></dt>
-					<dd>
-						Returns a collection with the names of all fields that
-						belong to the second table. With such kind of keys it is
-						now possible to find out, which fields belong to which table.
-					</dd>
-					<dt><code>tables.table(1).fields.field(2).name</code></dt>
-					<dd>
-						The additional index after field selects a certain field.
-						This expression represents the name of the third field in
-						the second table (<em>creationDate</em>).
-					</dd>
-					<dt><code>tables.table.fields.field(0).type</code></dt>
-					<dd>
-						This key may be a bit unusual but nevertheless completely
-						valid. It selects the data types of the first fields in all
-						tables. So here a collection would be returned with the
-						values [<em>long, long</em>].
-					</dd>
-				</dl>
-			</p>
-			<p>
-				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.
-			</p>
-		</subsection>
-		<subsection name="Adding new properties">
-			<p>
-				So far we have learned how to use indices to avoid ambiguities when
-				querying properties. The same problem occurs when adding new
-				properties to a structured configuration. As an example let's
-				assume we want to add a new field to the second table. New properties
-				can be added to a configuration using the <code>addProperty()</code>
-				method. Of course, we have to exactly specify where in the tree like structure new
-				data is to be inserted. A statement like
-			</p>
-   			<source><![CDATA[
-// Warning: This might cause trouble!
-config.addProperty("tables.table.fields.field.name", "size");
-]]></source>
-			<p>
-				would not be sufficient because it does not contain all needed
-				information. How is such a statement processed by the
-				<code>addProperty()</code> method?
-			</p>
-			<p>
-				<code>addProperty()</code> splits the provided key into its
-				single parts and navigates through the properties tree along the
-				corresponding element names. In this example it will start at the
-				root element and then find the <code>tables</code> element. The
-				next key part to be processed is <code>table</code>, but here a
-				problem occurs: the configuration contains two <code>table</code>
-				properties below the <code>tables</code> element. To get rid off
-				this ambiguity an index can be specified at this position in the
-				key that makes clear, which of the two properties should be
-				followed. <code>tables.table(1).fields.field.name</code> e.g.
-				would select the second <code>table</code> property. If an index
-				is missing, <code>addProperty()</code> always follows the last
-				available element. In our example this would be the second
-				<code>table</code>, too.
-			</p>
-			<p>
-				The following parts of the key are processed in exactly the same
-				manner. Under the selected <code>table</code> property there is
-				exactly one <code>fields</code> property, so this step is not
-				problematic at all. In the next step the <code>field</code> part
-				has to be processed. At the actual position in the properties tree
-				there are multiple <code>field</code> (sub) properties. So we here
-				have the same situation as for the <code>table</code> part.
-				Because no explicit index is defined the last <code>field</code>
-				property is selected. The last part of the key passed to
-				<code>addProperty()</code> (<code>name</code> in this example)
-				will always be added as new property at the position that has
-				been reached in the former processing steps. So in our example
-				the last <code>field</code> property of the second table would
-				be given a new <code>name</code> sub property and the resulting
-				structure would look like the following listing:
-			</p>
-   			<source><![CDATA[
-	...
-    <table tableType="application">
-      <name>documents</name>
-      <fields>
-        <field>
-          <name>docid</name>
-          <type>long</type>
-        </field>
-        <field>
-          <name>name</name>
-          <type>java.lang.String</type>
-        </field>
-        <field>
-          <name>creationDate</name>
-          <type>java.util.Date</type>
-        </field>
-        <field>
-          <name>authorID</name>
-          <type>long</type>
-        </field>
-        <field>
-          <name>version</name>
-		  <name>size</name>    <== Newly added property
-          <type>int</type>
-        </field>
-      </fields>
-    </table>
-  </tables>
-</database>
-]]></source>
-			<p>
-				This result is obviously not what was desired, but it demonstrates
-				how <code>addProperty()</code> works: the method follows an
-				existing branch in the properties tree and adds new leaves to it.
-				(If the passed in key does not match a branch in the existing tree,
-				a new branch will be added. E.g. if we pass the key
-				<code>tables.table.data.first.test</code>, the existing tree can be
-				navigated until the <code>data</code> part of the key. From here a
-				new branch is started with the remaining parts <code>data</code>,
-				<code>first</code> and <code>test</code>.)
-			</p>
-			<p>
-				If we want a different behavior, we must explicitely tell
-				<code>addProperty()</code> what to do. In our example with the
-				new field our intension was to create a new branch for the
-				<code>field</code> part in the key, so that a new <code>field</code>
-				property is added to the structure rather than adding sub properties
-				to the last existing <code>field</code> property. This can be
-				achieved by specifying the special index <code>(-1)</code> at the
-				corresponding position in the key as shown below:
-			</p>
-   			<source><![CDATA[
-config.addProperty("tables.table(1).fields.field(-1).name", "size");
-config.addProperty("tables.table(1).fields.field.type", "int");
-]]></source>
-			<p>
-				The first line in this fragment specifies that a new branch is
-				to be created for the <code>field</code> property (index -1).
-				In the second line no index is specified for the field, so the
-				last one is used - which happens to be the field that has just
-				been created. So these two statements add a fully defined field
-				to the second table. This is the default pattern for adding new
-				properties or whole hierarchies of properties: first create a new
-				branch in the properties tree and then populate its sub properties.
-				As an additional example let's add a complete new table definition
-				to our example configuration:
-			</p>
-   			<source><![CDATA[
-// Add a new table element and define the name
-config.addProperty("tables.table(-1).name", "versions");
-
-// Add a new field to the new table
-// (an index for the table is not necessary because the latest is used)
-config.addProperty("tables.table.fields.field(-1).name", "id");
-config.addProperty("tables.table.fields.field.type", "int");
-
-// Add another field to the new table
-config.addProperty("tables.table.fields.field(-1).name", "date");
-config.addProperty("tables.table.fields.field.type", "java.sql.Date");
-...
-]]></source>
-			<p>
-				For more information about adding properties to a hierarchical
-				configuration also have a look at the javadocs for
-				<code>HierarchicalConfiguration</code>.
-			</p>
-		</subsection>
-		<subsection name="Escaping dot characters in XML tags">
-			<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:
-			</p>
-   			<source><![CDATA[
-<?xml version="1.0" encoding="ISO-8859-1" ?>
-
-<configuration>
-  <test.value>42</test.value>
-  <test.complex>
-    <test.sub.element>many dots</test.sub.element>
-  </test.complex>
-</configuration>
-]]></source>
-			<p>
-                This XML document can be loaded by <code>XMLConfiguration</code>
-                without trouble, but when we want to access certain properties
-                we face a problem: The configuration claims that it does not
-                store any values for the properties with the keys
-                <code>test.value</code> or <code>test.complex.test.sub.element</code>!
-            </p>
-            <p>
-                Of course, it is the dot character contained in the property
-                names, which causes this problem. A dot is always interpreted
-                as a delimiter between elements. So given the property key
-                <code>test.value</code> the configuration would look for an
-                element named <code>test</code> and then for a sub element
-                with the name <code>value</code>. To change this behavior it is
-                possible to escape a dot character, thus telling the configuration
-                that it is really part of an element name. This is simply done
-                by duplicating the dot. So the following statements will return
-                the desired property values:
-            </p>
-   			<source><![CDATA[
-int testVal = config.getInt("test..value");
-String complex = config.getString("test..complex.test..sub..element");
-]]></source>
-            <p>
-                Note the duplicated dots whereever the dot does not act as
-                delimiter. This way it is possible to access properties containing
-                dots in arbitrary combination. However, as you can see, the
-                escaping can be confusing sometimes. So if you have a choice,
-                you should avoid dots in the tag names of your XML configuration
-                files.
-            </p>
-        </subsection>
-	</section>
-    
-    <section name="Validation of XML configuration files">
-        <p>
-            XML parsers provide support for validation of XML documents to ensure that they
-            conform to a certain DTD. This feature can be useful for
-            configuration files, too. <code>XMLConfiguration</code> allows to enable
-            validation for the files to load.
-        </p>
-        <p>
-            The easiest way to turn on validation is to simply set the
-            <code>validating</code> property to true as shown in the
-            following example:
-        </p>
-        <source><![CDATA[
-XMLConfiguration config = new XMLConfiguration();
-config.setFileName("myconfig.xml");
-config.setValidating(true);
-
-// This will throw a ConfigurationException if the XML document does not
-// conform to its DTD.
-config.load();
-]]></source>
-        <p>
-            Setting the <code>validating</code> flag to true will cause
-            <code>XMLConfiguration</code> to use a validating XML parser. At this parser
-            a custom <code>ErrorHandler</code> will be registered, which throws
-            exceptions on simple and fatal parsing errors.
-        </p>
-        <p>
-            While using the <code>validating</code> flag is a simple means of
-            enabling validation it cannot fullfil more complex requirements,
-            e.g. schema validation. To be able to deal with such requirements
-            XMLConfiguration provides a generic way of setting up the XML
-            parser to use: A preconfigured <code>DocumentBuilder</code> object
-            can be passed to the <code>setDocumentBuilder()</code> method.
-        </p>
-        <p>
-            So an application can create a <code>DocumentBuilder</code> object
-            and initialize it according to its special needs. Then this
-            object must be passed to the <code>XMLConfiguration</code> instance
-            before invocation of the <code>load()</code> method. When loading
-            a configuration file, the passed in <code>DocumentBuilder</code> will
-            be used instead of the default one.
-        </p>
-    </section>
-</body>
-
+<?xml version="1.0"?>
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+
+<document>
+
+ <properties>
+  <title>XML Howto</title>
+  <author email="oliver.heger@t-online.de">Oliver Heger</author>
+ </properties>
+
+<body>		
+	<section name="Using XML based Configurations">
+		<p>
+ 	 		This section explains how to use hierarchical
+    		and structured XML datasets.
+    	</p>
+    </section>
+
+	<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 <code>XMLConfiguration</code> class..
+		</p>
+        <subsection name="Accessing properties defined in XML documents">
+            <p>
+                We will start with a simple XML document to show some basics
+                about accessing properties. The following file named
+                <code>gui.xml</code> is used as example document:
+            </p>
+   			<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<gui-definition>
+  <colors>
+    <background>#808080</background>
+    <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>
+				(As becomes obvious, this tutorial does not bother with good
+				design of XML documents, the example file should rather 
+				demonstrate the different ways of accessing properties.)
+				To access the data stored in this document it must be loaded
+                by <code>XMLConfiguration</code>. Like other file based
+                configuration classes <code>XMLConfiguration</code> supports
+                many ways of specifying the file to process. One way is to
+                pass the file name to the constructor as shown in the following
+                code fragment:
+			</p>
+   			<source><![CDATA[
+try
+{
+    XMLConfiguration config = new XMLConfiguration("tables.xml");
+    // do something with config
+}
+catch(ConfigurationException cex)
+{
+    // something went wrong, e.g. the file was not found
+}
+]]></source>
+			<p>
+				If no exception was thrown, the properties defined in the
+                XML document are now available in the configuration object.
+                The following fragment shows how the properties can be accessed:
+			</p>
+   			<source><![CDATA[
+String backColor = config.getString("colors.background");
+String textColor = config.getString("colors.text");
+String linkNormal = config.getString("colors.link[@normal]");
+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 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
+						the example document there is an element
+						<code>&lt;text&gt;</code> in the body of the
+						<code>&lt;color&gt;</code> element. The corresponding
+						key is <code>color.text</code>.
+					</li>
+					<li>
+						The root element is ignored when constructing keys. In
+						the example you do not write
+						<code>gui-definition.color.text</code>, but only
+						<code>color.text</code>.
+					</li>
+					<li>
+						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>&lt;default&gt;</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>
+                In the next section will show how data in a more complex XML
+                document can be processed.
+            </p>
+        </subsection>
+		<subsection name="Structured XML">
+			<p>
+				Consider the following scenario: An application operates on
+				database tables and wants to load a definition of the database
+				schema from its configuration. A XML document provides this
+				information. It could look as follows:
+			</p>
+   			<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<database>
+  <tables>
+    <table tableType="system">
+      <name>users</name>
+      <fields>
+        <field>
+          <name>uid</name>
+          <type>long</type>
+        </field>
+        <field>
+          <name>uname</name>
+          <type>java.lang.String</type>
+        </field>
+        <field>
+          <name>firstName</name>
+          <type>java.lang.String</type>
+        </field>
+        <field>
+          <name>lastName</name>
+          <type>java.lang.String</type>
+        </field>
+        <field>
+          <name>email</name>
+          <type>java.lang.String</type>
+        </field>
+      </fields>
+    </table>
+    <table tableType="application">
+      <name>documents</name>
+      <fields>
+        <field>
+          <name>docid</name>
+          <type>long</type>
+        </field>
+        <field>
+          <name>name</name>
+          <type>java.lang.String</type>
+        </field>
+        <field>
+          <name>creationDate</name>
+          <type>java.util.Date</type>
+        </field>
+        <field>
+          <name>authorID</name>
+          <type>long</type>
+        </field>
+        <field>
+          <name>version</name>
+          <type>int</type>
+        </field>
+      </fields>
+    </table>
+  </tables>
+</database>
+]]></source>
+			<p>
+				This XML is quite self explanatory; there is an arbitrary number
+				of table elements, each of it has a name and a list of fields.
+				A field in turn consists of a name and a data type. This
+                XML document (let's call it <code>tables.xml</code>) can be
+                loaded in exactly the same way as the simple document in the
+                section before.
+			</p>
+			<p>
+				When we now want to access some of the properties we face a
+                problem: the syntax for	constructing configuration keys we
+                learned so far is not powerful enough to access all of the data
+                stored in the tables document.
+			</p>
+			<p>
+				Because the document contains a list of tables some properties
+				are defined more than once. E.g. the configuration key
+				<code>tables.table.name</code> refers to a <code>name</code>
+				element inside a <code>table</code> element inside a
+				<code>tables</code> element. This constellation happens to
+				occur twice in the tables document.
+			</p>
+			<p>
+				Multiple definitions of a property do not cause problems and are
+				supported by all classes of Configuration. If such a property
+				is queried using <code>getProperty()</code>, the method
+				recognizes that there are multiple values for that property and
+				returns a collection with all these values. So we could write
+			</p>
+   			<source><![CDATA[
+Object prop = config.getProperty("tables.table.name");
+if(prop instanceof Collection)
+{
+	System.out.println("Number of tables: " + ((Collection) prop).size());
+}
+]]></source>
+			<p>
+				An alternative to this code would be the <code>getList()</code>
+				method of <code>Configuration</code>. If a property is known to
+				have multiple values (as is the table name property in this example),
+				<code>getList()</code> allows to retrieve all values at once.
+				<b>Note:</b> it is legal to call <code>getString()</code>
+				or one of the other getter methods on a property with multiple
+				values; it returns the first element of the list.
+			</p>
+		</subsection>
+		<subsection name="Accessing structured properties">
+			<p>
+				Okay, we can obtain a list with the name of all defined
+				tables. In the same way we can retrieve a list with the names
+				of all table fields: just pass the key
+				<code>tables.table.fields.field.name</code> to the
+				<code>getList()</code> method. In our example this list
+				would contain 10 elements, the names of all fields of all tables.
+				This is fine, but how do we know, which field belongs to
+				which table?
+			</p>
+			<p>
+				When working with such hierarchical structures the configuration keys
+				used to query properties can have an extended syntax. All components
+				of a key can be appended by a numerical value in parentheses that
+				determines the index of the affected property. So if we have two
+				<code>table</code> elements we can exactly specify, which one we
+				want to address by appending the corresponding index. This is
+				explained best by some examples:
+			</p>
+			<p>
+				We will now provide some configuration keys and show the results
+				of a <code>getProperty()</code> call with these keys as arguments.
+				<dl>
+					<dt><code>tables.table(0).name</code></dt>
+					<dd>
+						Returns the name of the first table (all indices are 0 based),
+						in this example the string <em>users</em>.
+					</dd>
+					<dt><code>tables.table(0)[@tableType]</code></dt>
+					<dd>
+						Returns the value of the tableType attribute of the first
+						table (<em>system</em>).
+					</dd>
+					<dt><code>tables.table(1).name</code></dt>
+					<dd>
+						Analogous to the first example returns the name of the
+						second table (<em>documents</em>).
+					</dd>
+					<dt><code>tables.table(2).name</code></dt>
+					<dd>
+						Here the name of a third table is queried, but because there
+						are only two tables result is <b>null</b>. The fact that a
+						<b>null</b> value is returned for invalid indices can be used
+						to find out how many values are defined for a certain property:
+						just increment the index in a loop as long as valid objects
+						are returned.
+					</dd>
+					<dt><code>tables.table(1).fields.field.name</code></dt>
+					<dd>
+						Returns a collection with the names of all fields that
+						belong to the second table. With such kind of keys it is
+						now possible to find out, which fields belong to which table.
+					</dd>
+					<dt><code>tables.table(1).fields.field(2).name</code></dt>
+					<dd>
+						The additional index after field selects a certain field.
+						This expression represents the name of the third field in
+						the second table (<em>creationDate</em>).
+					</dd>
+					<dt><code>tables.table.fields.field(0).type</code></dt>
+					<dd>
+						This key may be a bit unusual but nevertheless completely
+						valid. It selects the data types of the first fields in all
+						tables. So here a collection would be returned with the
+						values [<em>long, long</em>].
+					</dd>
+				</dl>
+			</p>
+			<p>
+				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.
+			</p>
+		</subsection>
+		<subsection name="Adding new properties">
+			<p>
+				So far we have learned how to use indices to avoid ambiguities when
+				querying properties. The same problem occurs when adding new
+				properties to a structured configuration. As an example let's
+				assume we want to add a new field to the second table. New properties
+				can be added to a configuration using the <code>addProperty()</code>
+				method. Of course, we have to exactly specify where in the tree like structure new
+				data is to be inserted. A statement like
+			</p>
+   			<source><![CDATA[
+// Warning: This might cause trouble!
+config.addProperty("tables.table.fields.field.name", "size");
+]]></source>
+			<p>
+				would not be sufficient because it does not contain all needed
+				information. How is such a statement processed by the
+				<code>addProperty()</code> method?
+			</p>
+			<p>
+				<code>addProperty()</code> splits the provided key into its
+				single parts and navigates through the properties tree along the
+				corresponding element names. In this example it will start at the
+				root element and then find the <code>tables</code> element. The
+				next key part to be processed is <code>table</code>, but here a
+				problem occurs: the configuration contains two <code>table</code>
+				properties below the <code>tables</code> element. To get rid off
+				this ambiguity an index can be specified at this position in the
+				key that makes clear, which of the two properties should be
+				followed. <code>tables.table(1).fields.field.name</code> e.g.
+				would select the second <code>table</code> property. If an index
+				is missing, <code>addProperty()</code> always follows the last
+				available element. In our example this would be the second
+				<code>table</code>, too.
+			</p>
+			<p>
+				The following parts of the key are processed in exactly the same
+				manner. Under the selected <code>table</code> property there is
+				exactly one <code>fields</code> property, so this step is not
+				problematic at all. In the next step the <code>field</code> part
+				has to be processed. At the actual position in the properties tree
+				there are multiple <code>field</code> (sub) properties. So we here
+				have the same situation as for the <code>table</code> part.
+				Because no explicit index is defined the last <code>field</code>
+				property is selected. The last part of the key passed to
+				<code>addProperty()</code> (<code>name</code> in this example)
+				will always be added as new property at the position that has
+				been reached in the former processing steps. So in our example
+				the last <code>field</code> property of the second table would
+				be given a new <code>name</code> sub property and the resulting
+				structure would look like the following listing:
+			</p>
+   			<source><![CDATA[
+	...
+    <table tableType="application">
+      <name>documents</name>
+      <fields>
+        <field>
+          <name>docid</name>
+          <type>long</type>
+        </field>
+        <field>
+          <name>name</name>
+          <type>java.lang.String</type>
+        </field>
+        <field>
+          <name>creationDate</name>
+          <type>java.util.Date</type>
+        </field>
+        <field>
+          <name>authorID</name>
+          <type>long</type>
+        </field>
+        <field>
+          <name>version</name>
+		  <name>size</name>    <== Newly added property
+          <type>int</type>
+        </field>
+      </fields>
+    </table>
+  </tables>
+</database>
+]]></source>
+			<p>
+				This result is obviously not what was desired, but it demonstrates
+				how <code>addProperty()</code> works: the method follows an
+				existing branch in the properties tree and adds new leaves to it.
+				(If the passed in key does not match a branch in the existing tree,
+				a new branch will be added. E.g. if we pass the key
+				<code>tables.table.data.first.test</code>, the existing tree can be
+				navigated until the <code>data</code> part of the key. From here a
+				new branch is started with the remaining parts <code>data</code>,
+				<code>first</code> and <code>test</code>.)
+			</p>
+			<p>
+				If we want a different behavior, we must explicitely tell
+				<code>addProperty()</code> what to do. In our example with the
+				new field our intension was to create a new branch for the
+				<code>field</code> part in the key, so that a new <code>field</code>
+				property is added to the structure rather than adding sub properties
+				to the last existing <code>field</code> property. This can be
+				achieved by specifying the special index <code>(-1)</code> at the
+				corresponding position in the key as shown below:
+			</p>
+   			<source><![CDATA[
+config.addProperty("tables.table(1).fields.field(-1).name", "size");
+config.addProperty("tables.table(1).fields.field.type", "int");
+]]></source>
+			<p>
+				The first line in this fragment specifies that a new branch is
+				to be created for the <code>field</code> property (index -1).
+				In the second line no index is specified for the field, so the
+				last one is used - which happens to be the field that has just
+				been created. So these two statements add a fully defined field
+				to the second table. This is the default pattern for adding new
+				properties or whole hierarchies of properties: first create a new
+				branch in the properties tree and then populate its sub properties.
+				As an additional example let's add a complete new table definition
+				to our example configuration:
+			</p>
+   			<source><![CDATA[
+// Add a new table element and define the name
+config.addProperty("tables.table(-1).name", "versions");
+
+// Add a new field to the new table
+// (an index for the table is not necessary because the latest is used)
+config.addProperty("tables.table.fields.field(-1).name", "id");
+config.addProperty("tables.table.fields.field.type", "int");
+
+// Add another field to the new table
+config.addProperty("tables.table.fields.field(-1).name", "date");
+config.addProperty("tables.table.fields.field.type", "java.sql.Date");
+...
+]]></source>
+			<p>
+				For more information about adding properties to a hierarchical
+				configuration also have a look at the javadocs for
+				<code>HierarchicalConfiguration</code>.
+			</p>
+		</subsection>
+		<subsection name="Escaping dot characters in XML tags">
+			<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:
+			</p>
+   			<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<configuration>
+  <test.value>42</test.value>
+  <test.complex>
+    <test.sub.element>many dots</test.sub.element>
+  </test.complex>
+</configuration>
+]]></source>
+			<p>
+                This XML document can be loaded by <code>XMLConfiguration</code>
+                without trouble, but when we want to access certain properties
+                we face a problem: The configuration claims that it does not
+                store any values for the properties with the keys
+                <code>test.value</code> or <code>test.complex.test.sub.element</code>!
+            </p>
+            <p>
+                Of course, it is the dot character contained in the property
+                names, which causes this problem. A dot is always interpreted
+                as a delimiter between elements. So given the property key
+                <code>test.value</code> the configuration would look for an
+                element named <code>test</code> and then for a sub element
+                with the name <code>value</code>. To change this behavior it is
+                possible to escape a dot character, thus telling the configuration
+                that it is really part of an element name. This is simply done
+                by duplicating the dot. So the following statements will return
+                the desired property values:
+            </p>
+   			<source><![CDATA[
+int testVal = config.getInt("test..value");
+String complex = config.getString("test..complex.test..sub..element");
+]]></source>
+            <p>
+                Note the duplicated dots whereever the dot does not act as
+                delimiter. This way it is possible to access properties containing
+                dots in arbitrary combination. However, as you can see, the
+                escaping can be confusing sometimes. So if you have a choice,
+                you should avoid dots in the tag names of your XML configuration
+                files.
+            </p>
+        </subsection>
+	</section>
+    
+    <section name="Validation of XML configuration files">
+        <p>
+            XML parsers provide support for validation of XML documents to ensure that they
+            conform to a certain DTD. This feature can be useful for
+            configuration files, too. <code>XMLConfiguration</code> allows to enable
+            validation for the files to load.
+        </p>
+        <p>
+            The easiest way to turn on validation is to simply set the
+            <code>validating</code> property to true as shown in the
+            following example:
+        </p>
+        <source><![CDATA[
+XMLConfiguration config = new XMLConfiguration();
+config.setFileName("myconfig.xml");
+config.setValidating(true);
+
+// This will throw a ConfigurationException if the XML document does not
+// conform to its DTD.
+config.load();
+]]></source>
+        <p>
+            Setting the <code>validating</code> flag to true will cause
+            <code>XMLConfiguration</code> to use a validating XML parser. At this parser
+            a custom <code>ErrorHandler</code> will be registered, which throws
+            exceptions on simple and fatal parsing errors.
+        </p>
+        <p>
+            While using the <code>validating</code> flag is a simple means of
+            enabling validation it cannot fullfil more complex requirements,
+            e.g. schema validation. To be able to deal with such requirements
+            XMLConfiguration provides a generic way of setting up the XML
+            parser to use: A preconfigured <code>DocumentBuilder</code> object
+            can be passed to the <code>setDocumentBuilder()</code> method.
+        </p>
+        <p>
+            So an application can create a <code>DocumentBuilder</code> object
+            and initialize it according to its special needs. Then this
+            object must be passed to the <code>XMLConfiguration</code> instance
+            before invocation of the <code>load()</code> method. When loading
+            a configuration file, the passed in <code>DocumentBuilder</code> will
+            be used instead of the default one.
+        </p>
+    </section>
+</body>
+
 </document>
\ No newline at end of file

Propchange: commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_xml.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/index.xml
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/index.xml?rev=952622&r1=952621&r2=952622&view=diff
==============================================================================
--- commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/index.xml (original)
+++ commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/index.xml Tue Jun  8 11:56:30 2010
@@ -1,49 +1,49 @@
-<?xml version="1.0"?>
-<!--
-   Licensed to the Apache Software Foundation (ASF) under one or more
-   contributor license agreements.  See the NOTICE file distributed with
-   this work for additional information regarding copyright ownership.
-   The ASF licenses this file to You under the Apache License, Version 2.0
-   (the "License"); you may not use this file except in compliance with
-   the License.  You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
--->
-<document>
-
-  <properties>
-    <author email="oheger@apache.org">Oliver Heger</author>
-    <title>Howtos index</title>
-  </properties>
-
-  <body>
-    <section name="Howtos">
-      <p>
-        Here you can find documents that describe the usage of some of
-        the main classes provided by the Commons Configuration project. Prior
-        to the 1.3 release these howto documents made up the user
-        documentation. In Commons Configuration 1.3 they have been replaced by
-        a new <a href="../userguide/user_guide.html">user's guide</a>. So if you are using
-        a newer version of Commons Configuration you should jump to this new
-        user's guide. For versions up to 1.2 you are right here.
-      </p>
-      <p>
-        The following doucments are available:
-        <ul>
-          <li><a href="overview.html">Using Configuration</a></li>
-          <li><a href="howto_properties.html">Properties Howto</a></li>
-          <li><a href="howto_configurationfactory.html">ConfigurationFactory Howto</a></li>
-          <li><a href="howto_xml.html">XML Howto</a></li>
-          <li><a href="howto_compositeconfiguration.html">Composite Config Howto</a></li>
-        </ul>
-      </p>
-    </section>
-
-  </body>
-</document>
+<?xml version="1.0"?>
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+<document>
+
+  <properties>
+    <author email="oheger@apache.org">Oliver Heger</author>
+    <title>Howtos index</title>
+  </properties>
+
+  <body>
+    <section name="Howtos">
+      <p>
+        Here you can find documents that describe the usage of some of
+        the main classes provided by the Commons Configuration project. Prior
+        to the 1.3 release these howto documents made up the user
+        documentation. In Commons Configuration 1.3 they have been replaced by
+        a new <a href="../userguide/user_guide.html">user's guide</a>. So if you are using
+        a newer version of Commons Configuration you should jump to this new
+        user's guide. For versions up to 1.2 you are right here.
+      </p>
+      <p>
+        The following doucments are available:
+        <ul>
+          <li><a href="overview.html">Using Configuration</a></li>
+          <li><a href="howto_properties.html">Properties Howto</a></li>
+          <li><a href="howto_configurationfactory.html">ConfigurationFactory Howto</a></li>
+          <li><a href="howto_xml.html">XML Howto</a></li>
+          <li><a href="howto_compositeconfiguration.html">Composite Config Howto</a></li>
+        </ul>
+      </p>
+    </section>
+
+  </body>
+</document>

Propchange: commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/index.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/overview.xml
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/overview.xml?rev=952622&r1=952621&r2=952622&view=diff
==============================================================================
--- commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/overview.xml (original)
+++ commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/overview.xml Tue Jun  8 11:56:30 2010
@@ -1,198 +1,198 @@
-<?xml version="1.0"?>
-<!--
-   Licensed to the Apache Software Foundation (ASF) under one or more
-   contributor license agreements.  See the NOTICE file distributed with
-   this work for additional information regarding copyright ownership.
-   The ASF licenses this file to You under the Apache License, Version 2.0
-   (the "License"); you may not use this file except in compliance with
-   the License.  You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
--->
-
-<document>
-  <properties>
-    <title>Configuration Overview</title>
-    <author email="epugh@upstate.com">Eric Pugh</author>
-    <author email="smanux@lfjr.net">Emmanuel Bourg</author>
-  </properties>
-  <body>
-
-    <section name="Using Configuration">
-      <p>
-        One of the strength of Commons Configuration is its ability to mix configurations
-        from heterogeneous sources, this section will introduce you to the different configurations
-        available and will show you how to combine them.
-      </p>
-
-      <subsection name="Configuration Sources">
-      <p>
-        Currently there are quite a number of different sources of Configuration objects. But,
-        by just using a Configuration object versus a specific type like XMLConfiguration or
-        JNDIConfiguration, you are sheltered from the mechanics of actually retrieving the
-        configuration values. These various sources include:
-        <ul>
-          <li>
-              <strong>PropertiesConfiguration</strong>
-              Loads configuration values from a properties file.
-          </li>
-          <li>
-              <strong>XMLConfiguration</strong>
-              Takes values from an XML document.
-          </li>
-          <li>
-              <strong>PropertyListConfiguration</strong>
-              Loads values from an OpenStep .plist file. XMLPropertyListConfiguration is also
-              available to read the XML variant used by Mac OSX.
-          </li>
-          <li>
-              <strong>JNDIConfiguration</strong>
-              Using a key in the JNDI tree, can retrieve values as configuration properties.
-          </li>
-          <li>
-              <strong>BaseConfiguration</strong>
-              An in-memory method of populating a Configuration object.
-          </li>
-          <li>
-              <strong>SystemConfiguration</strong>
-              A configuration using the system properties
-          </li>
-          <li>
-              <strong>ConfigurationConverter</strong>
-              Takes a java.util.Properties or an o.a.c.collections.ExtendedProperties
-              and converts it to a Configuration object.
-          </li>
-       </ul>
-
-      </p>
-      </subsection>
-
-      <subsection name="Mixing Configuration Sources">
-      <p>
-        Often you want to provide a base set of configuration values, but allow the user to easily
-        override them for their specific environment.  Well one way is to hard code the default
-        values into your code, and have then provide a property file that overrides this.  However,
-        this is a very rigid way of doing things. Instead, with the <code>CompositeConfiguration</code>
-        you can provide many different ways of setting up a configuration. You can either do it
-        manually:
-      </p>
-
-<source>
-CompositeConfiguration config = new CompositeConfiguration();
-config.addConfiguration(new SystemConfiguration());
-config.addConfiguration(new PropertiesConfiguration("application.properties"));
-</source>
-
-      <p>or via the <code>ConfigurationFactory</code> class:</p>
-
-<source>
-ConfigurationFactory factory = new ConfigurationFactory("config.xml");
-Configuration config = factory.getConfiguration();
-</source>
-
-      <p>
-        The <code>config.xml</code> file used in the example above is a configuration descriptor,
-        it specifies the Configuration objects to load. Here is an example of descriptor:
-      </p>
-
-<source><![CDATA[
-<?xml version="1.0" encoding="ISO-8859-1" ?>
-
-<configuration>
-  <system/>
-  <properties fileName="application.properties"/>
-</configuration>
-]]></source>
-
-      <p>
-        What this says is that we are loading up all system properties, as well as the properties
-        file <code>application.properties</code>. The order of precedence is first to last. So in
-        the above example, if a property is not found in the system properties, it'll be searched
-        in the properties file. This allows you to set up default values in a properties file, and
-        override them with the system properties.
-      </p>
-      </subsection>
-    </section>
-
-    <section name="Configuration Details">
-      <p>
-      Configuration is done by taking the configuration descriptor XML file and parsing the
-      individual configurations.  Make sure to include the various <a href="dependencies.html">dependencies</a>
-      required for each type of configuration!
-      </p>
-      <subsection name="Classic Properties File">
-<source><![CDATA[
-  <properties fileName="conf/test.properties"/>
-]]></source>
-
-        <p>
-      This configuration file is very simple.  You just need to specify the path to the property file.
-      </p>
-      </subsection>
-      <subsection name="XML Properties File">
-        <source><![CDATA[
-  <xml fileName="conf/test.xml"/>
-]]></source>
-        <p>
-        The configuration is very similar to the classic properties file.  However, the xml file
-        must be in a specific format. Currently there is no DTD.
-        </p>
-<source><![CDATA[
-<baseElement>
-  <element>value</element>
-  <element2>
-    <subelement>
-      <subsubelement>I'm complex!</subsubelement>
-    </subelement>
-  </element2>
-  <test>
-    <short>8</short>
-  </test>
-</baseElement>
-]]></source>
-        <p>
-          In the above example, the root element is ignored.  So to get the value "8", you would
-          request from your Configuration object the key "<code>test.short</code>". The root
-          element can be called anything.
-        </p>
-      </subsection>
-      <subsection name="JNDI Environment Properties">
-        <source><![CDATA[
-  <jndi prefix="java:comp/env"/>
-]]></source>
-        <p>
-        This configuration is very useful for setting environment specific settings like mail
-        servers! The prefix tells the <code>ConfigurationFactory</code> what the root will be
-        to look up your configuration settings.
-        </p>
-        <source><![CDATA[
-    <env-entry>
-        <env-entry-name>smtp</env-entry-name>
-        <env-entry-value>127.0.0.1</env-entry-value>
-        <env-entry-type>java.lang.String</env-entry-type>
-    </env-entry>
-
-    <env-entry>
-        <env-entry-name>test/short</env-entry-name>
-        <env-entry-value>80</env-entry-value>
-        <env-entry-type>java.lang.Short</env-entry-type>
-    </env-entry>
-]]></source>
-        <p>
-        <strong>Note!</strong>  If you have a property called "<code>test.short</code>" with spaces
-        in it, then it will be translated as the key "<code>test/short</code>".  Therefore, you
-        should NOT use spaces in the name of properties that are loaded from JNDI!  If you do want
-        to use them, then make sure to convert in your <code>web.xml</code> the "." characters to
-        "/" characters, like in the <code>test.short</code> example above.
-        </p>
-      </subsection>
-    </section>
-
-  </body>
-</document>
+<?xml version="1.0"?>
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+
+<document>
+  <properties>
+    <title>Configuration Overview</title>
+    <author email="epugh@upstate.com">Eric Pugh</author>
+    <author email="smanux@lfjr.net">Emmanuel Bourg</author>
+  </properties>
+  <body>
+
+    <section name="Using Configuration">
+      <p>
+        One of the strength of Commons Configuration is its ability to mix configurations
+        from heterogeneous sources, this section will introduce you to the different configurations
+        available and will show you how to combine them.
+      </p>
+
+      <subsection name="Configuration Sources">
+      <p>
+        Currently there are quite a number of different sources of Configuration objects. But,
+        by just using a Configuration object versus a specific type like XMLConfiguration or
+        JNDIConfiguration, you are sheltered from the mechanics of actually retrieving the
+        configuration values. These various sources include:
+        <ul>
+          <li>
+              <strong>PropertiesConfiguration</strong>
+              Loads configuration values from a properties file.
+          </li>
+          <li>
+              <strong>XMLConfiguration</strong>
+              Takes values from an XML document.
+          </li>
+          <li>
+              <strong>PropertyListConfiguration</strong>
+              Loads values from an OpenStep .plist file. XMLPropertyListConfiguration is also
+              available to read the XML variant used by Mac OSX.
+          </li>
+          <li>
+              <strong>JNDIConfiguration</strong>
+              Using a key in the JNDI tree, can retrieve values as configuration properties.
+          </li>
+          <li>
+              <strong>BaseConfiguration</strong>
+              An in-memory method of populating a Configuration object.
+          </li>
+          <li>
+              <strong>SystemConfiguration</strong>
+              A configuration using the system properties
+          </li>
+          <li>
+              <strong>ConfigurationConverter</strong>
+              Takes a java.util.Properties or an o.a.c.collections.ExtendedProperties
+              and converts it to a Configuration object.
+          </li>
+       </ul>
+
+      </p>
+      </subsection>
+
+      <subsection name="Mixing Configuration Sources">
+      <p>
+        Often you want to provide a base set of configuration values, but allow the user to easily
+        override them for their specific environment.  Well one way is to hard code the default
+        values into your code, and have then provide a property file that overrides this.  However,
+        this is a very rigid way of doing things. Instead, with the <code>CompositeConfiguration</code>
+        you can provide many different ways of setting up a configuration. You can either do it
+        manually:
+      </p>
+
+<source>
+CompositeConfiguration config = new CompositeConfiguration();
+config.addConfiguration(new SystemConfiguration());
+config.addConfiguration(new PropertiesConfiguration("application.properties"));
+</source>
+
+      <p>or via the <code>ConfigurationFactory</code> class:</p>
+
+<source>
+ConfigurationFactory factory = new ConfigurationFactory("config.xml");
+Configuration config = factory.getConfiguration();
+</source>
+
+      <p>
+        The <code>config.xml</code> file used in the example above is a configuration descriptor,
+        it specifies the Configuration objects to load. Here is an example of descriptor:
+      </p>
+
+<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<configuration>
+  <system/>
+  <properties fileName="application.properties"/>
+</configuration>
+]]></source>
+
+      <p>
+        What this says is that we are loading up all system properties, as well as the properties
+        file <code>application.properties</code>. The order of precedence is first to last. So in
+        the above example, if a property is not found in the system properties, it'll be searched
+        in the properties file. This allows you to set up default values in a properties file, and
+        override them with the system properties.
+      </p>
+      </subsection>
+    </section>
+
+    <section name="Configuration Details">
+      <p>
+      Configuration is done by taking the configuration descriptor XML file and parsing the
+      individual configurations.  Make sure to include the various <a href="dependencies.html">dependencies</a>
+      required for each type of configuration!
+      </p>
+      <subsection name="Classic Properties File">
+<source><![CDATA[
+  <properties fileName="conf/test.properties"/>
+]]></source>
+
+        <p>
+      This configuration file is very simple.  You just need to specify the path to the property file.
+      </p>
+      </subsection>
+      <subsection name="XML Properties File">
+        <source><![CDATA[
+  <xml fileName="conf/test.xml"/>
+]]></source>
+        <p>
+        The configuration is very similar to the classic properties file.  However, the xml file
+        must be in a specific format. Currently there is no DTD.
+        </p>
+<source><![CDATA[
+<baseElement>
+  <element>value</element>
+  <element2>
+    <subelement>
+      <subsubelement>I'm complex!</subsubelement>
+    </subelement>
+  </element2>
+  <test>
+    <short>8</short>
+  </test>
+</baseElement>
+]]></source>
+        <p>
+          In the above example, the root element is ignored.  So to get the value "8", you would
+          request from your Configuration object the key "<code>test.short</code>". The root
+          element can be called anything.
+        </p>
+      </subsection>
+      <subsection name="JNDI Environment Properties">
+        <source><![CDATA[
+  <jndi prefix="java:comp/env"/>
+]]></source>
+        <p>
+        This configuration is very useful for setting environment specific settings like mail
+        servers! The prefix tells the <code>ConfigurationFactory</code> what the root will be
+        to look up your configuration settings.
+        </p>
+        <source><![CDATA[
+    <env-entry>
+        <env-entry-name>smtp</env-entry-name>
+        <env-entry-value>127.0.0.1</env-entry-value>
+        <env-entry-type>java.lang.String</env-entry-type>
+    </env-entry>
+
+    <env-entry>
+        <env-entry-name>test/short</env-entry-name>
+        <env-entry-value>80</env-entry-value>
+        <env-entry-type>java.lang.Short</env-entry-type>
+    </env-entry>
+]]></source>
+        <p>
+        <strong>Note!</strong>  If you have a property called "<code>test.short</code>" with spaces
+        in it, then it will be translated as the key "<code>test/short</code>".  Therefore, you
+        should NOT use spaces in the name of properties that are loaded from JNDI!  If you do want
+        to use them, then make sure to convert in your <code>web.xml</code> the "." characters to
+        "/" characters, like in the <code>test.short</code> example above.
+        </p>
+      </subsection>
+    </section>
+
+  </body>
+</document>

Propchange: commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/overview.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/configuration/trunk/src/test/org/apache/commons/configuration/Logging.java
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message