xdocs/overview.xml - commons-configuration - Git at Google

 <?xml version="1.0"?>
 <!--
    Copyright 2004-2005 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>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>BaseConfiguration</strong>
               An in-memory method of populating a Configuration object.
           </li>
           <li>
               <strong>XMLConfiguration</strong>
               Takes values from an XML document.
           </li>
           <li>
               <strong>JNDIConfiguration</strong>
               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
         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>
	<?xml version="1.0"?>
	<!--
	Copyright 2004-2005 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>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>BaseConfiguration</strong>
	An in-memory method of populating a Configuration object.
	</li>
	<li>
	<strong>XMLConfiguration</strong>
	Takes values from an XML document.
	</li>
	<li>
	<strong>JNDIConfiguration</strong>
	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
	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>