About Us Home Contributors License Components Sandbox Configuration Home Overview Simple Howto ConfigurationFactory Howto XML Howto Composite Config Howto Runtime Dependencies Roadmap Javadoc Extensions Avalon Component Project Documentation About Commons Configuration Downloads Project Info Project Reports Development Process General Information Charter Volunteering Contributing Patches Releasing Components Jakarta Community Get Involved Mailing Lists Access CVS Repositories Commons Resources (Unofficial) Wiki Japanese Translation Korean Translation Related Apache Commons DB Commons XML Commons | ### Using Configuration 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. #### Configuration Sources 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: PropertiesConfiguration Loads configuration values from a properties file. BaseConfiguration An in-memory method of populating a Configuration object. XMLConfiguration Takes values from an XML document. JNDIConfiguration Using a key in the JNDI tree, can retrieve values as configuration properties. ConfigurationConverter Takes a java.util.Properties or an o.a.c.collections.ExtendedProperties and converts it to a Configuration object. #### Mixing Configuration Sources 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. 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:
    <?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>
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.. 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! ### Configuration Details 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! #### Classic Properties File
      <properties className="org.apache.commons.configuration.PropertiesConfiguration" fileName="conf/test.properties"/>
This configuration file is very simple. You just need to specify the path to the property file. #### XML Properties File
      <xml className="org.apache.commons.configuration.XMLConfiguration" fileName="conf/test.xml"/>
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.
    <baseElement>
      <element>value</element>
      <element2>
        <subelement>
          <subsubelement>I'm complex!</subsubelement>
        </subelement>
      </element2>
      <test>
        <short>8</short>
      </test>
    </baseElement>
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. #### JNDI Properties File
      <jndi className="org.apache.commons.configuration.JNDIConfiguration" prefix="java:comp/env"/>
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.
        <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>
Note! 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.