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

 <?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>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>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 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 digester xml file that specifies how to load up all the Configuration objects.  Here is
         a sample one using the default digesterRules.xml file:
         <source>
 <![CDATA[
 <?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"/>
   <xml className="org.apache.commons.configuration.XMLConfiguration" fileName="conf/test.xml"/>
 </configuration>
 ]]>
         </source>

         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!
       </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!
       </p>
       <subsection name="Classic Properties File">
         <source>
 <![CDATA[
   <properties className="org.apache.commons.configuration.PropertiesConfiguration" 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 className="org.apache.commons.configuration.XMLConfiguration" 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 "test.short".  The root element can be called anything.
         </p>
       </subsection>
       <subsection name="JNDI Properties File">
         <source>
 <![CDATA[
   <jndi className="org.apache.commons.configuration.JNDIConfiguration" 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.
         </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 "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.
         </p>
       </subsection>
     </section>

 </body>
 </document>
	<?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>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>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 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 digester xml file that specifies how to load up all the Configuration objects. Here is
	a sample one using the default digesterRules.xml file:
	<source>
	<![CDATA[
	<?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"/>
	<xml className="org.apache.commons.configuration.XMLConfiguration" fileName="conf/test.xml"/>
	</configuration>
	]]>
	</source>

	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!
	</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!
	</p>
	<subsection name="Classic Properties File">
	<source>
	<![CDATA[
	<properties className="org.apache.commons.configuration.PropertiesConfiguration" 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 className="org.apache.commons.configuration.XMLConfiguration" 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 "test.short". The root element can be called anything.
	</p>
	</subsection>
	<subsection name="JNDI Properties File">
	<source>
	<![CDATA[
	<jndi className="org.apache.commons.configuration.JNDIConfiguration" 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.
	</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 "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.
	</p>
	</subsection>
	</section>

	</body>
	</document>