commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ohe...@apache.org
Subject svn commit: r384588 - in /jakarta/commons/proper/configuration/trunk/xdocs: howto_beans.xml howto_filebased.xml howto_properties.xml howto_xml.xml navigation.xml overview.xml user_guide.xml
Date Thu, 09 Mar 2006 19:46:13 GMT
Author: oheger
Date: Thu Mar  9 11:46:11 2006
New Revision: 384588

URL: http://svn.apache.org/viewcvs?rev=384588&view=rev
Log:
Restructured and enhanced user's guide

Added:
    jakarta/commons/proper/configuration/trunk/xdocs/howto_beans.xml   (with props)
    jakarta/commons/proper/configuration/trunk/xdocs/howto_filebased.xml   (with props)
    jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml   (with props)
Modified:
    jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml
    jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml
    jakarta/commons/proper/configuration/trunk/xdocs/navigation.xml
    jakarta/commons/proper/configuration/trunk/xdocs/overview.xml

Added: jakarta/commons/proper/configuration/trunk/xdocs/howto_beans.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/xdocs/howto_beans.xml?rev=384588&view=auto
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/howto_beans.xml (added)
+++ jakarta/commons/proper/configuration/trunk/xdocs/howto_beans.xml Thu Mar  9 11:46:11 2006
@@ -0,0 +1,357 @@
+<?xml version="1.0"?>
+<!--
+   Copyright 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.
+   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>Declaring Beans Howto</title>
+  <author email="oheger@apache.org">Oliver Heger</author>
+ </properties>
+
+<body>
+	<section name="Declaring and Creating Beans">
+    <p>
+      Often it is good practice to make heavy use of Java interfaces and program
+      an application or components against these interfaces rather than concrete
+      implementation classes. This makes it possible to switch to different implementations
+      without having to modify calling code. However the problem remains how a
+      concrete implementation of an interface is obtained. Simply using the
+      <b>new</b> operator on a specific implementation class would somehow break
+      the interface concept because then the code would have an explicit reference
+      to a concrete implementation.
+    </p>
+    <p>
+      A solution to this problem is to define the concrete implementation class
+      that should be used in a configuration file. Client code would obtain an
+      object (or a bean) from the configuration and cast it to the service
+      interface. This way the caller would have no knowledge about which concrete
+      implementation is used; it would only interact with the service through
+      the interface. By changing the configuration file and entering a different
+      class name for the implementation class the behavior of the application
+      can be altered, e.g. to inject a test stub for the used service.
+    </p>
+    <p>
+      <em>Note: The concept of defining service objects in configuration files
+      and let them be created by a special container has grown popular these
+      days. Especially IoC containers like <a href="http://jakarta.apache.org/hivemind/">HiveMind</a>
+      or <a href="http://www.springframework.org/">Spring</a> offer wide
+      functionality related to this topic. Commons Configuration is not and has
+      no ambitions to become an IoC container. The provided functionality for
+      declaring and creating beans is very basic and limited compared to the
+      specialists. So if you are in need of enhanced features like the creation
+      of complete networks of service objects, life cycle handling and such things,
+      you should in any case use a real IoC container. For simple use cases
+      however the functionality of Commons Configuration might be sufficient,
+      and we have tried to provide hooks for extending the predefined mechanisms.</em>
+    </p>
+
+      <subsection name="Basic Concepts">
+      <p>
+        Beans (we use the term <em>bean</em> here to name any plain old Java
+        object that is defined in a configuration file and can be instantiated
+        by Commons Configuration) are defined in configuration files in a specific
+        format, a so called <em>Bean declaration</em>. Such a declaration contains
+        all information needed to create an instance of this bean class, e.g.
+        the full qualified name of the class and initialization parameters. We will
+        explain how a bean declaration looks like in short.
+      </p>
+      <p>
+        On the Java side three entities are involved in the creation of a bean:
+        <ul>
+          <li>A <em>bean factory</em>: This is an object that implements the
+          <code><a href="apidocs/org/apache/commons/configuration/beanutils/BeanFactory.html">BeanFactory</a></code>
+          interface and knows how to create an instance of a bean class. In most
+          cases calling code does not directly deal with a bean factory.</li>
+          <li>An implementation of the
+          <code><a href="apidocs/org/apache/commons/configuration/beanutils/BeanDeclaration.html">BeanDeclaration</a></code>
+          interface. This object knows how the bean declaration in the configuration
+          file is organized and how the needed information can be extracted. So
+          the way the bean is declared in the configuration file must match the
+          expectations of this object.</li>
+          <li>The utility class
+          <code><a href="apidocs/org/apache/commons/configuration/beanutils/BeanHelper.html">BeanHelper</a></code>
+          brings all these together and performs the bean creation operation.
+          Usually client code will create a <code>BeanDeclaration</code> object
+          from a <code>Configuration</code> implementation and then pass it to
+          one of the <code>createBean()</code> methods of <code>BeanHelper</code>.
+          That's it!</li>
+        </ul>
+        For all of the interfaces mentioned above default implementations are
+        provided, which in many cases can be used out of the box.
+      </p>
+      </subsection>
+      
+      <subsection name="An Example">
+      <p>
+        After this theory let's get into practice using an example. Consider a
+        GUI application that makes use of a <em>Window manager</em> to display
+        its windows and dialogs to the user. There is a <code>WindowManager</code>
+        interface containing methods for opening, displaying, hiding, and
+        disposing windows. Different implementations of this interface exist, e.g.
+        providing different look &amp; feel or special functionality. The concrete
+        set of methods of the interface does not matter for this example.
+      </p>
+      <p>
+        Now in the application's configuration it shall be specified that the
+        concrete implementation <code>DefaultWindowManager</code> should be
+        used as <code>WindowManager</code>. This is a plain Java class implementing
+        the <code>WindowManager</code> interface. Some fragments are shown in
+        the following listing:
+      </p>
+<source><![CDATA[
+package examples.windows;
+
+public class DefaultWindowManager implements WindowManager
+{
+    // are windows allowed to be resized?
+    private boolean resizable;
+    // do windows have a close button?
+    private boolean closable;
+    
+    // Default size of new windows
+    private int defaultWidth;
+    private int defaultHeight;
+    
+    WindowStyleDefinition styleDefinition;
+    
+    // getters and setters ommitted, also the WindowManager methods
+}
+]]></source>
+      <p>
+        As you can see, the <code>DefaultWindowManager</code> class has some
+        simple properties for defining the windows. There is also a property
+        named <code>StyleDefinition</code> whose type is another bean (such
+        a style definition may contain information about themes, colors, fonts
+        of the window and so on). How can we now write a configuration file so
+        that a bean of the <code>DefaultWindowManager</code> class is declared
+        and initialization properties are defined? In an XML configuration file
+        this will look as follows:
+      </p>
+<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<config>
+  <gui>
+    <windowManager config-class="examples.windows.DefaultWindowManager"
+      closable="false" resizable="true" defaultWidth="400"
+      defaultHeight="250">
+      <styleDefinition config-class="examples.windows.WindowStyleDefinition"
+        backColor="#ffffff" foreColor="0080ff" iconName="myicon" />
+    </windowManager>
+  </gui>
+</config>
+]]></source>
+      <p>
+        This XML document contains a valid bean declaration starting with the
+        <code>windowManager</code> element and including its sub elements. Note
+        the following points:
+        <ul>
+          <li>The (full qualified) class of the bean is specified using the
+          <code>config-class</code> attribute. (Attributes starting with the
+          prefix &quot;config-&quot; are reserved; they contain special meta
+          data for the bean creation process.)</li>
+          <li>Other attributes of the <code>windowManager</code> element correspond
+          to properties of the <code>DefaultWindowManager</code> class. These
+          properties will be initialized with the values specified here.</li>
+          <li>For the <code>styleDefinition</code> property, which is itself a
+          bean, a sub element (matching the property's name) exists. The structure
+          of this element is analogous to the structure of the <code>windowManager</code>
+          element; indeed it could even have further sub elements defining
+          bean properties of the <code>WindowStyleDefinition</code> class.</li>
+        </ul>
+        The basic structure of a bean declaration should have become clear by
+        this example.
+      </p>
+      <p>
+        Now let's see how we can access this declaration and create an instance.
+        This is demonstrated in the code fragment below:
+      </p>
+<source><![CDATA[
+XMLConfiguration config = new XMLConfiguration("windowconfig.xml");
+BeanDeclaration decl = new XMLBeanDeclaration(config, "gui.windowManager");
+WindowManager wm = (WindowManager) BeanHelper.createBean(decl);
+]]></source>
+      <p>
+        This fragment loads the configuration file using a <code>XMLConfiguration</code>
+        object. Then a bean declaration object is created, in this case an
+        instance of the <code><a href="apidocs/org/apache/commons/configuration/beanutils/XMLBeanDeclaration.html">XMLBeanDeclaration</a></code>
+        class, which can deal with bean declarations in XML documents. This
+        declaration is passed to the static <code>createBean()</code> method of
+        the <code><a href="apidocs/org/apache/commons/configuration/beanutils/BeanHelper.html">BeanHelper</a></code>
+        class, which returns the new bean instance.
+      </p>
+      <p>
+        <code>BeanHelper</code> defines some overloaded versions of the
+        <code>createBean()</code> method. Some allow to pass in a default bean
+        class; then it is not necessary to define the class in the bean declaration
+        - an instance of this default class will be created if it is lacking in
+        the configuration file. If the bean cannot be created for some reason
+        (e.g. a wrong class name was specified), a <code>ConfigurationRuntimeException</code>
+        will be thrown.
+      </p>
+      </subsection>
+      
+      <subsection name="Extending the Basic Mechanism">
+      <p>
+        As was pointed out in the introduction of this chapter support for creating
+        beans is focused on the basics. But there are some possibilities of hooking
+        in and add custom extensions. This can be done in the following ways:
+        <ul>
+          <li>By defining a custom <code>BeanDeclaration</code> implementation</li>
+          <li>By providing a custom <code>BeanFactory</code> implementation</li>
+        </ul>
+      </p>
+      <p>
+        A specialized bean declaration is needed when you have to deal with
+        configuration files that contain bean declarations in a different format
+        than the ones supported by the available default implementations. Then it
+        is the responsibility of your implementation to parse the configuration
+        data and extract the required information to create the bean. Basically
+        your <code><a href="apidocs/org/apache/commons/configuration/beanutils/BeanDeclaration.html">BeanDeclaration</a></code>
+        implementation must be able to provide the following data:
+        <ul>
+          <li>The name of the class for which an instance is to be created.</li>
+          <li>The name of the bean factory that is used to create the bean. Here
+          <b>null</b> can be returned, then a default factory is used. (See
+          below for more information about working with custom bean factories.)</li>
+          <li>An optional parameter to be passed to the bean factory. If a factory
+          is used that supports additional parameters, the current parameter
+          values are also obtained from the bean declaration.</li>
+          <li>A map with the properties to be set on the newly created bean.
+          This map's keys are names of properties, its values are the corresponding
+          property values. The default bean factory will process this map and
+          call the corresponding setter methods on the newly created bean object.</li>
+          <li>A map with further <code>BeanDeclaration</code> objects for
+          initializing properties of the new bean that are itself beans. These
+          bean declarations are treated exactly as the one that is currently
+          processed. The resulting beans will then be set as properties on the
+          processed bean (the names of these properties are again obtained from
+          the keys of the map).</li>
+        </ul>
+      </p>
+      <p>
+        While creating a custom <code>BeanDeclaration</code> implementation
+        allows you to adapt the format of bean declarations in configuration files,
+        you can manipulate the bean creation mechanism itself by creating a
+        specialized implementation of the
+        <code><a href="apidocs/org/apache/commons/configuration/beanutils/BeanFactory.html">BeanFactory</a></code>
+        interface. For this purpose the following steps are necessary:
+        <ol>
+          <li>Create a class implementing the <code>BeanFactory</code> interface.
+          This interface is quite simple. It defines one method for creating an
+          instance of a class whose <code>Class</code> object is provided, and
+          another method, which is called for querying a default class.</li>
+          <li>Register this new factory class at the <code>BeanHelper</code>
+          class.</li>
+          <li>In the bean declaration in your configuration file refer to the
+          factory that should be used for creating the bean.</li>
+        </ol>
+      </p>
+      <p>
+        We will provide an example that covers all these steps. This example
+        deals with a <em>singleton</em> factory, i.e. an implementation of
+        <code>BeanFactory</code> that returns always the same instance of a
+        provided bean class.
+      </p>
+      <p>
+        We start with the creation of the factory class. The basic idea is that
+        the functionality for creating and initializing beans is already provided
+        by the <code><a href="apidocs/org/apache/commons/configuration/beanutils/DefaultBeanFactory.html">DefaultBeanFactory</a></code>
+        class, so we extend this class. Our implementation only has to deal with
+        the singleton stuff: We keep a map that stores already created bean
+        instances and can be accessed by the name of their classes. In the
+        factory's <code>createBean()</code> method we check if for the passed in
+        class already an instance exists. If this is the case, it is directly
+        returned. Otherwise we call the inherited <code>createBean()</code> method
+        and store its result in the map. (Note that this implementation is a bit
+        simplicistic; a real world implementation would also have to take the
+        initialization parameters into account. But for the purpose of an example
+        it should be good enough). Here is the code:
+      </p>
+<source><![CDATA[
+public class SingletonBeanFactory extends DefaultBeanFactory
+{
+    /** A map for the so far created instances.*/
+    private Map beans;
+    
+    public SingletonBeanFactory()
+    {
+        super();
+        beans = new HashMap();
+    }
+    
+    // Creates the bean. Checks if already an instance exists.
+    public synchronized Object createBean(Class beanClass, BeanDeclaration decl,
+        Object param) throws Exception
+    {
+        Object bean = beans.get(beanClass.getName());
+        if (bean != null)
+        {
+            // Yes, there is already an instance
+            return bean;
+        }
+        else
+        {
+            // No, create it now (done by the super class)
+            bean = super.createBean(beanClass, decl, param);
+            // Store it in map
+            beans.put(beanClass.getName(), bean);
+            return bean;
+        }
+    }
+}
+]]></source>
+      <p>
+        Note the <b>synchronized</b> key word, which is necessary because the
+        method can be accessed by multiple threads concurrently. Now we have to
+        register an instance of this class at the <code>BeanHelper</code> class.
+        This can be done in the initialization phase of your application and
+        looks as follows:
+      </p>
+<source><![CDATA[
+BeanHelper.registerBeanFactory("SINGLETON", new SingletonBeanFactory());
+]]></source>
+      <p>
+        To make use of the new factory a bean declaration must contain an
+        attribute that refers to the name under which the factory was registered.
+        This is demonstrated by the fragment below:
+      </p>
+<source><![CDATA[
+<config>
+...
+    <services>
+      <fileService config-class="my.package.services.FileServiceImpl"
+        config-factory="SINGLETON"
+        property1="value1" property2="value2">
+        <!-- Here can be nested bean declarations -->
+      </fileService>
+      ...
+</config>
+]]></source>
+      <p>
+        In this fragment the <code>fileService</code> element contains a bean
+        declaration for some service object. Apart from the <code>config-class</code>
+        attribute the important part is the <code>config-factory</code> attribute.
+        This attribute tells the <code>BeanHelper</code> class that it should
+        use a special factory when it processes this bean declaration. As was
+        demonstrated by this example, it should not be too difficult to extend
+        the custom mechanism for creating beans.
+      </p>
+      </subsection>
+    </section>
+</body>
+
+</document>

Propchange: jakarta/commons/proper/configuration/trunk/xdocs/howto_beans.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: jakarta/commons/proper/configuration/trunk/xdocs/howto_beans.xml
------------------------------------------------------------------------------
    svn:keywords = Date Author Id Revision HeadURL

Propchange: jakarta/commons/proper/configuration/trunk/xdocs/howto_beans.xml
------------------------------------------------------------------------------
    svn:mime-type = text/xml

Added: jakarta/commons/proper/configuration/trunk/xdocs/howto_filebased.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/xdocs/howto_filebased.xml?rev=384588&view=auto
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/howto_filebased.xml (added)
+++ jakarta/commons/proper/configuration/trunk/xdocs/howto_filebased.xml Thu Mar  9 11:46:11 2006
@@ -0,0 +1,204 @@
+<?xml version="1.0"?>
+<!--
+   Copyright 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.
+   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>File-based Configurations</title>
+  <author email="oheger@apache.org">Oliver Heger</author>
+ </properties>
+
+<body>
+	<section name="File-based Configurations">
+		<p>
+ 	 	  Often configuration properties are stored in files on the user's hard
+          disk, e.g. in .properties files or as XML documents. Configuration
+          classes that deal with such properties need to provide typical operations
+          like loading or saving files. The files to be processed can be specified
+          in several different flavors like <code>java.io.File</code> objects,
+          relative or absolute path names, or URLs.
+    	</p>
+        <p>
+          To provide a consistent way of dealing with configuration files in
+          Commons Configuration the <code><a href="apidocs/org/apache/commons/configuration/FileConfiguration.html">FileConfiguration</a></code>
+          interface exists. <code>FileConfiguration</code> defines a standard
+          API for accessing files and is implemented by many configuration
+          implementations, including <code>PropertiesConfiguration</code> and
+          <code>XMLConfiguration</code>.
+        </p>
+        <p>
+          In the following sections we take a closer look at the methods of the
+          <code>FileConfiguration</code> interface and how they are used.
+        </p>
+        
+        <subsection name="Specifying the file">
+          <p>
+            The <code>FileConfiguration</code> interface contains several
+            methods for specifying the file to be loaded. The following variants
+            are supported:
+            <ul>
+              <li>With the <code>setFile()</code> method the data file can be
+              specified as a <code>java.io.File</code> object.</li>
+              <li>The <code>setURL()</code> takes a <code>java.net.URL</code>
+              as argument; the file will be loaded from this URL.</li>
+              <li>The methods <code>setFileName()</code> and <code>setBasePath()</code>
+              allows to specify the path of the data file. The base path is
+              important if relative paths are to be resolved based on this file.</li>
+            </ul>
+          </p>
+          <p>
+            While a <code>File</code> or a URL uniquely identify a file, the
+            situation is a bit ambigous when only a base path and a file name are
+            set. These can be arbitrary strings (even full URLs) whose exact
+            meaning must be detected when the file is loaded. For this purpose
+            file-based configurations perform the following checks (in this
+            order):
+            <ul>
+              <li>If the combination from base path and file name is a full URL
+              that points to an existing file, this URL will be used to load
+              the file.</li>
+              <li>If the combination from base path and file name is an absolute
+              file name and this file exists, it will be loaded.</li>
+              <li>If the combination from base path and file name is a relative
+              file path that points to an existing file, this file will be loaded.</li>
+              <li>If a file with the specified name exists in the user's home
+              directory, this file will be loaded.</li>
+              <li>Otherwise the file name is interpreted as a resource name, and
+              it is checked whether the data file can be loaded from the classpath.</li>
+            </ul>
+            If all these checks fail, a <code>ConfigurationException</code> will
+            be thrown.
+          </p>
+        </subsection>
+        
+        <subsection name="Loading">
+          <p>
+            After the file name has been defined using one of the methods mentioned
+            above, the <code>load()</code> method can be called. This method tries
+            to locate the file and open it. If this fails, a <code>ConfigurationException</code>
+            is thrown.
+          </p>
+          <p>
+            The <code>FileConfiguration</code> interface defines multiple overloaded
+            <code>load()</code> methods. The one that takes no argument will
+            always operate on the file name that has been set earlier. All
+            other methods allow to specify the source to be loaded. This can be
+            done as <code>java.io.File</code>, <code>java.net.URL</code>, string
+            (containing either an absolute or relative path), input stream, or
+            reader. When using these variants of the <code>load()</code> method
+            be aware of two things:
+            <ol>
+              <li>They do not change the configuration's file name. To do this
+              you have to explicitely call one of the setter methods.</li>
+              <li>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.</li>
+            </ol>
+          </p>
+          <p>
+            File-based configurations typically define a set of constructors that
+            correspond to the various setter methods for defining the data file.
+            These constructors will set the file and then invoke the <code>load()</code>
+            method. So creating a file-based configuration object and loading its
+            content can be done in a single step.
+          </p>
+        </subsection>
+        
+        <subsection name="Saving">
+          <p>
+            Saving is implemented analogously to loading: There is a no argument
+            <code>save()</code> method that will use the internal file name. Then
+            for each <code>load()</code> method a corresponding <code>save()</code>
+            method exists that will write the data contained in the configuration
+            to different targets.
+          </p>
+          <p>
+            An example for loading, manipulating, and saving a configuration
+            (based on a <a href="howto_properties.html"><code>PropertiesConfiguration</code></a>)
+            could look as follows:
+          </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>
+        </subsection>
+        
+        <subsection name="Automatic Saving">
+          <p>
+            If you want to ensure that every modification of a configuration
+            object is immideately written to disk, you can enable the automatic
+            saving mode. This is done through the <code>setAutoSave()</code>
+            method as shown in the following example:
+          </p>
+<source>
+PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties");
+config.setAutoSave(true);
+config.setProperty("colors.background", "#000000); // the configuration is saved after this call
+</source>
+          <p>
+            Be careful with this mode when you have many updates on your
+            configuration. This will lead to many I/O operations, too.
+          </p>
+        </subsection>
+        
+        <subsection name="Automatic Reloading">
+        <p>
+          A common issue with file-based configurations is to handle the
+          reloading of the data file when it changes. This is especially important
+          if you have long running applications and do not want to restart them
+          when a configuration file was updated. Commons Configuration has the
+          concept of so called <em>reloading strategies</em> that can be
+          associated with a file-based configuration. Such a strategy monitors
+          a configuration file and is able to detect changes. A default reloading
+          strategy is <code><a href="apidocs/org/apache/commons/configuration/reloading/FileChangedReloadingStrategy.html">FileChangedReloadingStrategy</a></code>.
+          It can be set on a file-based configuration as follows:
+        </p>
+<source>
+PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties");
+config.setReloadingStrategy(new FileChangedReloadingStrategy());
+</source>
+        <p>
+          <code>FileChangedReloadingStrategy</code> works as follows: On every
+          property access the configuration checks its associated reloading
+          strategy. <code>FileChangedReloadingStrategy</code> will then obtain
+          the last modification date of the configuration file and check whether
+          it has changed since the last access. If this is the case, a reload is
+          triggered. To avoid often disk access when multiple properties are
+          queried from the configuration, a <em>refresh delay</em> can be set on
+          the reloading strategy. This is a time in milli seconds with the meaning
+          that the reloading strategy will only once check the file's last
+          modification time in the period specified here.
+        </p>
+        </subsection>
+    </section>
+
+</body>
+
+</document>

Propchange: jakarta/commons/proper/configuration/trunk/xdocs/howto_filebased.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: jakarta/commons/proper/configuration/trunk/xdocs/howto_filebased.xml
------------------------------------------------------------------------------
    svn:keywords = Date Author Id Revision HeadURL

Propchange: jakarta/commons/proper/configuration/trunk/xdocs/howto_filebased.xml
------------------------------------------------------------------------------
    svn:mime-type = text/xml

Modified: jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml?rev=384588&r1=384587&r2=384588&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml Thu Mar  9 11:46:11 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.
@@ -19,7 +19,7 @@
   <properties>
     <title>Properties files</title>
     <author email="smanux@lfjr.net">Emmanuel Bourg</author>
-    <author email="oliver.heger@t-online.de">Oliver Heger</author>
+    <author email="oheger@apache.org">Oliver Heger</author>
   </properties>
 
   <body>
@@ -27,18 +27,31 @@
     <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.
+        supports this format and enhances significantly the basic <code>java.util.Properties</code> class.
+        This section introduces the features of the 
+        <code><a href="apidocs/org/apache/commons/configuration/PropertiesConfiguration.html">PropertiesConfiguration</a></code> class.
+        Note that <code>PropertiesConfiguration</code> is a very typical example
+        for an implementation of the <code>Configuration</code> interface and
+        many of the features described in this section (e.g. list handling or
+        interpolation) are supported by other configuration classes as well.
+        This is because most configuration implementations that ship with
+        Commons Configuration are derived from the common base class
+        <code><a href="apidocs/org/apache/commons/configuration/AbstractConfiguration.html">AbstractConfiguration</a></code>,
+        which implementes this features.
       </p>
 
-      <subsection name="Loading">
+      <subsection name="Using PropertiesConfiguration">
         <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:
+          Let's start with a simple properties file named
+          <code>usergui.properties</code> with the following content:
         </p>
         <source><![CDATA[
 # Properties definining the GUI
 colors.background = #FFFFFF
+colors.foreground = #000080
+
+window.width = 500
+window.height = 300
 ]]></source>
 
         <p>
@@ -59,23 +72,20 @@
         <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>
+          overloaded variants that allow you to load properties from various
+          sources. More information about loading properties files (and file-based
+          configurations in general) can be found in the section about
+          <a href="howto_filebased.html">File-based Configurations</a>.
         </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.
+          After the properties file was loaded you can access its content through
+          the methods of the <code>Configuration</code> interface, e.g.
         </p>
+<source>
+String backColor = config.getString("colors.background");
+Dimension size = new Dimension(config.getInt("window.width"),
+  config.getInt("window.height"));
+</source>
       </subsection>
 
       <subsection name="Includes">
@@ -99,55 +109,6 @@
 
       </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,
@@ -158,10 +119,12 @@
 colors.pie = #FF0000, #00FF00, #0000FF
 </source>
         <p>
-          You don't have to split the value manually, you can retrieve an array directly with:
+          You don't have to split the value manually, you can retrieve an array
+          or a <code>java.util.List</code> directly with:
         </p>
 <source>
 String[] colors = config.getStringArray("colors.pie");
+List colorList = config.getList("colors.pie");
 </source>
         <p>
           Alternatively, you can specify a list of values in your properties file by using
@@ -173,6 +136,61 @@
 colors.pie = #00FF00;
 colors.pie = #0000FF;
 </source>
+        <p>
+          The <code>addProperty()</code> and <code>setProperty()</code> methods
+          also implement special list handling. The property value that is passed
+          to these methods can be a list or an array resulting in a property
+          with multiple values. If the property value is a string, it is checked
+          whether it contains the <em>list delimiter character</em>. If this is
+          the case, the string is splitted, and its single parts are added one
+          by one. The list delimiter character is the comma by default. It is
+          also applied to the properties when the configuration file is loaded
+          (that's the reason why the example above with the comma separated list
+          of chart colors works). By using the <code>setListDelimiter()</code>
+          method you can set it to a different character. Here are some examples:
+        </p>
+<source>
+// Change the list delimiter character to a slash
+config.setListDelimiter('/');
+// Now add some properties
+config.addProperty("greeting", "Hello, how are you?");
+config.addProperty("colors.pie",
+  new String[] { "#FF0000", "#00FF00", "#0000FF" });
+config.addProperty("colors.graph", "#808080/#00FFCC/#6422FF");
+
+// Access data
+String salut = config.getString("greeting");
+List colPie = config.getList("colors.pie");
+String[] colGraph = config.getStringArray("colors.graph");
+
+String firstPieColor = config.getString("colors.pie");
+</source>
+        <p>
+          In this example the list delimiter character is changed from a comma
+          to a slash. Because of this the <code>greeting</code> property won't
+          be splitted, but remains a single string. The string passed as value
+          for the <code>colors.graph</code> property in opposite contains the
+          new delimiter character and thus will result in a property with three
+          values.
+        </p>
+        <p>
+          Of interest is also the last line of the example fragment. Here the
+          <code>getString()</code> method is called for a property that has
+          multiple values. This call will return the first value of the list.
+        </p>
+        <p>
+          If you want to change the list delimiter character for all configuration
+          objects, you can use the static <code>setDefaultListDelimiter()</code>
+          method of <code>AbstractConfiguration</code>. It is also possible to
+          disable splitting of string properties at all for a Configuration
+          instance by calling its <code>setDelimiterParsingDisabled()</code>
+          method with a value of <b>true</b>.
+        </p>
+        <p>
+          <em>Note:</em> The list handling and string splitting facilities
+          described in this section are not specific to <code>PropertiesConfiguration</code>,
+          but are also supported by other configuration classes.
+        </p>
       </subsection>
 
       <subsection name="Variable Interpolation">
@@ -188,6 +206,36 @@
 
 application.title = ${application.name} ${application.version}
 </source>
+        <p>
+          If you now retrieve the value for the <code>application.title</code>
+          property, the result will be <code>Killer App 1.6.2</code>. As for
+          list handling, variable interpolation is a feature supported by other
+          configuration classes as well.
+        </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>
+          More information about saving properties files (and file-based
+          configurations in general) can be found in the section about
+          <a href="howto_filebased.html">File-based Configurations</a>.
+        </p>
       </subsection>
 
       <subsection name="Special Characters">
@@ -200,8 +248,6 @@
 key = This \n string \t contains \, escaped \\ characters \u0020
 ]]></source>
       </subsection>
-
-
 
     </section>
 

Modified: jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml?rev=384588&r1=384587&r2=384588&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml Thu Mar  9 11:46:11 2006
@@ -19,7 +19,7 @@
 
  <properties>
   <title>XML Howto</title>
-  <author email="oliver.heger@t-online.de">Oliver Heger</author>
+  <author email="oheger@apache.org">Oliver Heger</author>
  </properties>
 
 <body>		
@@ -67,7 +67,8 @@
 				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
+                by <code>XMLConfiguration</code>. Like other 
+                <a href="howto_filebased.html">file based</a>
                 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
@@ -131,7 +132,7 @@
                         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>setDefaultDelimiter()</code> method of
                         <code>AbstractConfiguration</code> you can globally
                         define a different delimiter character or -
                         by setting the delimiter to 0 - disabling this mechanism

Modified: jakarta/commons/proper/configuration/trunk/xdocs/navigation.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/xdocs/navigation.xml?rev=384588&r1=384587&r2=384588&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/navigation.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/navigation.xml Thu Mar  9 11:46:11 2006
@@ -30,11 +30,7 @@
 	<menu name="Configuration">
       <item name="Home"                         href="/index.html"/>  
       <item name="Download"                     href="http://jakarta.apache.org/site/downloads/downloads_commons-configuration.cgi"/>  
-      <item name="Using Configuration"          href="/overview.html"/>
-      <item name="Properties Howto"             href="/howto_properties.html"/>
-      <item name="XML Howto"                    href="/howto_xml.html"/>
-      <item name="ConfigurationFactory Howto"   href="/howto_configurationfactory.html"/>      
-      <item name="Composite Config Howto"       href="/howto_compositeconfiguration.html"/>
+      <item name="User's Guide"                 href="/user_guide.html"/>
       <item name="Runtime Dependencies"         href="/dependencies.html"/>
       <item name="Building"                     href="/building.html"/>
       <item name="Roadmap"                      href="/tasks-report.html"/>

Modified: jakarta/commons/proper/configuration/trunk/xdocs/overview.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/xdocs/overview.xml?rev=384588&r1=384587&r2=384588&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/overview.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/overview.xml Thu Mar  9 11:46:11 2006
@@ -25,8 +25,16 @@
 
     <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
+        Commons Configuration allows you to access configuration properties from
+        a variety of different sources. No matter if they are stored in a properties file,
+        a XML document, or a JNDI tree, they can all be accessed in the same way
+        through the generic <code><a href="apidocs/org/apache/commons/configuration/Configuration.html">Configuration</a></code>
+        interface.
+      </p>
+      <p>
+        Another strength of Commons Configuration is its ability to mix configurations
+        from heterogeneous sources and treat them like a single logic configuration.
+        This section will introduce you to the different configurations
         available and will show you how to combine them.
       </p>
 
@@ -59,6 +67,11 @@
               An in-memory method of populating a Configuration object.
           </li>
           <li>
+              <strong>HierarchicalConfiguration</strong>
+              An in-memory Configuration object that is able to deal with complex
+              structured data.
+          </li>
+          <li>
               <strong>SystemConfiguration</strong>
               A configuration using the system properties
           </li>
@@ -117,79 +130,65 @@
         override them with the system properties.
       </p>
       </subsection>
-    </section>
-
-    <section name="Configuration Details">
+      
+      <subsection name="The Configuration interface">
       <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!
+        All the classes in this package that represent different kinds of configuration
+        sources share a single interface:
+        <code><a href="apidocs/org/apache/commons/configuration/Configuration.html">Configuration</a></code>.
+        This interface allows you to access and manipulate configuration properties
+        in a generic way.
       </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>
+        A major part of the methods defined in the <code>Configuration</code>
+        interface deals with retrieving properties of different data types. All
+        these methods take a key as an argument that points to the desired
+        property. This is a string value whose exact meaning depends on the
+        concrete <code>Configuration</code> implementation used. They try to
+        find the property specified by the passed in key and convert it to their
+        target type; this converted value will be returned. There are also
+        overloaded variants of all methods that allow to specify a default value,
+        which will be returned if the property cannot be found. The following
+        data types are supported:
+        <ul>
+          <li>BigDecimal</li>
+          <li>BigInteger</li>
+          <li>boolean</li>
+          <li>byte</li>
+          <li>double</li>
+          <li>float</li>
+          <li>int</li>
+          <li>long</li>
+          <li>short</li>
+          <li>String</li>
+        </ul>
+        The names of these methods start with <code>get</code> followed by their
+        data type. The <code>getString()</code> method for instance will return
+        String values, <code>getInt()</code> will operate on integers.
+      </p>
+      <p>
+        Properties can have multiple values, so it is also possible to query a
+        list containing all of the available values. This is done using the
+        <code>getList()</code> method.
+      </p>
+      <p>
+        For manipulating properties or their values the following methods can
+        be used:
+        <dl>
+          <dt><code>addProperty()</code></dt>
+          <dd>Adds a new property to the configuration. If this property already
+          exists, another value is added to it (so it becomes a multi-valued
+          property).</dd>
+          <dt><code>clearProperty()</code></dt>
+          <dd>Removes the specified property from the configuration.</dd>
+          <dt><code>setProperty()</code></dt>
+          <dd>Overwrites the value of the specified property. This is the same
+          as removing the property and then calling <code>addProperty()</code>
+          with the new property value.</dd>
+          <dt><code>clear()</code></dt>
+          <dd>Wipes out the whole configuration</dd>
+        </dl>
       </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>
 

Added: jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml?rev=384588&view=auto
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml (added)
+++ jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml Thu Mar  9 11:46:11 2006
@@ -0,0 +1,107 @@
+<?xml version="1.0"?>
+<!--
+   Copyright 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.
+   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>Commons Configuration User's Guide</title>
+  <author email="oheger@apache.org">Oliver Heger</author>
+ </properties>
+
+<body>
+	<section name="About this document">
+		<p>
+ 	 		This document describes the features of the Commons Configuration
+            component starting with the very basics and up to the more advanced
+            topics. If you read it in a linear way, you should get a sound
+            understanding of the provided classes and the possibilities they
+            offer. But you can also skip sections and jump directly to the topics
+            you are most interested in.
+    	</p>
+    </section>
+
+	<section name="Table of contents">
+    <ul>
+      <li><a href="overview.html#Using Configuration">Using Configuration</a></li>
+      <ul>
+        <li><a href="overview.html#Configuration Sources">Configuration Sources</a></li>
+        <li><a href="overview.html#Mixing Configuration Sources">Mixing Configuration Sources</a></li>
+        <li><a href="overview.html#The Configuration interface">The Configuration interface</a></li>
+      </ul>
+      <li><a href="howto_properties.html#Properties files">Properties files</a></li>
+      <ul>
+        <li><a href="howto_properties.html#Using PropertiesConfiguration">Using PropertiesConfiguration</a></li>
+        <li><a href="howto_properties.html#Includes">Includes</a></li>
+        <li><a href="howto_properties.html#Lists and arrays">Lists and arrays</a></li>
+        <li><a href="howto_properties.html#Variable Interpolation">Variable Interpolation</a></li>
+        <li><a href="howto_properties.html#Saving">Saving</a></li>
+        <li><a href="howto_properties.html#Special Characters">Special Characters</a></li>
+      </ul>
+      <li><a href="howto_filebased.html#File-based Configurations">File-based Configurations</a></li>
+      <ul>
+        <li><a href="howto_filebased.html#Specifying the file">Specifying the file</a></li>
+        <li><a href="howto_filebased.html#Loading">Loading</a></li>
+        <li><a href="howto_filebased.html#Saving">Saving</a></li>
+        <li><a href="howto_filebased.html#Automatic Saving">Automatic Saving</a></li>
+        <li><a href="howto_filebased.html#Automatic Reloading">Automatic Reloading</a></li>
+      </ul>
+      <li><a href="howto_xml.html#Hierarchical properties">Hierarchical properties</a></li>
+      <ul>
+        <li><a href="howto_xml.html#Accessing properties defined in XML documents">Accessing properties defined in XML documents</a></li>
+        <li><a href="howto_xml.html#Structured XML">Structured XML</a></li>
+        <li><a href="howto_xml.html#Accessing structured properties">Accessing structured properties</a></li>
+        <li><a href="howto_xml.html#Adding new properties">Adding new properties</a></li>
+        <li><a href="howto_xml.html#Escaping dot characters in XML tags">Escaping dot characters in XML tags</a></li>
+      </ul>
+      <li><a href="howto_xml.html#Expression engines">Expression engines</a></li>
+      <ul>
+        <li><a href="howto_xml.html#The default expression engine">The default expression engine</a></li>
+        <li><a href="howto_xml.html#The XPATH expression engine">The XPATH expression engine</a></li>
+      </ul>
+      <li><a href="howto_xml.html#Validation of XML configuration files">Validation of XML configuration files</a></li>
+      <li><a href="howto_compositeconfiguration.html#Composite Configuration Details">Composite Configuration Details</a></li>
+      <ul>
+        <li><a href="howto_compositeconfiguration.html#Setting Up Defaults">Setting Up Defaults</a></li>
+        <li><a href="howto_compositeconfiguration.html#Saving Changes">Saving Changes</a></li>
+      </ul>
+      <li><a href="howto_beans.html#Declaring and Creating Beans">Declaring and Creating Beans</a></li>
+      <ul>
+        <li><a href="howto_beans.html#Basic Concepts">Basic Concepts</a></li>
+        <li><a href="howto_beans.html#An Example">An Example</a></li>
+        <li><a href="howto_beans.html#Extending the Basic Mechanism">Extending the Basic Mechanism</a></li>
+      </ul>
+      <li><a href="howto_configurationfactory.html#Using a Configuration Factory">Using a Configuration Factory</a></li>
+      <ul>
+        <li><a href="howto_configurationfactory.html#The configuration definition file">The configuration definition file</a></li>
+        <li><a href="howto_configurationfactory.html#Setting up a ConfigurationFactory">Setting up a ConfigurationFactory</a></li>
+        <li><a href="howto_configurationfactory.html#Accessing properties">Accessing properties</a></li>
+      </ul>
+      <li><a href="howto_configurationfactory.html#Multiple configuration sources">Multiple configuration sources</a></li>
+      <ul>
+        <li><a href="howto_configurationfactory.html#Overriding properties">Overriding properties</a></li>
+        <li><a href="howto_configurationfactory.html#Optional configuration sources">Optional configuration sources</a></li>
+      </ul>
+      <li><a href="howto_configurationfactory.html#Union configuration">Union configuration</a></li>
+      <li><a href="howto_configurationfactory.html#The configuration definition file">The configuration definition file</a></li>
+      <ul>
+        <li><a href="howto_configurationfactory.html#Setting further options">Setting further options</a></li>
+      </ul>
+    </ul>
+    </section>
+</body>
+
+</document>
\ No newline at end of file

Propchange: jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml
------------------------------------------------------------------------------
    svn:keywords = Date Author Id Revision HeadURL

Propchange: jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml
------------------------------------------------------------------------------
    svn:mime-type = text/xml



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