You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by eb...@apache.org on 2007/04/13 19:31:18 UTC
svn commit: r528563 [1/2] - in /jakarta/commons/proper/configuration/trunk:
./ xdocs/ xdocs/userguide-1.2/ xdocs/userguide/
Author: ebourg
Date: Fri Apr 13 10:31:15 2007
New Revision: 528563
URL: http://svn.apache.org/viewvc?view=rev&rev=528563
Log:
Reorganization of the site documentation:
- moved the userguide and the 1.2 howtos in separate directories
- added a 'Javadoc archive' page and removed the links from the menu
- added a 'Development' section in the menu similar to other commons components
- added a description for some of the releases on the changes report
- removed the unused howtos_index_1.0.xml page
- reverted the maven-xdoc-plugin to 1.8 to fix the page titles (navigation.xml title + page title instead of page title + nav title)
- changed the page title to be more descriptive
Added:
jakarta/commons/proper/configuration/trunk/xdocs/javadoc.xml
jakarta/commons/proper/configuration/trunk/xdocs/userguide/
jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/
jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/howto_compositeconfiguration.xml
jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/howto_configurationfactory.xml
jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/howto_properties.xml
jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/howto_xml.xml
jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/index.xml
jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/overview.xml
jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_basicfeatures.xml (contents, props changed)
- copied, changed from r527434, jakarta/commons/proper/configuration/trunk/xdocs/howto_basicfeatures.xml
jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_beans.xml (contents, props changed)
- copied, changed from r527434, jakarta/commons/proper/configuration/trunk/xdocs/howto_beans.xml
jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_combinedconfiguration.xml (contents, props changed)
- copied, changed from r527434, jakarta/commons/proper/configuration/trunk/xdocs/howto_combinedconfiguration.xml
jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_compositeconfiguration.xml (contents, props changed)
- copied, changed from r527434, jakarta/commons/proper/configuration/trunk/xdocs/howto_compositeconfiguration.xml
jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_configurationbuilder.xml (contents, props changed)
- copied, changed from r527434, jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationbuilder.xml
jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_configurationfactory.xml (contents, props changed)
- copied, changed from r527434, jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationfactory.xml
jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_events.xml (contents, props changed)
- copied, changed from r527434, jakarta/commons/proper/configuration/trunk/xdocs/howto_events.xml
jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_filebased.xml (contents, props changed)
- copied, changed from r527434, jakarta/commons/proper/configuration/trunk/xdocs/howto_filebased.xml
jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_properties.xml (contents, props changed)
- copied, changed from r527434, jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml
jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_utilities.xml (contents, props changed)
- copied, changed from r527434, jakarta/commons/proper/configuration/trunk/xdocs/howto_utilities.xml
jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_xml.xml (contents, props changed)
- copied, changed from r527434, jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml
jakarta/commons/proper/configuration/trunk/xdocs/userguide/user_guide.xml (contents, props changed)
- copied, changed from r527434, jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml
Removed:
jakarta/commons/proper/configuration/trunk/xdocs/howto_basicfeatures.xml
jakarta/commons/proper/configuration/trunk/xdocs/howto_beans.xml
jakarta/commons/proper/configuration/trunk/xdocs/howto_combinedconfiguration.xml
jakarta/commons/proper/configuration/trunk/xdocs/howto_compositeconfiguration.xml
jakarta/commons/proper/configuration/trunk/xdocs/howto_compositeconfiguration_1_2.xml
jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationbuilder.xml
jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationfactory.xml
jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationfactory_1_2.xml
jakarta/commons/proper/configuration/trunk/xdocs/howto_events.xml
jakarta/commons/proper/configuration/trunk/xdocs/howto_filebased.xml
jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml
jakarta/commons/proper/configuration/trunk/xdocs/howto_properties_1_2.xml
jakarta/commons/proper/configuration/trunk/xdocs/howto_utilities.xml
jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml
jakarta/commons/proper/configuration/trunk/xdocs/howto_xml_1_2.xml
jakarta/commons/proper/configuration/trunk/xdocs/howtos_index.xml
jakarta/commons/proper/configuration/trunk/xdocs/howtos_index_1.0.xml
jakarta/commons/proper/configuration/trunk/xdocs/overview_1_2.xml
jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml
Modified:
jakarta/commons/proper/configuration/trunk/project.xml
jakarta/commons/proper/configuration/trunk/xdocs/changes.xml
jakarta/commons/proper/configuration/trunk/xdocs/index.xml
jakarta/commons/proper/configuration/trunk/xdocs/navigation.xml
jakarta/commons/proper/configuration/trunk/xdocs/overview.xml
Modified: jakarta/commons/proper/configuration/trunk/project.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/project.xml?view=diff&rev=528563&r1=528562&r2=528563
==============================================================================
--- jakarta/commons/proper/configuration/trunk/project.xml (original)
+++ jakarta/commons/proper/configuration/trunk/project.xml Fri Apr 13 10:31:15 2007
@@ -448,12 +448,12 @@
<dependency>
<groupId>maven</groupId>
<artifactId>maven-xdoc-plugin</artifactId>
- <version>1.9.2</version>
+ <version>1.8</version>
<url>http://maven.apache.org/maven-1.x/plugins/xdoc/</url>
<type>plugin</type>
<properties>
<comment>
- <strong>Site Only</strong> - v1.9.2 (minimum)
+ <strong>Site Only</strong> - v1.8 (minimum)
required for building the site documentation.
</comment>
</properties>
Modified: jakarta/commons/proper/configuration/trunk/xdocs/changes.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/changes.xml?view=diff&rev=528563&r1=528562&r2=528563
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/changes.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/changes.xml Fri Apr 13 10:31:15 2007
@@ -22,9 +22,9 @@
</properties>
<body>
- <release version="1.5-SNAPSHOT" date="in SVN">
+ <release version="1.5-SNAPSHOT" date="in SVN" description="">
<action dev="ebourg" type="add" issue="CONFIGURATION-261">
- Date objects are now supported in ASCII plist files.
+ Date objects are now supported in ASCII plist files.
</action>
<action dev="ebourg" type="update">
XMLPropertyListConfiguration no longer requires commons-digester and
@@ -36,7 +36,7 @@
</action>
</release>
- <release version="1.4" date="2007-04-08">
+ <release version="1.4" date="2007-04-08" description="Improved interpolation, configuration for INI files, reloading strategy triggered with JMX, bug fixes.">
<action dev="oheger" type="update" issue="CONFIGURATION-256">
MapConfiguration and the web-based configurations now treat strings
that contain an escaped list delimiter correctly: The escape character
@@ -232,6 +232,7 @@
the associated PropertiesConfigurationLayout object correctly.
</action>
</release>
+
<release version="1.3-rc1" date="2006-07-30">
<action dev="oheger" type="update" issue="CONFIGURATION-217">
The dependency to servletapi was updated from version 2.3 to version
@@ -762,7 +763,7 @@
</action>
</release>
- <release version="1.0" date="2004-10-11">
+ <release version="1.0" date="2004-10-11" description="First official release">
<action dev="ebourg" type="fix" issue="CONFIGURATION-66">
The getStringArray() method in CompositeConfiguration now interpolates
the strings.
Modified: jakarta/commons/proper/configuration/trunk/xdocs/index.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/index.xml?view=diff&rev=528563&r1=528562&r2=528563
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/index.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/index.xml Fri Apr 13 10:31:15 2007
@@ -23,14 +23,14 @@
<author email="jason@zenplex.com">Jason van Zyl</author>
<author email="epugh@upstate.com">Eric Pugh</author>
<author email="tobrien@discursive.com">Tim O'Brien</author>
- <title>Configuration</title>
+ <title>Java Configuration API</title>
</properties>
<body>
<section name="Intro">
<p>
Commons Configuration provides a generic configuration interface which enables
- an application to read configuration data from a variety of sources. Commons Configuration
+ a Java application to read configuration data from a variety of sources. Commons Configuration
provides typed access to single, and multi-valued configuration parameters as demonstrated
by the following code:
@@ -47,7 +47,7 @@
<li>Properties files</li>
<li>XML documents</li>
<li>Windows INI files</li>
- <li>Property list files (.plist)</li>
+ <li>Property list files (plist)</li>
<li>JNDI</li>
<li>JDBC Datasource</li>
<li>System properties</li>
@@ -88,8 +88,7 @@
<section name="Bugs">
<p>
Bugs may be reported via the <a href="http://issues.apache.org/jira/browse/CONFIGURATION">ASF JIRA</a>
- system. Detailed information can be found on the
- <a href="issue-tracking.html">issue tracking page</a>.
+ system. Detailed information can be found on the <a href="issue-tracking.html">issue tracking page</a>.
</p>
</section>
Added: jakarta/commons/proper/configuration/trunk/xdocs/javadoc.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/javadoc.xml?view=auto&rev=528563
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/javadoc.xml (added)
+++ jakarta/commons/proper/configuration/trunk/xdocs/javadoc.xml Fri Apr 13 10:31:15 2007
@@ -0,0 +1,39 @@
+<?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>Javadoc archives</title>
+ <author email="ebourg@apache.org">Emmanuel Bourg</author>
+ </properties>
+ <body>
+
+ <section name="Javadoc archive">
+
+ <p>Commons Configuration 1.3 (<a href="/apidocs_1.3/index.html">javadoc</a>)</p>
+
+ <p>Commons Configuration 1.2 (<a href="/apidocs_1.2/index.html">javadoc</a>)</p>
+
+ <p>Commons Configuration 1.1 (<a href="/apidocs_1.1/index.html">javadoc</a>)</p>
+
+ <p>Commons Configuration 1.0 (<a href="/apidocs_1.0/index.html">javadoc</a>)</p>
+
+ </section>
+
+ </body>
+</document>
Modified: jakarta/commons/proper/configuration/trunk/xdocs/navigation.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/navigation.xml?view=diff&rev=528563&r1=528562&r2=528563
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/navigation.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/navigation.xml Fri Apr 13 10:31:15 2007
@@ -16,12 +16,9 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<project name="Configuration">
+<project name="Jakarta Commons Configuration">
- <title>Configuration</title>
- <organizationLogo href="/images/jakarta-logo-blue.gif">
- Jakarta
- </organizationLogo>
+ <title>Jakarta - Commons Configuration</title>
<body>
<links>
@@ -31,16 +28,18 @@
<menu name="Configuration">
<item name="Home" href="/index.html"/>
<item name="Download" href="http://jakarta.apache.org/site/downloads/downloads_commons-configuration.cgi"/>
- <item name="User's Guide" href="/user_guide.html"/>
- <item name="Howtos (Release 1.2)" href="/howtos_index.html"/>
+ <item name="Release History" href="/changes-report.html"/>
+ <item name="User's Guide" href="/userguide/user_guide.html"/>
+ <item name="Howtos (1.2 release)" href="/userguide-1.2/index.html"/>
<item name="Runtime Dependencies" href="/dependencies.html"/>
+ <item name="Javadoc (1.4 release)" href="/apidocs/index.html"/>
+ <item name="Javadoc (old releases)" href="/javadoc.html"/>
+ </menu>
+
+ <menu name="Development">
<item name="Building" href="/building.html"/>
<item name="Roadmap" href="/tasks-report.html"/>
- <item name="Javadoc (Release 1.4)" href="/apidocs/index.html"/>
- <item name="Javadoc (Release 1.3)" href="/apidocs_1.3/index.html"/>
- <item name="Javadoc (Release 1.2)" href="/apidocs_1.2/index.html"/>
- <item name="Javadoc (Release 1.1)" href="/apidocs_1.1/index.html"/>
- <item name="Javadoc (Release 1.0)" href="/apidocs_1.0/index.html"/>
+ <item name="Issue Tracking" href="issue-tracking.html"/>
<item name="SVN" href="http://svn.apache.org/repos/asf/jakarta/commons/proper/configuration/"/>
</menu>
Modified: jakarta/commons/proper/configuration/trunk/xdocs/overview.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/overview.xml?view=diff&rev=528563&r1=528562&r2=528563
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/overview.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/overview.xml Fri Apr 13 10:31:15 2007
@@ -55,9 +55,13 @@
Takes values from an XML document.
</li>
<li>
+ <strong>INIConfiguration</strong>
+ Loads the values from a .ini file as used by Windows.
+ </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.
+ available to read the XML variant used by Mac OS X.
</li>
<li>
<strong>JNDIConfiguration</strong>
@@ -78,7 +82,7 @@
</li>
<li>
<strong>ConfigurationConverter</strong>
- Takes a java.util.Properties or an o.a.c.collections.ExtendedProperties
+ Takes a java.util.Properties or an org.aapache.commons.collections.ExtendedProperties
and converts it to a Configuration object.
</li>
</ul>
Added: jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/howto_compositeconfiguration.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/howto_compositeconfiguration.xml?view=auto&rev=528563
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/howto_compositeconfiguration.xml (added)
+++ jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/howto_compositeconfiguration.xml Fri Apr 13 10:31:15 2007
@@ -0,0 +1,81 @@
+<?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>Composite Configuration Details</title>
+ <author email="epugh@opensourceconnections.com">Eric Pugh</author>
+ </properties>
+
+<body>
+
+ <section name="Composite Configuration Details">
+ <p>
+ We will discuss how you can establish a "default" choice for your
+ Composite Configuration as well as save changes made to your
+ Composite Configuration.
+ </p>
+ <subsection name="Setting Up Defaults">
+ <p>
+ Defaults are very simple. You can just add them as your last configuration object,
+ either through the ConfigurationFactory or manually:
+ </p>
+ <source><![CDATA[
+Configuration defaults = new PropertiesConfiguration(fileToDefaults);
+Configuration otherProperties = new PropertiesConfiguration(fileToOtherProperties);
+CompositeConfiguration cc = new CompositeConfiguration();
+cc.addConfiguration(otherProperties);
+cc.addDefaults(fileToDefaults);
+]]></source>
+ </subsection>
+
+ <subsection name="Saving Changes">
+ <p>
+ If you have a non static Configuration where you want to
+ save changes made to a configuration, and you are using a
+ CompositeConfiguration, then you will need to pass into
+ the constructor of the CompositeConfiguration what Configuration
+ to save the changes via.
+ </p>
+ <source><![CDATA[
+PropertiesConfiguration saveConfiguration = new PropertiesConfiguration(fileToSaveChangesIn);
+Configuration cc = new CompositeConfiguration(saveConfiguration);
+cc.setProperty("newProperty","new value");
+
+saveConfiguration.save();
+]]></source>
+ <p>
+ Alternatively, you can just request the
+ inMemoryConfiguration that stores the changes:
+ <source><![CDATA[
+Configuration changes = myCompositeConfiguration.getInMemoryConfiguration();
+DatabaseConfiguration config = new DatabaseConfiguration(datasource, "configuration", "key", "value");
+for (Iterator i = changes.getKeys().iterator();i.hasNext()){
+ String key = (key)i.next();
+ Object value = changes.get(key);
+ config.setProperty(key,value);
+}
+]]></source>
+ </p>
+
+ </subsection>
+ </section>
+</body>
+
+</document>
\ No newline at end of file
Added: jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/howto_configurationfactory.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/howto_configurationfactory.xml?view=auto&rev=528563
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/howto_configurationfactory.xml (added)
+++ jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/howto_configurationfactory.xml Fri Apr 13 10:31:15 2007
@@ -0,0 +1,526 @@
+<?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 Factory Howto</title>
+ <author email="oliver.heger@t-online.de">Oliver Heger</author>
+ </properties>
+
+<body>
+ <section name="Using a Configuration Factory">
+ <p>
+ This section explains how a
+ <code>ConfigurationFactory</code> object is setup that provides access
+ to a collection of different configuration sources.
+ </p>
+
+ <subsection name="The configuration definition file">
+ <p>
+ When a single configuration file (e.g. a properties file) is the only
+ source of configuration data it is very simple to
+ load it using the specific configuration class that deals with
+ the corresponding format (e.g. <code>PropertiesConfiguration</code>
+ for properties files or <code>XMLConfiguration</code> for XML files). But because
+ we think that later other sources will be added (otherwise
+ this example section would be too silly) we will use a
+ <code>ConfigurationFactory</code> object to load it.
+ </p>
+ <p>
+ <code>ConfigurationFactory</code> allows to combine
+ multiple configuration sources. The properties defined in these
+ sources can then be accessed as if they were defined in a
+ single configuration file. To make use of this we have to
+ create a XML file which tells the factory from which sources
+ the properties are to be collected. The following listing shows
+ the content of this file:
+ </p>
+ <source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<configuration>
+ <properties fileName="usergui.properties"/>
+</configuration>
+]]></source>
+ <p>
+ Definition files for <code>ConfigurationFactory</code> are
+ normal XML files. The root element must be named
+ <code>configuration</code>. It can contain different sub
+ elements that specify the configuration sources to load. The
+ <code>properties</code> element is one of these; it is used to
+ include properties files.
+ </p>
+ <p>
+ For this example we store the definition file for
+ <code>ConfigurationFactory</code> in the same directory as the
+ properties file and call it <code>config.xml</code>. The
+ properties file used in this example is the same as in the
+ section about <a href="howto_properties.html">properties
+ files</a>.
+ </p>
+ </subsection>
+ <subsection name="Setting up a ConfigurationFactory">
+ <p>
+ Now we have to create a <code>ConfigurationFactory</code>
+ object and let it read this definition file. This is quite simple:
+ Just create a new instance and set the name of the definition
+ file with the <code>setConfigurationFileName()</code> method.
+ </p>
+ <source><![CDATA[
+ConfigurationFactory factory = new ConfigurationFactory();
+URL configURL = new File("config.xml").toURL();
+factory.setConfigurationFileName(configURL.toString());
+Configuration config = factory.getConfiguration();
+]]></source>
+ <p>
+ As this code fragment shows the file name passed to the factory
+ can be a full URL. This is also the recommended way of
+ specifying the file because it provides the greatest flexibility
+ and a consistent way of handling relative file names found in
+ the definition file.
+ </p>
+ <p>
+ Here we assumed the configuration definition file to be located
+ in the current directory. It is also possible (and probably a
+ better approach) to load the file from the class path. This
+ could be done as follows:
+ </p>
+ <source><![CDATA[
+ConfigurationFactory factory = new ConfigurationFactory();
+URL configURL = getClass().getResource("/config.xml");
+factory.setConfigurationURL(configURL);
+Configuration config = factory.getConfiguration();
+]]></source>
+ </subsection>
+ <subsection name="Accessing properties">
+ <p>
+ Whatever way we used to load the configuration factory, we
+ should now have a <code>Configuration</code> object that was
+ returned by the factory's <code>getConfiguration()</code>
+ method. This object is actually an instance of the
+ <code>CompositeConfiguration</code> class, a specific implementation
+ of the <code>Configuration</code> interface that is able to
+ deal with multiple contained configuration objects. Of course
+ this class provides all the getter methods defined in the
+ <code>Configuration</code> interface, so for accessing a
+ string property for instance we would use the <code>getString()</code> method:
+ </p>
+ <source><![CDATA[
+String backColor = config.getString("color.background");
+]]></source>
+ </subsection>
+ </section>
+
+ <section name="Multiple configuration sources">
+ <p>
+ Using <code>ConfigurationFactory</code> to collect configuration
+ sources does not make much sense if there is only one source to be
+ loaded. So let's add another one! This time we will embedd a XML file.
+ </p>
+ <subsection name="Overriding properties">
+ <p>
+ Many applications use the popular XML format for storing
+ configuration information. So it is no wonder that Configuration
+ also supports this type of configuration sources. In general
+ each XML document can be used to define configuration settings.
+ We start here with a rather simple one:
+ </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"/>
+ </colors>
+ <rowsPerPage>15</rowsPerPage>
+</gui-definition>
+]]></source>
+ <p>
+ To make this XML document part of our global configuration we
+ have to modify our configuration definition file to also include
+ the new file. For XML documents the element <code>xml</code>
+ can be used so that we have now:
+ </p>
+ <source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<configuration>
+ <properties fileName="usergui.properties"/>
+ <xml fileName="gui.xml"/>
+</configuration>
+]]></source>
+ <p>
+ The code for setting up the <code>ConfigurationFactory</code>
+ object remains the same. From the <code>Configuration</code>
+ object returned by the factory the new properties can be
+ accessed in the usual way.
+ </p>
+ <p>
+ There is one problem with this example configuration setup:
+ The <code>color.background</code> property
+ is defined in both the properties and the XML file, and -
+ to make things worse - with different values. Which value will
+ be returned by a call to <code>getString()</code>?
+ </p>
+ <p>
+ The answer is that the configuration sources are searched in the
+ order they are defined in the configuration definition file.
+ Here the properties file is included first, then comes the XML
+ file. Because the <code>color.background</code> property can
+ be found in the properties file the value specified there will
+ be returned (which happens to be <code>#FFFFFF</code>).
+ </p>
+ <p>
+ It might not be obvious why it makes sense to define the value
+ of one and the same property in multiple configuration sources.
+ But consider the following scenario: An application comes with
+ a set of default properties and allows the user to override some
+ or all of them. This can now easy be realized by saving the
+ user's settings in a file and the default settings in another.
+ Then in the configuration definition file the file with the
+ user settings is included first and after that the file with the
+ default values. The application code that queries these
+ settings need not be aware whether a property was overriden by
+ the user. The <code>ConfigurationFactory</code> takes care
+ that properties defined in the first file (the user file) are
+ found; other properties which the user has not changed will
+ still be returned from the second file (the defaults file).
+ </p>
+ </subsection>
+ <subsection name="Optional configuration sources">
+ <p>
+ The example above with two configuration sources - one for user
+ settings and one with default values - raises an interesting
+ question: What will happen if the user has not defined specific
+ properties yet? Or what if a new user starts our application for
+ the first time and thus no user specific properties exist?
+ </p>
+ <p>
+ The default behavior of <code>ConfigurationFactory</code> is to
+ throw a <code>ConfigurationException</code> exception if one of
+ the sources defined in the configuration definition file cannot
+ be loaded. For our example this behavior is not desired: the
+ properties file with specific user settings is not required. If it
+ cannot be loaded, the example application will still work because
+ a complete set of configuration properties is defined in the
+ second file.
+ </p>
+ <p>
+ <code>ConfigurationFactory</code> supports such optional
+ configuration sources. For this purpose in the definition of a
+ (file based) configuration source the <code>optional</code>
+ attribute can be placed. An example of this is shown below:
+ </p>
+ <source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<configuration>
+ <properties fileName="usersettings.properties" optional="true"/>
+ <properties fileName="default.properties"/>
+</configuration>
+]]></source>
+ <p>
+ In this configuration definition file the first properties file
+ with user specific settings is marked as optional. This means that
+ if it cannot be loaded, <code>ConfigurationFactory</code> will
+ not throw an exception, but only write a warning message to its
+ logger. Note that the <code>optional</code> attribute is absent
+ for the second properties file. Thus it is mandatory, and the
+ <code>getConfiguration()</code> method of
+ <code>ConfigurationFactory</code> would throw an exception if it
+ could not be found.
+ </p>
+ </subsection>
+ </section>
+
+ <section name="Union configuration">
+ <p>
+ In an earlier section about the configuration definition file for
+ <code>ConfigurationFactory</code> it was stated that configuration
+ files included first can override properties in configuraton files
+ included later and an example use case for this behaviour was given.
+ There may be times when there are other requirements.
+ </p>
+ <p>
+ Let's continue the example with the application that somehow process
+ database tables and that reads the definitions of the affected tables from
+ its configuration. This example and the corresponding XML configuration
+ files were introduced in the section about <a href="howto_xml.html">XMLConfiguration</a>.
+ Now consider that this application grows larger and
+ must be maintained by a team of developers. Each developer works on
+ a separated set of tables. In such a scenario it would be problematic
+ if the definitions for all tables would be kept in a single file. It can be
+ expected that this file needs to be changed very often and thus can be
+ a bottleneck for team development when it is nearly steadily checked
+ out. It would be much better if each developer had an associated file
+ with table definitions and all these information could be linked together
+ at the end.
+ </p>
+ <p>
+ <code>ConfigurationFactory</code> provides support for such a use case,
+ too. It is possible to specify in the configuration definition file that
+ from a set of configuration sources a logic union configuration is to be
+ constructed. Then all properties defined in the provided sources are
+ collected and can be accessed as if they had been defined in a single
+ source. To demonstrate this feature let us assume that a developer of
+ the database application has defined a specific XML file with a table
+ definition named <code>tasktables.xml</code>:
+ </p>
+ <source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<config>
+ <table tableType="application">
+ <name>tasks</name>
+ <fields>
+ <field>
+ <name>taskid</name>
+ <type>long</type>
+ </field>
+ <field>
+ <name>name</name>
+ <type>java.lang.String</type>
+ </field>
+ <field>
+ <name>description</name>
+ <type>java.lang.String</type>
+ </field>
+ <field>
+ <name>responsibleID</name>
+ <type>long</type>
+ </field>
+ <field>
+ <name>creatorID</name>
+ <type>long</type>
+ </field>
+ <field>
+ <name>startDate</name>
+ <type>java.util.Date</type>
+ </field>
+ <field>
+ <name>endDate</name>
+ <type>java.util.Date</type>
+ </field>
+ </fields>
+ </table>
+</config>
+]]></source>
+ <p>
+ This file defines the structure of an additional table, which should be
+ added to the so far existing table definitions. To achieve this the
+ configuration definition file has to be changed: A new section is added
+ that contains the include elements of all configuration sources which
+ are to be combined.
+ </p>
+ <source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<!-- Configuration definition file that demonstrates the
+ override and additional sections -->
+
+<configuration>
+ <override>
+ <properties fileName="usergui.properties"/>
+ <xml fileName="gui.xml"/>
+ </override>
+
+ <additional>
+ <xml fileName="tables.xml"/>
+ <xml fileName="tasktables.xml" at="tables"/>
+ </additional>
+</configuration>
+]]></source>
+ <p>
+ Compared to the older versions of this file a couple of changes has been
+ done. One major difference is that the elements for including configuration
+ sources are no longer direct children of the root element, but are now
+ contained in either an <code>override</code> or <code>additional</code>
+ section. The names of these sections already imply their purpose.
+ </p>
+ <p>
+ The <code>override</code> section is not strictly necessary. Elements in
+ this section are treated as if they were children of the root element, i.e.
+ properties in the included configuration sources override properties in
+ sources included later. So the <code>override</code> tags could have
+ been ommitted, but for sake of clearity it is recommended to use them
+ when there is also an <code>additional</code> section.
+ </p>
+ <p>
+ It is the <code>additonal</code> section that introduces a new behaviour.
+ All configuration sources listed here are combined to a union configuration.
+ In our example we have put two <code>xml</code> elements in this area
+ that load the available files with database table definitions. The syntax
+ of elements in the <code>additional</code> section is analogous to the
+ syntax described so far. The only difference is an additionally supported
+ <code>at</code> attribute that specifies the position in the logic union
+ configuration where the included properties are to be added. In this
+ example we set the <code>at</code> attribute of the second element to
+ <em>tables</em>. This is because the file starts with a <code>table</code>
+ element, but to be compatible with the other table definition file it should be
+ accessable under the key <code>tables.table</code>.
+ </p>
+ <p>
+ After these modifications have been performed the configuration obtained
+ from the <code>ConfigurationFactory</code> will allow access to three
+ database tables. A call of <code>config.getString("tables.table(2).name");</code>
+ will result in a value of <em>tasks</em>. In an analogous way it is possible
+ to retrieve the fields of the third table.
+ </p>
+ <p>
+ Note that it is also possible to override properties defined in an
+ <code>additonal</code> section. This can be done by placing a
+ configuration source in the <code>override</code> section that defines
+ properties that are also defined in one of the sources listed in the
+ <code>additional</code> section. The example does not make use of that.
+ Note also that the order of the <code>override</code> and
+ <code>additional</code> sections in a configuration definition file does
+ not matter. Sources in an <code>override</code> section are always treated with
+ higher priority (otherwise they could not override the values of other
+ sources).
+ </p>
+ </section>
+
+ <section name="The configuration definition file">
+ <p>
+ We have seen how to write configuration definition files for
+ including properties and XML files. This section deals with other
+ options that can be specified in such a definition file and that
+ are evaluated by <code>ConfigurationFactory</code>.
+ </p>
+ <p>
+ From time to time the question is raised whether there is a
+ document type definition that exactly defines the structure of a
+ configuration definition file. Frankly, the answer is no. This is
+ because for a future version of Commons Configuration it is planed
+ to make the configuration definition files extensible, i.e. allow
+ developers to register their own tags and corresponding implementations
+ of the Configuration interface.
+ </p>
+ <p>
+ In the current version the set of supported XML elements is fixed.
+ Below is a list of all supported tags and a description of each:
+ </p>
+ <p>
+ <dl>
+ <dt>properties</dt>
+ <dd>
+ With this element properties files can be included. The name of
+ the file to load is specified using the <code>fileName</code>
+ attribute. Which configuration class is created by this tag
+ depends on the extension of the file to load: If the extension
+ is ".xml", a <code>XMLPropertiesConfiguration</code> object is
+ created, which is able to process the XML properties format
+ introduced in Java 5.0. Otherwise a <code>PropertiesConfiguration</code>
+ object is created, the default reader for properties files.
+ </dd>
+ <dt>xml</dt>
+ <dd>
+ The <code>xml</code> element can be used to load XML configuration
+ files. It also uses the <code>fileName</code> attribute to
+ determine the name of the file to load and creates an instance
+ of <code>XMLConfiguration</code>.
+ </dd>
+ <dt>jndi</dt>
+ <dd>
+ As the name implies, with this element JNDI resources can be
+ included in the resulting configuration. Under the hood this is
+ done by an instance of the <code>JNDIConfiguration</code>
+ class. The <code>prefix</code> attribute can be used to
+ select a subset of the JNDI tree.
+ </dd>
+ <dt>plist</dt>
+ <dd>
+ The <code>plist</code> element allows to embedd configuration
+ files in the NeXT / OpenStep or Mac OS X format. Again the
+ name of the file to load is specified through the
+ <code>fileName</code> attribute. If a XML file is specified,
+ a <code>XMLPropertyListConfiguration</code> object is created
+ to process the file. Otherwise this task is delegated to a
+ <code>PropertyListConfiguration</code> instance.
+ </dd>
+ <dt>system</dt>
+ <dd>
+ With this element an instance of <code>SystemConfiguration</code>
+ is added to the resulting configuration allowing access to
+ system properties.
+ </dd>
+ </dl>
+ </p>
+ <p>
+ All of these elements can occur in a configuration definition file
+ in arbitrary number and order. The following listing shows an
+ example file using many of these tags.
+ </p>
+ <source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<configuration>
+ <system/>
+ <jndi prefix="java:comp/env"/>
+ <properties fileName="test.properties"/>
+ <xml fileName="test.xml"/>
+ <properties fileName="test.properties.xml"/>
+</configuration>
+]]></source>
+
+ <subsection name="Setting further options">
+ <p>
+ Many specialized configuration classes support initialization
+ properties that influence the behavior of their instances. For
+ example for file based configurations the encoding of the files
+ to load can be specified using the <code>setEncoding()</code>
+ method, or an <code>XMLConfiguration</code> can be told to
+ perform validation by calling the <code>setValidating()</code>
+ method. How can such properties be set in a configuration definition
+ file?
+ </p>
+ <p>
+ Fortunately this is easy possible. For each XML element in a
+ configuration definition file additional attributes can be
+ specified that correspond to (bean) setter methods defined in the
+ associated configuration class. To derive the name of an attribute
+ from a setter method to be called, just drop the prefix "set" and
+ make the first letter lower case. So for instance the attribute
+ that invokes the <code>setEncoding()</code> method would be
+ <code>encoding</code>. The following example shows how a XML
+ document with a certain encoding and enabled validation can be
+ loaded:
+ </p>
+ <source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<configuration>
+ <xml fileName="test.xml" encoding="UTF-8" validating="true"/>
+</configuration>
+]]></source>
+ <p>
+ Using this mechanism many properties of configuration classes can
+ be set when they are used together with <code>ConfigurationFactory</code>.
+ To find out, which attributes are supported by a specific XML
+ element, refer to the list in the previous section that explains,
+ which configuration classes are used for which tags. In the JavaDoc
+ of the corresponding class you can find the setter methods you can
+ address by attributes.
+ </p>
+ </subsection>
+ </section>
+</body>
+
+</document>
\ No newline at end of file
Added: jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/howto_properties.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/howto_properties.xml?view=auto&rev=528563
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/howto_properties.xml (added)
+++ jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/howto_properties.xml Fri Apr 13 10:31:15 2007
@@ -0,0 +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>
Added: jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/howto_xml.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/howto_xml.xml?view=auto&rev=528563
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/howto_xml.xml (added)
+++ jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/howto_xml.xml Fri Apr 13 10:31:15 2007
@@ -0,0 +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>
+
+</document>
\ No newline at end of file
Added: jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/index.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/index.xml?view=auto&rev=528563
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/index.xml (added)
+++ jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/index.xml Fri Apr 13 10:31:15 2007
@@ -0,0 +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="../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>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org