You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by ep...@apache.org on 2003/06/02 20:01:02 UTC
cvs commit: jakarta-commons-sandbox/configuration/xdocs navigation.xml tasks.xml overview.xml
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="epugh@upstate.com">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="epugh@upstate.com">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: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org