You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by eb...@apache.org on 2007/04/13 19:31:18 UTC
svn commit: r528563 [2/2] - in /jakarta/commons/proper/configuration/trunk:
./ xdocs/ xdocs/userguide-1.2/ xdocs/userguide/
Added: jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/overview.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/overview.xml?view=auto&rev=528563
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/overview.xml (added)
+++ jakarta/commons/proper/configuration/trunk/xdocs/userguide-1.2/overview.xml Fri Apr 13 10:31:15 2007
@@ -0,0 +1,198 @@
+<?xml version="1.0"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You 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>
Copied: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_basicfeatures.xml (from r527434, jakarta/commons/proper/configuration/trunk/xdocs/howto_basicfeatures.xml)
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_basicfeatures.xml?view=diff&rev=528563&p1=jakarta/commons/proper/configuration/trunk/xdocs/howto_basicfeatures.xml&r1=527434&p2=jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_basicfeatures.xml&r2=528563
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/howto_basicfeatures.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_basicfeatures.xml Fri Apr 13 10:31:15 2007
@@ -19,7 +19,7 @@
<document>
<properties>
- <title>Configuration Basic Features</title>
+ <title>Basic Features</title>
<author email="oheger@apache.org">Oliver Heger</author>
</properties>
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_basicfeatures.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_basicfeatures.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_basicfeatures.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Copied: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_beans.xml (from r527434, jakarta/commons/proper/configuration/trunk/xdocs/howto_beans.xml)
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_beans.xml?view=diff&rev=528563&p1=jakarta/commons/proper/configuration/trunk/xdocs/howto_beans.xml&r1=527434&p2=jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_beans.xml&r2=528563
==============================================================================
(empty)
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_beans.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_beans.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_beans.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Copied: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_combinedconfiguration.xml (from r527434, jakarta/commons/proper/configuration/trunk/xdocs/howto_combinedconfiguration.xml)
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_combinedconfiguration.xml?view=diff&rev=528563&p1=jakarta/commons/proper/configuration/trunk/xdocs/howto_combinedconfiguration.xml&r1=527434&p2=jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_combinedconfiguration.xml&r2=528563
==============================================================================
(empty)
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_combinedconfiguration.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_combinedconfiguration.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_combinedconfiguration.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Copied: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_compositeconfiguration.xml (from r527434, jakarta/commons/proper/configuration/trunk/xdocs/howto_compositeconfiguration.xml)
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_compositeconfiguration.xml?view=diff&rev=528563&p1=jakarta/commons/proper/configuration/trunk/xdocs/howto_compositeconfiguration.xml&r1=527434&p2=jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_compositeconfiguration.xml&r2=528563
==============================================================================
(empty)
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_compositeconfiguration.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_compositeconfiguration.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Copied: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_configurationbuilder.xml (from r527434, jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationbuilder.xml)
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_configurationbuilder.xml?view=diff&rev=528563&p1=jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationbuilder.xml&r1=527434&p2=jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_configurationbuilder.xml&r2=528563
==============================================================================
(empty)
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_configurationbuilder.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_configurationbuilder.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_configurationbuilder.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Copied: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_configurationfactory.xml (from r527434, jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationfactory.xml)
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_configurationfactory.xml?view=diff&rev=528563&p1=jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationfactory.xml&r1=527434&p2=jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_configurationfactory.xml&r2=528563
==============================================================================
(empty)
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_configurationfactory.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_configurationfactory.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Copied: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_events.xml (from r527434, jakarta/commons/proper/configuration/trunk/xdocs/howto_events.xml)
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_events.xml?view=diff&rev=528563&p1=jakarta/commons/proper/configuration/trunk/xdocs/howto_events.xml&r1=527434&p2=jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_events.xml&r2=528563
==============================================================================
(empty)
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_events.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_events.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_events.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Copied: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_filebased.xml (from r527434, jakarta/commons/proper/configuration/trunk/xdocs/howto_filebased.xml)
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_filebased.xml?view=diff&rev=528563&p1=jakarta/commons/proper/configuration/trunk/xdocs/howto_filebased.xml&r1=527434&p2=jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_filebased.xml&r2=528563
==============================================================================
(empty)
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_filebased.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_filebased.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_filebased.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Copied: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_properties.xml (from r527434, jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml)
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_properties.xml?view=diff&rev=528563&p1=jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml&r1=527434&p2=jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_properties.xml&r2=528563
==============================================================================
(empty)
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_properties.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_properties.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Copied: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_utilities.xml (from r527434, jakarta/commons/proper/configuration/trunk/xdocs/howto_utilities.xml)
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_utilities.xml?view=diff&rev=528563&p1=jakarta/commons/proper/configuration/trunk/xdocs/howto_utilities.xml&r1=527434&p2=jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_utilities.xml&r2=528563
==============================================================================
(empty)
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_utilities.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_utilities.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_utilities.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Copied: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_xml.xml (from r527434, jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml)
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_xml.xml?view=diff&rev=528563&p1=jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml&r1=527434&p2=jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_xml.xml&r2=528563
==============================================================================
(empty)
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_xml.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/howto_xml.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Copied: jakarta/commons/proper/configuration/trunk/xdocs/userguide/user_guide.xml (from r527434, jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml)
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/userguide/user_guide.xml?view=diff&rev=528563&p1=jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml&r1=527434&p2=jakarta/commons/proper/configuration/trunk/xdocs/userguide/user_guide.xml&r2=528563
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/userguide/user_guide.xml Fri Apr 13 10:31:15 2007
@@ -24,7 +24,8 @@
</properties>
<body>
- <section name="About this document">
+
+ <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
@@ -37,7 +38,7 @@
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
+ <a href="../userguide-1.2/index.html">Howtos</a> documents, which specifically
deal with this version.
</p>
</section>
@@ -145,6 +146,7 @@
</ul>
</ul>
</section>
+
</body>
</document>
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/user_guide.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/user_guide.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: jakarta/commons/proper/configuration/trunk/xdocs/userguide/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