commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ohe...@apache.org
Subject 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
Date Tue, 30 May 2006 19:18:15 GMT
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>&lt;text&gt;</code> in the body of the
+						<code>&lt;color&gt;</code> element. The corresponding
+						key is <code>color.text</code>.
+					</li>
+					<li>
+						The root element is ignored when constructing keys. In
+						the example you do not write
+						<code>gui-definition.color.text</code>, but only
+						<code>color.text</code>.
+					</li>
+					<li>
+						Attributes of XML elements are accessed in a XPath like
+						notation.
+					</li>
+                    <li>
+                        Interpolation can be used as in <code>PropertiesConfiguration</code>.
+                        Here the <code>&lt;default&gt;</code> element in the
+                        <code>colors</code> section refers to another color.
+                    </li>
+                    <li>
+                        Lists of properties can be defined in a short form using
+                        the delimiter character (which is the comma by default).
+                        In this example the <code>buttons.name</code> property
+                        has the three values <em>OK</em>, <em>Cancel</em>, and
+                        <em>Help</em>, so it is queried using the <code>getList()</code>
+                        method. This works in attributes, too. Using the static
+                        <code>setDelimiter()</code> method of
+                        <code>AbstractConfiguration</code> you can globally
+                        define a different delimiter character or -
+                        by setting the delimiter to 0 - disabling this mechanism
+                        completely. Placing a backslash before a delimiter
+                        character will escape it. This is demonstrated in the
+                        <code>pattern</code> attribute of the <code>numberFormat</code>
+                        element.
+                    </li>
+				</ul>
+			</p>
+            <p>
+                In the next section will show how data in a more complex XML
+                document can be processed.
+            </p>
+        </subsection>
+		<subsection name="Structured XML">
+			<p>
+				Consider the following scenario: An application operates on
+				database tables and wants to load a definition of the database
+				schema from its configuration. A XML document provides this
+				information. It could look as follows:
+			</p>
+   			<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<database>
+  <tables>
+    <table tableType="system">
+      <name>users</name>
+      <fields>
+        <field>
+          <name>uid</name>
+          <type>long</type>
+        </field>
+        <field>
+          <name>uname</name>
+          <type>java.lang.String</type>
+        </field>
+        <field>
+          <name>firstName</name>
+          <type>java.lang.String</type>
+        </field>
+        <field>
+          <name>lastName</name>
+          <type>java.lang.String</type>
+        </field>
+        <field>
+          <name>email</name>
+          <type>java.lang.String</type>
+        </field>
+      </fields>
+    </table>
+    <table tableType="application">
+      <name>documents</name>
+      <fields>
+        <field>
+          <name>docid</name>
+          <type>long</type>
+        </field>
+        <field>
+          <name>name</name>
+          <type>java.lang.String</type>
+        </field>
+        <field>
+          <name>creationDate</name>
+          <type>java.util.Date</type>
+        </field>
+        <field>
+          <name>authorID</name>
+          <type>long</type>
+        </field>
+        <field>
+          <name>version</name>
+          <type>int</type>
+        </field>
+      </fields>
+    </table>
+  </tables>
+</database>
+]]></source>
+			<p>
+				This XML is quite self explanatory; there is an arbitrary number
+				of table elements, each of it has a name and a list of fields.
+				A field in turn consists of a name and a data type. This
+                XML document (let's call it <code>tables.xml</code>) can be
+                loaded in exactly the same way as the simple document in the
+                section before.
+			</p>
+			<p>
+				When we now want to access some of the properties we face a
+                problem: the syntax for	constructing configuration keys we
+                learned so far is not powerful enough to access all of the data
+                stored in the tables document.
+			</p>
+			<p>
+				Because the document contains a list of tables some properties
+				are defined more than once. E.g. the configuration key
+				<code>tables.table.name</code> refers to a <code>name</code>
+				element inside a <code>table</code> element inside a
+				<code>tables</code> element. This constellation happens to
+				occur twice in the tables document.
+			</p>
+			<p>
+				Multiple definitions of a property do not cause problems and are
+				supported by all classes of Configuration. If such a property
+				is queried using <code>getProperty()</code>, the method
+				recognizes that there are multiple values for that property and
+				returns a collection with all these values. So we could write
+			</p>
+   			<source><![CDATA[
+Object prop = config.getProperty("tables.table.name");
+if(prop instanceof Collection)
+{
+	System.out.println("Number of tables: " + ((Collection) prop).size());
+}
+]]></source>
+			<p>
+				An alternative to this code would be the <code>getList()</code>
+				method of <code>Configuration</code>. If a property is known to
+				have multiple values (as is the table name property in this example),
+				<code>getList()</code> allows to retrieve all values at once.
+				<b>Note:</b> it is legal to call <code>getString()</code>
+				or one of the other getter methods on a property with multiple
+				values; it returns the first element of the list.
+			</p>
+		</subsection>
+		<subsection name="Accessing structured properties">
+			<p>
+				Okay, we can obtain a list with the name of all defined
+				tables. In the same way we can retrieve a list with the names
+				of all table fields: just pass the key
+				<code>tables.table.fields.field.name</code> to the
+				<code>getList()</code> method. In our example this list
+				would contain 10 elements, the names of all fields of all tables.
+				This is fine, but how do we know, which field belongs to
+				which table?
+			</p>
+			<p>
+				When working with such hierarchical structures the configuration keys
+				used to query properties can have an extended syntax. All components
+				of a key can be appended by a numerical value in parentheses that
+				determines the index of the affected property. So if we have two
+				<code>table</code> elements we can exactly specify, which one we
+				want to address by appending the corresponding index. This is
+				explained best by some examples:
+			</p>
+			<p>
+				We will now provide some configuration keys and show the results
+				of a <code>getProperty()</code> call with these keys as arguments.
+				<dl>
+					<dt><code>tables.table(0).name</code></dt>
+					<dd>
+						Returns the name of the first table (all indices are 0 based),
+						in this example the string <em>users</em>.
+					</dd>
+					<dt><code>tables.table(0)[@tableType]</code></dt>
+					<dd>
+						Returns the value of the tableType attribute of the first
+						table (<em>system</em>).
+					</dd>
+					<dt><code>tables.table(1).name</code></dt>
+					<dd>
+						Analogous to the first example returns the name of the
+						second table (<em>documents</em>).
+					</dd>
+					<dt><code>tables.table(2).name</code></dt>
+					<dd>
+						Here the name of a third table is queried, but because there
+						are only two tables result is <b>null</b>. The fact that a
+						<b>null</b> value is returned for invalid indices can be used
+						to find out how many values are defined for a certain property:
+						just increment the index in a loop as long as valid objects
+						are returned.
+					</dd>
+					<dt><code>tables.table(1).fields.field.name</code></dt>
+					<dd>
+						Returns a collection with the names of all fields that
+						belong to the second table. With such kind of keys it is
+						now possible to find out, which fields belong to which table.
+					</dd>
+					<dt><code>tables.table(1).fields.field(2).name</code></dt>
+					<dd>
+						The additional index after field selects a certain field.
+						This expression represents the name of the third field in
+						the second table (<em>creationDate</em>).
+					</dd>
+					<dt><code>tables.table.fields.field(0).type</code></dt>
+					<dd>
+						This key may be a bit unusual but nevertheless completely
+						valid. It selects the data types of the first fields in all
+						tables. So here a collection would be returned with the
+						values [<em>long, long</em>].
+					</dd>
+				</dl>
+			</p>
+			<p>
+				These examples should make the usage of indices quite clear.
+				Because each configuration key can contain an arbitrary number
+				of indices it is possible to navigate through complex structures of
+				XML documents; each XML element can be uniquely identified.
+			</p>
+		</subsection>
+		<subsection name="Adding new properties">
+			<p>
+				So far we have learned how to use indices to avoid ambiguities when
+				querying properties. The same problem occurs when adding new
+				properties to a structured configuration. As an example let's
+				assume we want to add a new field to the second table. New properties
+				can be added to a configuration using the <code>addProperty()</code>
+				method. Of course, we have to exactly specify where in the tree like structure new
+				data is to be inserted. A statement like
+			</p>
+   			<source><![CDATA[
+// Warning: This might cause trouble!
+config.addProperty("tables.table.fields.field.name", "size");
+]]></source>
+			<p>
+				would not be sufficient because it does not contain all needed
+				information. How is such a statement processed by the
+				<code>addProperty()</code> method?
+			</p>
+			<p>
+				<code>addProperty()</code> splits the provided key into its
+				single parts and navigates through the properties tree along the
+				corresponding element names. In this example it will start at the
+				root element and then find the <code>tables</code> element. The
+				next key part to be processed is <code>table</code>, but here a
+				problem occurs: the configuration contains two <code>table</code>
+				properties below the <code>tables</code> element. To get rid off
+				this ambiguity an index can be specified at this position in the
+				key that makes clear, which of the two properties should be
+				followed. <code>tables.table(1).fields.field.name</code> e.g.
+				would select the second <code>table</code> property. If an index
+				is missing, <code>addProperty()</code> always follows the last
+				available element. In our example this would be the second
+				<code>table</code>, too.
+			</p>
+			<p>
+				The following parts of the key are processed in exactly the same
+				manner. Under the selected <code>table</code> property there is
+				exactly one <code>fields</code> property, so this step is not
+				problematic at all. In the next step the <code>field</code> part
+				has to be processed. At the actual position in the properties tree
+				there are multiple <code>field</code> (sub) properties. So we here
+				have the same situation as for the <code>table</code> part.
+				Because no explicit index is defined the last <code>field</code>
+				property is selected. The last part of the key passed to
+				<code>addProperty()</code> (<code>name</code> in this example)
+				will always be added as new property at the position that has
+				been reached in the former processing steps. So in our example
+				the last <code>field</code> property of the second table would
+				be given a new <code>name</code> sub property and the resulting
+				structure would look like the following listing:
+			</p>
+   			<source><![CDATA[
+	...
+    <table tableType="application">
+      <name>documents</name>
+      <fields>
+        <field>
+          <name>docid</name>
+          <type>long</type>
+        </field>
+        <field>
+          <name>name</name>
+          <type>java.lang.String</type>
+        </field>
+        <field>
+          <name>creationDate</name>
+          <type>java.util.Date</type>
+        </field>
+        <field>
+          <name>authorID</name>
+          <type>long</type>
+        </field>
+        <field>
+          <name>version</name>
+		  <name>size</name>    <== Newly added property
+          <type>int</type>
+        </field>
+      </fields>
+    </table>
+  </tables>
+</database>
+]]></source>
+			<p>
+				This result is obviously not what was desired, but it demonstrates
+				how <code>addProperty()</code> works: the method follows an
+				existing branch in the properties tree and adds new leaves to it.
+				(If the passed in key does not match a branch in the existing tree,
+				a new branch will be added. E.g. if we pass the key
+				<code>tables.table.data.first.test</code>, the existing tree can be
+				navigated until the <code>data</code> part of the key. From here a
+				new branch is started with the remaining parts <code>data</code>,
+				<code>first</code> and <code>test</code>.)
+			</p>
+			<p>
+				If we want a different behavior, we must explicitely tell
+				<code>addProperty()</code> what to do. In our example with the
+				new field our intension was to create a new branch for the
+				<code>field</code> part in the key, so that a new <code>field</code>
+				property is added to the structure rather than adding sub properties
+				to the last existing <code>field</code> property. This can be
+				achieved by specifying the special index <code>(-1)</code> at the
+				corresponding position in the key as shown below:
+			</p>
+   			<source><![CDATA[
+config.addProperty("tables.table(1).fields.field(-1).name", "size");
+config.addProperty("tables.table(1).fields.field.type", "int");
+]]></source>
+			<p>
+				The first line in this fragment specifies that a new branch is
+				to be created for the <code>field</code> property (index -1).
+				In the second line no index is specified for the field, so the
+				last one is used - which happens to be the field that has just
+				been created. So these two statements add a fully defined field
+				to the second table. This is the default pattern for adding new
+				properties or whole hierarchies of properties: first create a new
+				branch in the properties tree and then populate its sub properties.
+				As an additional example let's add a complete new table definition
+				to our example configuration:
+			</p>
+   			<source><![CDATA[
+// Add a new table element and define the name
+config.addProperty("tables.table(-1).name", "versions");
+
+// Add a new field to the new table
+// (an index for the table is not necessary because the latest is used)
+config.addProperty("tables.table.fields.field(-1).name", "id");
+config.addProperty("tables.table.fields.field.type", "int");
+
+// Add another field to the new table
+config.addProperty("tables.table.fields.field(-1).name", "date");
+config.addProperty("tables.table.fields.field.type", "java.sql.Date");
+...
+]]></source>
+			<p>
+				For more information about adding properties to a hierarchical
+				configuration also have a look at the javadocs for
+				<code>HierarchicalConfiguration</code>.
+			</p>
+		</subsection>
+		<subsection name="Escaping dot characters in XML tags">
+			<p>
+                In XML the dot character used as delimiter by most configuration
+                classes is a legal character that can occur in any tag. So the
+                following XML document is completely valid:
+			</p>
+   			<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<configuration>
+  <test.value>42</test.value>
+  <test.complex>
+    <test.sub.element>many dots</test.sub.element>
+  </test.complex>
+</configuration>
+]]></source>
+			<p>
+                This XML document can be loaded by <code>XMLConfiguration</code>
+                without trouble, but when we want to access certain properties
+                we face a problem: The configuration claims that it does not
+                store any values for the properties with the keys
+                <code>test.value</code> or <code>test.complex.test.sub.element</code>!
+            </p>
+            <p>
+                Of course, it is the dot character contained in the property
+                names, which causes this problem. A dot is always interpreted
+                as a delimiter between elements. So given the property key
+                <code>test.value</code> the configuration would look for an
+                element named <code>test</code> and then for a sub element
+                with the name <code>value</code>. To change this behavior it is
+                possible to escape a dot character, thus telling the configuration
+                that it is really part of an element name. This is simply done
+                by duplicating the dot. So the following statements will return
+                the desired property values:
+            </p>
+   			<source><![CDATA[
+int testVal = config.getInt("test..value");
+String complex = config.getString("test..complex.test..sub..element");
+]]></source>
+            <p>
+                Note the duplicated dots whereever the dot does not act as
+                delimiter. This way it is possible to access properties containing
+                dots in arbitrary combination. However, as you can see, the
+                escaping can be confusing sometimes. So if you have a choice,
+                you should avoid dots in the tag names of your XML configuration
+                files.
+            </p>
+        </subsection>
+	</section>
+    
+    <section name="Validation of XML configuration files">
+        <p>
+            XML parsers provide support for validation of XML documents to ensure that they
+            conform to a certain DTD. This feature can be useful for
+            configuration files, too. <code>XMLConfiguration</code> allows to enable
+            validation for the files to load.
+        </p>
+        <p>
+            The easiest way to turn on validation is to simply set the
+            <code>validating</code> property to true as shown in the
+            following example:
+        </p>
+        <source><![CDATA[
+XMLConfiguration config = new XMLConfiguration();
+config.setFileName("myconfig.xml");
+config.setValidating(true);
+
+// This will throw a ConfigurationException if the XML document does not
+// conform to its DTD.
+config.load();
+]]></source>
+        <p>
+            Setting the <code>validating</code> flag to true will cause
+            <code>XMLConfiguration</code> to use a validating XML parser. At this parser
+            a custom <code>ErrorHandler</code> will be registered, which throws
+            exceptions on simple and fatal parsing errors.
+        </p>
+        <p>
+            While using the <code>validating</code> flag is a simple means of
+            enabling validation it cannot fullfil more complex requirements,
+            e.g. schema validation. To be able to deal with such requirements
+            XMLConfiguration provides a generic way of setting up the XML
+            parser to use: A preconfigured <code>DocumentBuilder</code> object
+            can be passed to the <code>setDocumentBuilder()</code> method.
+        </p>
+        <p>
+            So an application can create a <code>DocumentBuilder</code> object
+            and initialize it according to its special needs. Then this
+            object must be passed to the <code>XMLConfiguration</code> instance
+            before invocation of the <code>load()</code> method. When loading
+            a configuration file, the passed in <code>DocumentBuilder</code> will
+            be used instead of the default one.
+        </p>
+    </section>
+</body>
+
+</document>
\ No newline at end of file

Propchange: 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


Mime
View raw message