epugh 2003/06/02 11:01:01
Added: configuration/xdocs navigation.xml tasks.xml overview.xml
Log:
Adding documentation on how to use commons-configuration.
Revision Changes Path
1.1 jakarta-commons-sandbox/configuration/xdocs/navigation.xml
Index: navigation.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="Configuration">
<title>Configuration</title>
<organizationLogo href="/images/jakarta-logo-blue.gif">Jakarta</organizationLogo>
<body>
<menu name="Configuration">
<item name="Home" href="/index.html"/>
<item name="Overview" href="/overview.html"/>
<item name="To Do List" href="/tasks.html"/>
</menu>
</body>
</project>
1.1 jakarta-commons-sandbox/configuration/xdocs/tasks.xml
Index: tasks.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>TODO</title>
<author email="[EMAIL PROTECTED]">Eric Pugh</author>
</properties>
<body>
<section name="TODO list">
<p>
The following is a list of items that need to be completed in
Configuration. Contributions are welcome!
</p>
<subsection name="High priority">
</subsection>
<subsection name="Medium priority">
<ul>
<li>
<strong>Avalon Integration</strong>
Need to be able to retrieve configuration values from Avalon,
and pass them into Avalon.
</li>
</ul>
</subsection>
<subsection name="Low priority">
</subsection>
</section>
<section name='Completed'>
<subsection name="Since Last Release">
</subsection>
</section>
</body>
</document>
1.1 jakarta-commons-sandbox/configuration/xdocs/overview.xml
Index: overview.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Configuration Overview</title>
<author email="[EMAIL PROTECTED]">Eric Pugh</author>
</properties>
<body>
<section name="Using Configuration">
<p>
The best way to learn how to use Configuration is to look at the various
testcases
that it comes with. This will demonstrate how a Configuration object is
populated
from multiple different sources.
</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>BasePropertiesConfiguration</strong>
An in-memory method of populating a Configuration object.
</li>
<li>
<strong>ConfigurationConverter</strong>
Takes an o.a.c.collections.ExtendedProperties and converts it to a
Configuration
object.
</li>
<li>
<strong>DOM4JConfiguration</strong>
Takes values from an XML documentation using DOM4J.
</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
CompositeConfiguration you can
provide many different ways of setting up a configuration. You can either
do it manually (see
JUnit testcase "TestCompositeConfiguration.java", or via the
ConfigurationFactory class.
</p>
<p>
Using the ConfigurationFactory, (see the Junit testcase
"TestConfigurationFactory.java") you load
up a digesterRules.xml file that specifies how to load up all the
Configuration objects. Here is
a sample one using the default digesterRules.xml file:
<pre>
<?xml version="1.0" encoding="ISO-8859-1" ?>
<configuration>
<jndi className="org.apache.commons.configuration.JNDIConfiguration"
prefix="java:comp/env"/>
<properties className="org.apache.commons.configuration.PropertiesConfiguration"
fileName="conf/test.properties"/>
<dom4j className="org.apache.commons.configuration.DOM4JConfiguration"
fileName="conf/test.xml"/>
</configuration>
</pre>
What this says is that we are loading up all JNDI values under java:comp/env
key, as well
as a properties file in conf/test.properties as well as a dom4j XML file in
conf/test.xml.
Please inspect the test cases and the files in the conf/ directory for more
information.
</p>
</subsection>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
