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]