ebourg 2004/10/25 07:12:02
Modified: configuration/xdocs overview.xml
Log:
documentation update:
- removed the references to the unit tests, this is discouraging for new users
- more examples
- replaced "digester file" by "configuration descriptor" since digester is just an
implementation detail
Revision Changes Path
1.7 +70 -54 jakarta-commons/configuration/xdocs/overview.xml
Index: overview.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/configuration/xdocs/overview.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- overview.xml 22 Oct 2004 01:40:48 -0000 1.6
+++ overview.xml 25 Oct 2004 14:12:02 -0000 1.7
@@ -1,25 +1,25 @@
<?xml version="1.0"?>
<document>
-
- <properties>
- <title>Configuration Overview</title>
- <author email="[EMAIL PROTECTED]">Eric Pugh</author>
- </properties>
-
-<body>
+ <properties>
+ <title>Configuration Overview</title>
+ <author email="[EMAIL PROTECTED]">Eric Pugh</author>
+ <author email="[EMAIL PROTECTED]">Emmanuel Bourg</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.
+ 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,
+ 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
+ JNDIConfiguration, you are sheltered from the mechanics of actually
retrieving the
configuration values. These various sources include:
<ul>
<li>
@@ -39,61 +39,74 @@
Using a key in the JNDI tree, can retrieve values as configuration
properties.
</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
+ 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.
+ 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>
- Using the ConfigurationFactory, (see the Junit testcase
"TestConfigurationFactory.java") you load
- up a digester xml file that specifies how to load up all the Configuration
objects. Here is
- a sample one using the default digesterRules.xml file:
+ 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[
+<source><![CDATA[
<?xml version="1.0" encoding="ISO-8859-1" ?>
<configuration>
- <jndi prefix="java:comp/env"/>
- <properties fileName="conf/test.properties"/>
- <xml fileName="conf/test.xml"/>
+ <system/>
+ <properties fileName="application.properties"/>
</configuration>
]]></source>
<p>
- 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 XML file in
conf/test.xml.
- Please inspect the test cases and the files in the conf/ directory for more
information on how
- to structure your configuration xml file..
- </p>
- <p>
- The order of precedence is first to last. So in the above example, if
there was a JNDI key
- called test.precendence and another one in the XML file called
test.precedence, then the configuration
- value from JNDI would be returned, not the one in the XML file. This
allows you to set up defaults
- in properties/xml file, but override them from JNDI or even another
XML/properties file!
+ 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 XML file and using included
Digester rules,
- parsing the individual configurations. Make sure to include the various
dependencies required for
- each type of configuration!
+ 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[
+<source><![CDATA[
<properties fileName="conf/test.properties"/>
]]></source>
@@ -106,10 +119,10 @@
<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.
+ 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[
+<source><![CDATA[
<baseElement>
<element>value</element>
<element2>
@@ -123,17 +136,19 @@
</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 "test.short". The root element can be called
anything.
+ 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 Properties File">
+ </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 ConfigurationFactory what the root will be to look up your
configuration settings.
+ 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>
@@ -141,7 +156,7 @@
<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>
@@ -149,13 +164,14 @@
</env-entry>
]]></source>
<p>
- <strong>Note!</strong> If you have a property called "test.short" with
spaces in it, then it will be translated
- as the key "test/short". 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 web.xml the
- "." characters to "/" characters, like in the test.short example above.
+ <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>
+ </subsection>
</section>
-</body>
+ </body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
