You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by oh...@apache.org on 2006/05/30 21:18:15 UTC
svn commit: r410350 - in /jakarta/commons/proper/configuration/trunk/xdocs:
howto_compositeconfiguration_1_2.xml howto_configurationfactory_1_2.xml
howto_properties_1_2.xml howto_xml_1_2.xml howtos_index.xml navigation.xml
overview_1_2.xml user_guide.xml
Author: oheger
Date: Tue May 30 12:18:14 2006
New Revision: 410350
URL: http://svn.apache.org/viewvc?rev=410350&view=rev
Log:
Updated site so that it can be deployed from a snapshot version; re-added howtos for 1.2 and made 1.2 javadocs available
Added:
jakarta/commons/proper/configuration/trunk/xdocs/howto_compositeconfiguration_1_2.xml (with props)
jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationfactory_1_2.xml (with props)
jakarta/commons/proper/configuration/trunk/xdocs/howto_properties_1_2.xml (with props)
jakarta/commons/proper/configuration/trunk/xdocs/howto_xml_1_2.xml (with props)
jakarta/commons/proper/configuration/trunk/xdocs/overview_1_2.xml (with props)
Modified:
jakarta/commons/proper/configuration/trunk/xdocs/howtos_index.xml
jakarta/commons/proper/configuration/trunk/xdocs/navigation.xml
jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml
Added: jakarta/commons/proper/configuration/trunk/xdocs/howto_compositeconfiguration_1_2.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/howto_compositeconfiguration_1_2.xml?rev=410350&view=auto
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/howto_compositeconfiguration_1_2.xml (added)
+++ jakarta/commons/proper/configuration/trunk/xdocs/howto_compositeconfiguration_1_2.xml Tue May 30 12:18:14 2006
@@ -0,0 +1,80 @@
+<?xml version="1.0"?>
+<!--
+ Copyright 2004-2005 The Apache Software Foundation
+
+ Licensed 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
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/howto_compositeconfiguration_1_2.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/howto_compositeconfiguration_1_2.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/howto_compositeconfiguration_1_2.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Added: jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationfactory_1_2.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationfactory_1_2.xml?rev=410350&view=auto
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationfactory_1_2.xml (added)
+++ jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationfactory_1_2.xml Tue May 30 12:18:14 2006
@@ -0,0 +1,525 @@
+<?xml version="1.0"?>
+<!--
+ Copyright 2004-2005 The Apache Software Foundation
+
+ Licensed 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
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationfactory_1_2.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationfactory_1_2.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationfactory_1_2.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Added: jakarta/commons/proper/configuration/trunk/xdocs/howto_properties_1_2.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/howto_properties_1_2.xml?rev=410350&view=auto
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/howto_properties_1_2.xml (added)
+++ jakarta/commons/proper/configuration/trunk/xdocs/howto_properties_1_2.xml Tue May 30 12:18:14 2006
@@ -0,0 +1,209 @@
+<?xml version="1.0"?>
+<!--
+ Copyright 2004-2005 The Apache Software Foundation
+
+ Licensed 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: jakarta/commons/proper/configuration/trunk/xdocs/howto_properties_1_2.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/howto_properties_1_2.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/howto_properties_1_2.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Added: jakarta/commons/proper/configuration/trunk/xdocs/howto_xml_1_2.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/howto_xml_1_2.xml?rev=410350&view=auto
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/howto_xml_1_2.xml (added)
+++ jakarta/commons/proper/configuration/trunk/xdocs/howto_xml_1_2.xml Tue May 30 12:18:14 2006
@@ -0,0 +1,572 @@
+<?xml version="1.0"?>
+<!--
+ Copyright 2004-2005 The Apache Software Foundation
+
+ Licensed 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: jakarta/commons/proper/configuration/trunk/xdocs/howto_xml_1_2.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/howto_xml_1_2.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/howto_xml_1_2.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Modified: jakarta/commons/proper/configuration/trunk/xdocs/howtos_index.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/howtos_index.xml?rev=410350&r1=410349&r2=410350&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/howtos_index.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/howtos_index.xml Tue May 30 12:18:14 2006
@@ -1,6 +1,6 @@
<?xml version="1.0"?>
<!--
- Copyright 2004-2005 The Apache Software Foundation
+ Copyright 2004-2006 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
@@ -17,29 +17,29 @@
<document>
<properties>
- <author email="oliver.heger@t-online.de">Oliver Heger</author>
+ <author email="oheger@apache.org">Oliver Heger</author>
<title>Configuration howtos index</title>
</properties>
<body>
<section name="Howtos">
<p>
- Here you can find a short user guide for the Configuration project.
- Note that these documents deal with the latest <em>development</em> version of the
- Configuration API, i.e. the main trunk in SVN or the nightly builds.
- If you use the latest <em>released</em> version, some of the features
- described here may not be available. In this case please jump to the
- old version of this guide, which can be found
- <a href="howtos_index_1.0.html">here</a>.
+ 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>
+ <li><a href="overview_1_2.html">Using Configuration</a></li>
+ <li><a href="howto_properties_1_2.html">Properties Howto</a></li>
+ <li><a href="howto_configurationfactory_1_2.html">ConfigurationFactory Howto</a></li>
+ <li><a href="howto_xml_1_2.html">XML Howto</a></li>
+ <li><a href="howto_compositeconfiguration_1_2.html">Composite Config Howto</a></li>
</ul>
</p>
</section>
Modified: jakarta/commons/proper/configuration/trunk/xdocs/navigation.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/navigation.xml?rev=410350&r1=410349&r2=410350&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/navigation.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/navigation.xml Tue May 30 12:18:14 2006
@@ -31,6 +31,7 @@
<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="Runtime Dependencies" href="/dependencies.html"/>
<item name="Building" href="/building.html"/>
<item name="Roadmap" href="/tasks-report.html"/>
Added: jakarta/commons/proper/configuration/trunk/xdocs/overview_1_2.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/overview_1_2.xml?rev=410350&view=auto
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/overview_1_2.xml (added)
+++ jakarta/commons/proper/configuration/trunk/xdocs/overview_1_2.xml Tue May 30 12:18:14 2006
@@ -0,0 +1,197 @@
+<?xml version="1.0"?>
+<!--
+ Copyright 2004-2005 The Apache Software Foundation
+
+ Licensed 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: jakarta/commons/proper/configuration/trunk/xdocs/overview_1_2.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/overview_1_2.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/overview_1_2.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Modified: jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml?rev=410350&r1=410349&r2=410350&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml Tue May 30 12:18:14 2006
@@ -32,6 +32,13 @@
offer. But you can also skip sections and jump directly to the topics
you are most interested in.
</p>
+ <p>
+ Note that many features described in this guide are only available
+ since the 1.3 release of Commons Configuration. If you are using
+ a 1.2 version, have a look at the older
+ <a href="howtos_index.html">Howtos</a> documents, which specifically
+ deal with this version.
+ </p>
</section>
<section name="Table of contents">
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org