You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by se...@apache.org on 2010/06/08 13:56:31 UTC
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...
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><text></code> in the body of the
- <code><color></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><default></code> element in the
- <code>colors</code> section refers to another color.
- </li>
- <li>
- Lists of properties can be defined in a short form using
- the delimiter character (which is the comma by default).
- In this example the <code>buttons.name</code> property
- has the three values <em>OK</em>, <em>Cancel</em>, and
- <em>Help</em>, so it is queried using the <code>getList()</code>
- method. This works in attributes, too. Using the static
- <code>setDelimiter()</code> method of
- <code>AbstractConfiguration</code> you can globally
- define a different delimiter character or -
- by setting the delimiter to 0 - disabling this mechanism
- completely. Placing a backslash before a delimiter
- character will escape it. This is demonstrated in the
- <code>pattern</code> attribute of the <code>numberFormat</code>
- element.
- </li>
- </ul>
- </p>
- <p>
- 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><text></code> in the body of the
+ <code><color></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><default></code> element in the
+ <code>colors</code> section refers to another color.
+ </li>
+ <li>
+ Lists of properties can be defined in a short form using
+ the delimiter character (which is the comma by default).
+ In this example the <code>buttons.name</code> property
+ has the three values <em>OK</em>, <em>Cancel</em>, and
+ <em>Help</em>, so it is queried using the <code>getList()</code>
+ method. This works in attributes, too. Using the static
+ <code>setDelimiter()</code> method of
+ <code>AbstractConfiguration</code> you can globally
+ define a different delimiter character or -
+ by setting the delimiter to 0 - disabling this mechanism
+ completely. Placing a backslash before a delimiter
+ character will escape it. This is demonstrated in the
+ <code>pattern</code> attribute of the <code>numberFormat</code>
+ element.
+ </li>
+ </ul>
+ </p>
+ <p>
+ 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