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="[EMAIL PROTECTED]">Eric Pugh</author> + <author email="[EMAIL PROTECTED]">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="[EMAIL PROTECTED]">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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
