commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject svn commit: r952622 [1/3] - in /commons/proper/configuration/trunk: conf/ src/java/org/apache/commons/configuration/ src/java/org/apache/commons/configuration/interpol/ src/java/org/apache/commons/configuration/reloading/ src/java/org/apache/commons/co...
Date Tue, 08 Jun 2010 11:56:31 GMT
Author: sebb
Date: Tue Jun  8 11:56:30 2010
New Revision: 952622

URL: http://svn.apache.org/viewvc?rev=952622&view=rev
Log:
SVN eol-style

Modified:
    commons/proper/configuration/trunk/conf/CommonsConfiguration.xsd   (props changed)
    commons/proper/configuration/trunk/conf/PropertyList-1.0.dtd   (contents, props changed)
    commons/proper/configuration/trunk/conf/checkstyle-suppressions.xml   (contents, props changed)
    commons/proper/configuration/trunk/conf/configA.xml   (props changed)
    commons/proper/configuration/trunk/conf/configB.xml   (props changed)
    commons/proper/configuration/trunk/conf/log4j-test.xml   (props changed)
    commons/proper/configuration/trunk/conf/test.plist.xml   (contents, props changed)
    commons/proper/configuration/trunk/conf/testMultiConfiguration.xsd   (props changed)
    commons/proper/configuration/trunk/conf/testMultiConfiguration_2002.xml   (props changed)
    commons/proper/configuration/trunk/conf/testMultiDynamic_default2.xml   (props changed)
    commons/proper/configuration/trunk/conf/testMultiTenentConfigurationBuilder.xml   (props changed)
    commons/proper/configuration/trunk/conf/testMultiTenentConfigurationBuilder2.xml   (props changed)
    commons/proper/configuration/trunk/conf/testMultiTenentConfigurationBuilder3.xml   (props changed)
    commons/proper/configuration/trunk/conf/testMultiTenentConfigurationBuilder4.xml   (props changed)
    commons/proper/configuration/trunk/conf/testMultiTenentConfigurationBuilder5.xml   (props changed)
    commons/proper/configuration/trunk/conf/testVFSMultiTenentConfigurationBuilder1.xml   (props changed)
    commons/proper/configuration/trunk/conf/testVFSMultiTenentConfigurationBuilder2.xml   (props changed)
    commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/HierarchicalReloadableConfiguration.java   (props changed)
    commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/Lock.java   (props changed)
    commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/interpol/package.html   (props changed)
    commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/reloading/Reloadable.java   (props changed)
    commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/resolver/EntityResolverSupport.java   (props changed)
    commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/resolver/package.html   (props changed)
    commons/proper/configuration/trunk/src/site/xdoc/javadocarchive.xml   (contents, props changed)
    commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_compositeconfiguration.xml   (contents, props changed)
    commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_configurationfactory.xml   (contents, props changed)
    commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_properties.xml   (contents, props changed)
    commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_xml.xml   (contents, props changed)
    commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/index.xml   (contents, props changed)
    commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/overview.xml   (contents, props changed)
    commons/proper/configuration/trunk/src/test/org/apache/commons/configuration/Logging.java   (props changed)
    commons/proper/configuration/trunk/src/test/org/apache/commons/configuration/plist/TestPropertyListConfiguration.java   (contents, props changed)
    commons/proper/configuration/trunk/src/test/org/apache/commons/configuration/plist/TestPropertyListParser.java   (contents, props changed)
    commons/proper/configuration/trunk/src/test/org/apache/commons/configuration/plist/TestXMLPropertyListConfiguration.java   (contents, props changed)
    commons/proper/configuration/trunk/src/test/org/apache/commons/configuration/reloading/FileRandomReloadingStrategy.java   (props changed)

Propchange: commons/proper/configuration/trunk/conf/CommonsConfiguration.xsd
            ('svn:executable' removed)

Modified: commons/proper/configuration/trunk/conf/PropertyList-1.0.dtd
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/conf/PropertyList-1.0.dtd?rev=952622&r1=952621&r2=952622&view=diff
==============================================================================
--- commons/proper/configuration/trunk/conf/PropertyList-1.0.dtd (original)
+++ commons/proper/configuration/trunk/conf/PropertyList-1.0.dtd Tue Jun  8 11:56:30 2010
@@ -1,19 +1,19 @@
-<!ENTITY % plistObject "(array | data | date | dict | real | integer | string | true | false )" >
-<!ELEMENT plist %plistObject;>
-<!ATTLIST plist version CDATA "1.0" >
-
-<!-- Collections -->
-<!ELEMENT array (%plistObject;)*>
-<!ELEMENT dict (key, %plistObject;)*>
-<!ELEMENT key (#PCDATA)>
-
-<!--- Primitive types -->
-<!ELEMENT string (#PCDATA)>
-<!ELEMENT data (#PCDATA)> <!-- Contents interpreted as Base-64 encoded -->
-<!ELEMENT date (#PCDATA)> <!-- Contents should conform to a subset of ISO 8601 (in particular, YYYY '-' MM '-' DD 'T' HH ':' MM ':' SS 'Z'.  Smaller units may be omitted with a loss of precision) -->
-
-<!-- Numerical primitives -->
-<!ELEMENT true EMPTY>  <!-- Boolean constant true -->
-<!ELEMENT false EMPTY> <!-- Boolean constant false -->
-<!ELEMENT real (#PCDATA)> <!-- Contents should represent a floating point number matching ("+" | "-")? d+ ("."d*)? ("E" ("+" | "-") d+)? where d is a digit 0-9.  -->
-<!ELEMENT integer (#PCDATA)> <!-- Contents should represent a (possibly signed) integer number in base 10 -->
+<!ENTITY % plistObject "(array | data | date | dict | real | integer | string | true | false )" >
+<!ELEMENT plist %plistObject;>
+<!ATTLIST plist version CDATA "1.0" >
+
+<!-- Collections -->
+<!ELEMENT array (%plistObject;)*>
+<!ELEMENT dict (key, %plistObject;)*>
+<!ELEMENT key (#PCDATA)>
+
+<!--- Primitive types -->
+<!ELEMENT string (#PCDATA)>
+<!ELEMENT data (#PCDATA)> <!-- Contents interpreted as Base-64 encoded -->
+<!ELEMENT date (#PCDATA)> <!-- Contents should conform to a subset of ISO 8601 (in particular, YYYY '-' MM '-' DD 'T' HH ':' MM ':' SS 'Z'.  Smaller units may be omitted with a loss of precision) -->
+
+<!-- Numerical primitives -->
+<!ELEMENT true EMPTY>  <!-- Boolean constant true -->
+<!ELEMENT false EMPTY> <!-- Boolean constant false -->
+<!ELEMENT real (#PCDATA)> <!-- Contents should represent a floating point number matching ("+" | "-")? d+ ("."d*)? ("E" ("+" | "-") d+)? where d is a digit 0-9.  -->
+<!ELEMENT integer (#PCDATA)> <!-- Contents should represent a (possibly signed) integer number in base 10 -->

Propchange: commons/proper/configuration/trunk/conf/PropertyList-1.0.dtd
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: commons/proper/configuration/trunk/conf/checkstyle-suppressions.xml
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/conf/checkstyle-suppressions.xml?rev=952622&r1=952621&r2=952622&view=diff
==============================================================================
--- commons/proper/configuration/trunk/conf/checkstyle-suppressions.xml (original)
+++ commons/proper/configuration/trunk/conf/checkstyle-suppressions.xml Tue Jun  8 11:56:30 2010
@@ -1,22 +1,22 @@
-<?xml version="1.0"?>
-
-<!DOCTYPE suppressions PUBLIC
-    "-//Puppy Crawl//DTD Suppressions 1.0//EN"
-    "http://www.puppycrawl.com/dtds/suppressions_1_0.dtd">
-
-<!-- Exceptions for Checkstyle -->
-
-<suppressions>
-
-    <!-- Disable the warnings for the generated classes -->
-    <suppress checks=".*" files="ParseException.java"/>
-    <suppress checks=".*" files="PropertyListParser.java"/>
-    <suppress checks=".*" files="PropertyListParserConstants.java"/>
-    <suppress checks=".*" files="PropertyListParserTokenManager.java"/>
-    <suppress checks=".*" files="SimpleCharStream.java"/>
-    <suppress checks=".*" files="Token.java"/>
-    <suppress checks=".*" files="TokenMgrError.java"/>
-    
-    <suppress checks="MissingSwitchDefault" files="PropertiesConfiguration.java"/>
-
-</suppressions>
+<?xml version="1.0"?>
+
+<!DOCTYPE suppressions PUBLIC
+    "-//Puppy Crawl//DTD Suppressions 1.0//EN"
+    "http://www.puppycrawl.com/dtds/suppressions_1_0.dtd">
+
+<!-- Exceptions for Checkstyle -->
+
+<suppressions>
+
+    <!-- Disable the warnings for the generated classes -->
+    <suppress checks=".*" files="ParseException.java"/>
+    <suppress checks=".*" files="PropertyListParser.java"/>
+    <suppress checks=".*" files="PropertyListParserConstants.java"/>
+    <suppress checks=".*" files="PropertyListParserTokenManager.java"/>
+    <suppress checks=".*" files="SimpleCharStream.java"/>
+    <suppress checks=".*" files="Token.java"/>
+    <suppress checks=".*" files="TokenMgrError.java"/>
+    
+    <suppress checks="MissingSwitchDefault" files="PropertiesConfiguration.java"/>
+
+</suppressions>

Propchange: commons/proper/configuration/trunk/conf/checkstyle-suppressions.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/configuration/trunk/conf/configA.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/configuration/trunk/conf/configB.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/configuration/trunk/conf/log4j-test.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: commons/proper/configuration/trunk/conf/test.plist.xml
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/conf/test.plist.xml?rev=952622&r1=952621&r2=952622&view=diff
==============================================================================
--- commons/proper/configuration/trunk/conf/test.plist.xml (original)
+++ commons/proper/configuration/trunk/conf/test.plist.xml Tue Jun  8 11:56:30 2010
@@ -1,87 +1,87 @@
-<?xml version="1.0"?>
-<!DOCTYPE plist SYSTEM "file://localhost/System/Library/DTDs/PropertyList.dtd">
-<plist version="1.0">
-    <dict>
-
-        <key>string</key>
-        <string>value1</string>
-
-        <key>integer</key>
-        <integer>12345678900</integer>
-
-        <key>real</key>
-        <real>-123.45E-1</real>
-
-        <key>boolean1</key>
-        <true/>
-
-        <key>boolean2</key>
-        <false/>
-
-        <key>date</key>
-        <date>2005-01-01T12:00:00Z</date>
-
-        <key>date-gnustep</key>
-        <date>2002-03-22 11:30:00 +0100</date>
-
-        <key>data</key>
-        <data>RHJhY28gRG9ybWllbnMgTnVucXVhbSBUaXRpbGxhbmR1cw==</data>
-
-        <key>array</key>
-        <array>
-            <string>value1</string>
-            <string>value2</string>
-            <string>value3</string>
-        </array>
-
-        <key>nested-array</key>
-        <array>
-            <array>
-                <string>a</string>
-                <string>b</string>
-            </array>
-            <array>
-                <string>c</string>
-                <string>d</string>
-            </array>
-        </array>
-
-        <key>dictionary-array</key>
-        <array>
-            <dict>
-                <key>foo</key>
-                <string>bar</string>
-            </dict>
-            <dict>
-                <key>key</key>
-                <string>value</string>
-            </dict>
-        </array>
-
-        <key>dictionary</key>
-        <dict>
-            <key>key1</key>
-            <string>value1</string>
-            <key>key2</key>
-            <string>value2</string>
-            <key>key3</key>
-            <string>value3</string>
-        </dict>
-
-        <key>nested</key>
-        <dict>
-            <key>node1</key>
-            <dict>
-                <key>node2</key>
-                <dict>
-                    <key>node3</key>
-                    <string>value</string>
-                </dict>
-            </dict>
-        </dict>
-
-        <key>empty-dictionary</key>
-        <dict/>
-
-    </dict>
-</plist>
+<?xml version="1.0"?>
+<!DOCTYPE plist SYSTEM "file://localhost/System/Library/DTDs/PropertyList.dtd">
+<plist version="1.0">
+    <dict>
+
+        <key>string</key>
+        <string>value1</string>
+
+        <key>integer</key>
+        <integer>12345678900</integer>
+
+        <key>real</key>
+        <real>-123.45E-1</real>
+
+        <key>boolean1</key>
+        <true/>
+
+        <key>boolean2</key>
+        <false/>
+
+        <key>date</key>
+        <date>2005-01-01T12:00:00Z</date>
+
+        <key>date-gnustep</key>
+        <date>2002-03-22 11:30:00 +0100</date>
+
+        <key>data</key>
+        <data>RHJhY28gRG9ybWllbnMgTnVucXVhbSBUaXRpbGxhbmR1cw==</data>
+
+        <key>array</key>
+        <array>
+            <string>value1</string>
+            <string>value2</string>
+            <string>value3</string>
+        </array>
+
+        <key>nested-array</key>
+        <array>
+            <array>
+                <string>a</string>
+                <string>b</string>
+            </array>
+            <array>
+                <string>c</string>
+                <string>d</string>
+            </array>
+        </array>
+
+        <key>dictionary-array</key>
+        <array>
+            <dict>
+                <key>foo</key>
+                <string>bar</string>
+            </dict>
+            <dict>
+                <key>key</key>
+                <string>value</string>
+            </dict>
+        </array>
+
+        <key>dictionary</key>
+        <dict>
+            <key>key1</key>
+            <string>value1</string>
+            <key>key2</key>
+            <string>value2</string>
+            <key>key3</key>
+            <string>value3</string>
+        </dict>
+
+        <key>nested</key>
+        <dict>
+            <key>node1</key>
+            <dict>
+                <key>node2</key>
+                <dict>
+                    <key>node3</key>
+                    <string>value</string>
+                </dict>
+            </dict>
+        </dict>
+
+        <key>empty-dictionary</key>
+        <dict/>
+
+    </dict>
+</plist>

Propchange: commons/proper/configuration/trunk/conf/test.plist.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/configuration/trunk/conf/testMultiConfiguration.xsd
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/configuration/trunk/conf/testMultiConfiguration_2002.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/configuration/trunk/conf/testMultiDynamic_default2.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/configuration/trunk/conf/testMultiTenentConfigurationBuilder.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/configuration/trunk/conf/testMultiTenentConfigurationBuilder2.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/configuration/trunk/conf/testMultiTenentConfigurationBuilder3.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/configuration/trunk/conf/testMultiTenentConfigurationBuilder4.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/configuration/trunk/conf/testMultiTenentConfigurationBuilder5.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/configuration/trunk/conf/testVFSMultiTenentConfigurationBuilder1.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/configuration/trunk/conf/testVFSMultiTenentConfigurationBuilder2.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/HierarchicalReloadableConfiguration.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/Lock.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/interpol/package.html
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/reloading/Reloadable.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/resolver/EntityResolverSupport.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/resolver/package.html
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: commons/proper/configuration/trunk/src/site/xdoc/javadocarchive.xml
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/site/xdoc/javadocarchive.xml?rev=952622&r1=952621&r2=952622&view=diff
==============================================================================
--- commons/proper/configuration/trunk/src/site/xdoc/javadocarchive.xml (original)
+++ commons/proper/configuration/trunk/src/site/xdoc/javadocarchive.xml Tue Jun  8 11:56:30 2010
@@ -1,43 +1,43 @@
-<?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>Javadoc archives</title>
-    <author email="ebourg@apache.org">Emmanuel Bourg</author>
-  </properties>
-  <body>
-
-    <section name="Javadoc archive">
-
-      <p>Commons Configuration 1.5 (<a href="apidocs_1.5/index.html">javadoc</a>)</p>
-
-      <p>Commons Configuration 1.4 (<a href="apidocs_1.4/index.html">javadoc</a>)</p>
-
-      <p>Commons Configuration 1.3 (<a href="apidocs_1.3/index.html">javadoc</a>)</p>
-
-      <p>Commons Configuration 1.2 (<a href="apidocs_1.2/index.html">javadoc</a>)</p>
-
-      <p>Commons Configuration 1.1 (<a href="apidocs_1.1/index.html">javadoc</a>)</p>
-
-      <p>Commons Configuration 1.0 (<a href="apidocs_1.0/index.html">javadoc</a>)</p>
-
-    </section>
-
-  </body>
-</document>
+<?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>Javadoc archives</title>
+    <author email="ebourg@apache.org">Emmanuel Bourg</author>
+  </properties>
+  <body>
+
+    <section name="Javadoc archive">
+
+      <p>Commons Configuration 1.5 (<a href="apidocs_1.5/index.html">javadoc</a>)</p>
+
+      <p>Commons Configuration 1.4 (<a href="apidocs_1.4/index.html">javadoc</a>)</p>
+
+      <p>Commons Configuration 1.3 (<a href="apidocs_1.3/index.html">javadoc</a>)</p>
+
+      <p>Commons Configuration 1.2 (<a href="apidocs_1.2/index.html">javadoc</a>)</p>
+
+      <p>Commons Configuration 1.1 (<a href="apidocs_1.1/index.html">javadoc</a>)</p>
+
+      <p>Commons Configuration 1.0 (<a href="apidocs_1.0/index.html">javadoc</a>)</p>
+
+    </section>
+
+  </body>
+</document>

Propchange: commons/proper/configuration/trunk/src/site/xdoc/javadocarchive.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_compositeconfiguration.xml
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_compositeconfiguration.xml?rev=952622&r1=952621&r2=952622&view=diff
==============================================================================
--- commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_compositeconfiguration.xml (original)
+++ commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_compositeconfiguration.xml Tue Jun  8 11:56:30 2010
@@ -1,81 +1,81 @@
-<?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>Composite Configuration Details</title>
-  <author email="epugh@opensourceconnections.com">Eric Pugh</author>
- </properties>
-
-<body>
-
-    <section name="Composite Configuration Details">
-    	<p>
-    		We will discuss how you can establish a "default" choice for your
-    		Composite Configuration as well as save changes made to your
-    		Composite Configuration.
-    	</p>
-    	<subsection name="Setting Up Defaults">
-    		<p>
-    			Defaults are very simple.  You can just add them as your last configuration object, 
-    			either through the ConfigurationFactory or manually:
-    		</p>
-    			<source><![CDATA[
-Configuration defaults = new PropertiesConfiguration(fileToDefaults);
-Configuration otherProperties = new PropertiesConfiguration(fileToOtherProperties);
-CompositeConfiguration cc = new CompositeConfiguration();
-cc.addConfiguration(otherProperties);
-cc.addDefaults(fileToDefaults);
-]]></source>
-		</subsection>
-		
-		<subsection name="Saving Changes">
-			<p>
-				If you have a non static Configuration where you want to 
-				save changes made to a configuration, and you are using a
-				CompositeConfiguration, then you will need to pass into
-				the constructor of the CompositeConfiguration what Configuration
-				to save the changes via.  
-			</p>
-    			<source><![CDATA[
-PropertiesConfiguration saveConfiguration = new PropertiesConfiguration(fileToSaveChangesIn);
-Configuration cc = new CompositeConfiguration(saveConfiguration);
-cc.setProperty("newProperty","new value");
-
-saveConfiguration.save();
-]]></source>
-			<p>
-				Alternatively, you can just request the
-				inMemoryConfiguration that stores the changes:
-    			<source><![CDATA[
-Configuration changes = myCompositeConfiguration.getInMemoryConfiguration();
-DatabaseConfiguration config = new DatabaseConfiguration(datasource, "configuration", "key", "value");
-for (Iterator i = changes.getKeys().iterator();i.hasNext()){
-	String key = (key)i.next();
-	Object value = changes.get(key);
-	config.setProperty(key,value);
-}
-]]></source>
-			</p>
-		
-		</subsection>		
-	</section>
-</body>
-
+<?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>Composite Configuration Details</title>
+  <author email="epugh@opensourceconnections.com">Eric Pugh</author>
+ </properties>
+
+<body>
+
+    <section name="Composite Configuration Details">
+    	<p>
+    		We will discuss how you can establish a "default" choice for your
+    		Composite Configuration as well as save changes made to your
+    		Composite Configuration.
+    	</p>
+    	<subsection name="Setting Up Defaults">
+    		<p>
+    			Defaults are very simple.  You can just add them as your last configuration object, 
+    			either through the ConfigurationFactory or manually:
+    		</p>
+    			<source><![CDATA[
+Configuration defaults = new PropertiesConfiguration(fileToDefaults);
+Configuration otherProperties = new PropertiesConfiguration(fileToOtherProperties);
+CompositeConfiguration cc = new CompositeConfiguration();
+cc.addConfiguration(otherProperties);
+cc.addDefaults(fileToDefaults);
+]]></source>
+		</subsection>
+		
+		<subsection name="Saving Changes">
+			<p>
+				If you have a non static Configuration where you want to 
+				save changes made to a configuration, and you are using a
+				CompositeConfiguration, then you will need to pass into
+				the constructor of the CompositeConfiguration what Configuration
+				to save the changes via.  
+			</p>
+    			<source><![CDATA[
+PropertiesConfiguration saveConfiguration = new PropertiesConfiguration(fileToSaveChangesIn);
+Configuration cc = new CompositeConfiguration(saveConfiguration);
+cc.setProperty("newProperty","new value");
+
+saveConfiguration.save();
+]]></source>
+			<p>
+				Alternatively, you can just request the
+				inMemoryConfiguration that stores the changes:
+    			<source><![CDATA[
+Configuration changes = myCompositeConfiguration.getInMemoryConfiguration();
+DatabaseConfiguration config = new DatabaseConfiguration(datasource, "configuration", "key", "value");
+for (Iterator i = changes.getKeys().iterator();i.hasNext()){
+	String key = (key)i.next();
+	Object value = changes.get(key);
+	config.setProperty(key,value);
+}
+]]></source>
+			</p>
+		
+		</subsection>		
+	</section>
+</body>
+
 </document>
\ No newline at end of file

Propchange: commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_compositeconfiguration.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_configurationfactory.xml
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_configurationfactory.xml?rev=952622&r1=952621&r2=952622&view=diff
==============================================================================
--- commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_configurationfactory.xml (original)
+++ commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_configurationfactory.xml Tue Jun  8 11:56:30 2010
@@ -1,526 +1,526 @@
-<?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 Factory Howto</title>
-  <author email="oliver.heger@t-online.de">Oliver Heger</author>
- </properties>
-
-<body>		
-	<section name="Using a Configuration Factory">
-		<p>
- 	 		This section explains how a
-    		<code>ConfigurationFactory</code> object is setup that provides access
-    		to a collection of different configuration sources.
-    	</p>
-    		
-		<subsection name="The configuration definition file">
-			<p>
-				When a single configuration file (e.g. a properties file) is the only
-				source of configuration data it is very simple to
-				load it using the specific configuration class that deals with
-                the corresponding format (e.g. <code>PropertiesConfiguration</code>
-                for properties files or <code>XMLConfiguration</code> for XML files). But because
-				we think that later other sources will be added (otherwise
-				this example section would be too silly) we will use a
-				<code>ConfigurationFactory</code> object to load it.
-			</p>
-			<p>
-				<code>ConfigurationFactory</code> allows to combine
-				multiple configuration sources. The properties defined in these
-				sources can then be accessed as if they were defined in a
-				single configuration file. To make use of this we have to
-				create a XML file which tells the factory from which sources
-				the properties are to be collected. The following listing shows
-				the content of this file:
-			</p>
-   			<source><![CDATA[
-<?xml version="1.0" encoding="ISO-8859-1" ?>
-
-<configuration>
-  <properties fileName="usergui.properties"/>
-</configuration>
-]]></source>
-			<p>
-				Definition files for <code>ConfigurationFactory</code> are
-				normal XML files. The root element must be named
-				<code>configuration</code>. It can contain different sub
-				elements that specify the configuration sources to load. The
-				<code>properties</code> element is one of these; it is used to
-				include properties files.
-			</p>
-			<p>
-				For this example we store the definition file for
-				<code>ConfigurationFactory</code> in the same directory as the
-				properties file and call it <code>config.xml</code>. The
-                properties file used in this example is the same as in the
-                section about <a href="howto_properties.html">properties
-                files</a>.
-			</p>
-		</subsection>
-		<subsection name="Setting up a ConfigurationFactory">
-			<p>
-				Now we have to create a <code>ConfigurationFactory</code>
-				object and let it read this definition file. This is quite simple:
-				Just create a new instance and set the name of the definition
-				file with the <code>setConfigurationFileName()</code> method.
-			</p>
-    			<source><![CDATA[
-ConfigurationFactory factory = new ConfigurationFactory();
-URL configURL = new File("config.xml").toURL();
-factory.setConfigurationFileName(configURL.toString());
-Configuration config = factory.getConfiguration();
-]]></source>
-			<p>
-				As this code fragment shows the file name passed to the factory
-				can be a full URL. This is also the recommended way of
-				specifying the file because it provides the greatest flexibility
-				and a consistent way of handling relative file names found in
-				the definition file.
-			</p>
-			<p>
-				Here we assumed the configuration definition file to be located
-				in the current directory. It is also possible (and probably a
-				better approach) to load the file from the class path. This
-				could be done as follows:
-			</p>
-   			<source><![CDATA[
-ConfigurationFactory factory = new ConfigurationFactory();
-URL configURL = getClass().getResource("/config.xml");
-factory.setConfigurationURL(configURL);
-Configuration config = factory.getConfiguration();
-]]></source>
-    	</subsection>
-    	<subsection name="Accessing properties">
-    		<p>
-    			Whatever way we used to load the configuration factory, we
-    			should now have a <code>Configuration</code> object that was
-    			returned by the factory's <code>getConfiguration()</code>
-    			method. This object is actually an instance of the
-                <code>CompositeConfiguration</code> class, a specific implementation
-                of the <code>Configuration</code> interface that is able to
-                deal with multiple contained configuration objects. Of course
-                this class provides all the getter methods defined in the
-                <code>Configuration</code> interface, so for accessing a
-                string property for instance we	would use the <code>getString()</code> method:
-    		</p>
-   			<source><![CDATA[
-String backColor = config.getString("color.background");
-]]></source>
-    	</subsection>
-	</section>
-	
-	<section name="Multiple configuration sources">
-		<p>
-			Using <code>ConfigurationFactory</code> to collect configuration
-			sources does not make much sense if there is only one source to be
-			loaded. So let's add another one! This time we will embedd a XML file.
-		</p>
-		<subsection name="Overriding properties">
-			<p>
-				Many applications use the popular XML format for storing
-				configuration information. So it is no wonder that Configuration
-				also supports this type of configuration sources. In general
-				each XML document can be used to define configuration settings.
-				We start here with a rather simple one:
-			</p>
-   			<source><![CDATA[
-<?xml version="1.0" encoding="ISO-8859-1" ?>
-<gui-definition>
-  <colors>
-    <background>#808080</background>
-    <text>#000000</text>
-    <header>#008000</header>
-    <link normal="#000080" visited="#800080"/>
-  </colors>
-  <rowsPerPage>15</rowsPerPage>
-</gui-definition>
-]]></source>
-			<p>
-				To make this XML document part of our global configuration we
-				have to modify our configuration definition file to also include
-				the new file. For XML documents the element <code>xml</code>
-				can be used so that we have now:
-			</p>
-   			<source><![CDATA[
-<?xml version="1.0" encoding="ISO-8859-1" ?>
-
-<configuration>
-  <properties fileName="usergui.properties"/>
-  <xml fileName="gui.xml"/>
-</configuration>
-]]></source>
-			<p>
-				The code for setting up the <code>ConfigurationFactory</code>
-				object remains the same. From the <code>Configuration</code>
-                object returned by the factory the new properties can be
-                accessed in the usual way.
-			</p>
-			<p>
-				There is one problem with this example configuration setup:
-				The <code>color.background</code> property
-				is defined in both the properties and the XML file, and -
-				to make things worse - with different values. Which value will
-				be returned by a call to <code>getString()</code>?
-			</p>
-			<p>
-				The answer is that the configuration sources are searched in the
-				order they are defined in the configuration definition file.
-				Here the properties file is included first, then comes the XML
-				file. Because the <code>color.background</code> property can
-				be found in the properties file the value specified there will
-				be returned (which happens to be <code>#FFFFFF</code>).
-			</p>
-			<p>
-				It might not be obvious why it makes sense to define the value
-				of one and the same property in multiple configuration sources.
-				But consider the following scenario: An application comes with
-				a set of default properties and allows the user to override some
-				or all of them. This can now easy be realized by saving the
-				user's settings in a file and the default settings in another.
-				Then in the configuration definition file the file with the
-				user settings is included first and after that the file with the
-				default values. The application code that queries these
-				settings need not be aware whether a property was overriden by
-				the user. The <code>ConfigurationFactory</code> takes care
-				that properties defined in the first file (the user file) are
-				found; other properties which the user has not changed will
-				still be returned from the second file (the defaults file).
-			</p>
-		</subsection>
-		<subsection name="Optional configuration sources">
-			<p>
-				The example above with two configuration sources - one for user
-				settings and one with default values - raises an interesting
-				question: What will happen if the user has not defined specific
-				properties yet? Or what if a new user starts our application for
-				the first time and thus no user specific properties exist?
-			</p>
-			<p>
-				The default behavior of <code>ConfigurationFactory</code> is to
-				throw a <code>ConfigurationException</code> exception if one of
-				the sources defined in the configuration definition file cannot
-				be loaded. For our example this behavior is not desired: the
-				properties file with specific user settings is not required. If it
-				cannot be loaded, the example application will still work because
-				a complete set of configuration properties is defined in the
-				second file.
-			</p>
-			<p>
-				<code>ConfigurationFactory</code> supports such optional
-				configuration sources. For this purpose in the definition of a
-				(file based) configuration source the <code>optional</code>
-				attribute can be placed. An example of this is shown below:
-			</p>
-   			<source><![CDATA[
-<?xml version="1.0" encoding="ISO-8859-1" ?>
-
-<configuration>
-  <properties fileName="usersettings.properties" optional="true"/>
-  <properties fileName="default.properties"/>
-</configuration>
-]]></source>
-			<p>
-				In this configuration definition file the first properties file
-				with user specific settings is marked as optional. This means that
-				if it cannot be loaded, <code>ConfigurationFactory</code> will
-				not throw an exception, but only write a warning message to its
-				logger. Note that the <code>optional</code> attribute is absent
-				for the second properties file. Thus it is mandatory, and the
-				<code>getConfiguration()</code> method of
-				<code>ConfigurationFactory</code> would throw an exception if it
-				could not be found.
-			</p>
-		</subsection>
-	</section>
-
-	<section name="Union configuration">
-		<p>
-			In an earlier section about the configuration definition file for
-			<code>ConfigurationFactory</code> it was stated that configuration
-			files included first can override properties in configuraton files
-			included later and an example use case for this behaviour was given.
-			There may be times when there are other requirements.
-		</p>
-		<p>
-			Let's continue the example with the application that somehow process
-			database tables and that reads the definitions of the affected tables from
-			its configuration. This example and the corresponding XML configuration
-            files were introduced in the section about <a href="howto_xml.html">XMLConfiguration</a>.
-            Now consider that this application grows larger and
-			must be maintained by a team of developers. Each developer works on
-			a separated set of tables. In such a scenario it would be problematic
-			if the definitions for all tables would be kept in a single file. It can be
-			expected that this file needs to be changed very often and thus can be
-			a bottleneck for team development when it is nearly steadily checked
-			out. It would be much better if each developer had an associated file
-			with table definitions and all these information could be linked together
-			at the end.
-		</p>
-		<p>
-			<code>ConfigurationFactory</code> provides support for such a use case,
-			too. It is possible to specify in the configuration definition file that
-			from a set of configuration sources a logic union configuration is to be
-			constructed. Then all properties defined in the provided sources are
-			collected and can be accessed as if they had been defined in a single
-			source. To demonstrate this feature let us assume that a developer of
-			the database application has defined a specific XML file with a table
-			definition named <code>tasktables.xml</code>:
-		</p>
-   		<source><![CDATA[
-<?xml version="1.0" encoding="ISO-8859-1" ?>
-
-<config>
-  <table tableType="application">
-    <name>tasks</name>
-    <fields>
-      <field>
-        <name>taskid</name>
-        <type>long</type>
-      </field>
-      <field>
-        <name>name</name>
-        <type>java.lang.String</type>
-      </field>
-      <field>
-        <name>description</name>
-        <type>java.lang.String</type>
-      </field>
-      <field>
-        <name>responsibleID</name>
-        <type>long</type>
-      </field>
-      <field>
-        <name>creatorID</name>
-        <type>long</type>
-      </field>
-      <field>
-        <name>startDate</name>
-        <type>java.util.Date</type>
-      </field>
-      <field>
-        <name>endDate</name>
-        <type>java.util.Date</type>
-      </field>
-    </fields>
-  </table>
-</config>
-]]></source>
-		<p>
-			This file defines the structure of an additional table, which should be
-			added to the so far existing table definitions. To achieve this the
-			configuration definition file has to be changed: A new section is added
-			that contains the include elements of all configuration sources which
-			are to be combined.
-		</p>
-		<source><![CDATA[
-<?xml version="1.0" encoding="ISO-8859-1" ?>
-<!-- Configuration definition file that demonstrates the
-     override and additional sections -->
-
-<configuration>
-  <override>
-    <properties fileName="usergui.properties"/>
-    <xml fileName="gui.xml"/>
-  </override>
-  
-  <additional>
-    <xml fileName="tables.xml"/>
-    <xml fileName="tasktables.xml" at="tables"/>
-  </additional>
-</configuration>
-]]></source>
-		<p>
-			Compared to the older versions of this file a couple of changes has been
-			done. One major difference is that the elements for including configuration
-			sources are no longer direct children of the root element, but are now
-			contained in either an <code>override</code> or <code>additional</code>
-			section. The names of these sections already imply their purpose.
-		</p>
-		<p>
-			The <code>override</code> section is not strictly necessary. Elements in
-			this section are treated as if they were children of the root element, i.e.
-			properties in the included configuration sources override properties in
-			sources included later. So the <code>override</code> tags could have
-			been ommitted, but for sake of clearity it is recommended to use them
-			when there is also an <code>additional</code> section.
-		</p>
-		<p>
-			It is the <code>additonal</code> section that introduces a new behaviour.
-			All configuration sources listed here are combined to a union configuration.
-			In our example we have put two <code>xml</code> elements in this area
-			that load the available files with database table definitions. The syntax
-			of elements in the <code>additional</code> section is analogous to the
-			syntax described so far. The only difference is an additionally supported
-			<code>at</code> attribute that specifies the position in the logic union
-			configuration where the included properties are to be added. In this
-			example we set the <code>at</code> attribute of the second element to
-			<em>tables</em>. This is because the file starts with a <code>table</code>
-			element, but to be compatible with the other table definition file it should be
-			accessable under the key <code>tables.table</code>.
-		</p>
-		<p>
-			After these modifications have been performed the configuration obtained
-			from the <code>ConfigurationFactory</code> will allow access to three
-			database tables. A call of <code>config.getString("tables.table(2).name");</code>
-			will result in a value of <em>tasks</em>. In an analogous way it is possible
-			to retrieve the fields of the third table.
-		</p>
-		<p>
-			Note that it is also possible to override properties defined in an
-			<code>additonal</code> section. This can be done by placing a
-			configuration source in the <code>override</code> section that defines
-			properties that are also defined in one of the sources listed in the
-			<code>additional</code> section. The example does not make use of that.
-			Note also that the order of the <code>override</code> and
-			<code>additional</code> sections in a configuration definition file does
-			not matter. Sources in an <code>override</code> section are always treated with
-			higher priority (otherwise they could not override the values of other
-			sources).
-		</p>
-	</section>
-    
-    <section name="The configuration definition file">
-        <p>
-            We have seen how to write configuration definition files for
-            including properties and XML files. This section deals with other
-            options that can be specified in such a definition file and that
-            are evaluated by <code>ConfigurationFactory</code>.
-        </p>
-        <p>
-            From time to time the question is raised whether there is a
-            document type definition that exactly defines the structure of a
-            configuration definition file. Frankly, the answer is no. This is
-            because for a future version of Commons Configuration it is planed
-            to make the configuration definition files extensible, i.e. allow
-            developers to register their own tags and corresponding implementations
-            of the Configuration interface.
-        </p>
-        <p>
-            In the current version the set of supported XML elements is fixed.
-            Below is a list of all supported tags and a description of each:
-        </p>
-        <p>
-            <dl>
-                <dt>properties</dt>
-                <dd>
-                With this element properties files can be included. The name of
-                the file to load is specified using the <code>fileName</code>
-                attribute. Which configuration class is created by this tag
-                depends on the extension of the file to load: If the extension
-                is ".xml", a <code>XMLPropertiesConfiguration</code> object is
-                created, which is able to process the XML properties format
-                introduced in Java 5.0. Otherwise a <code>PropertiesConfiguration</code>
-                object is created, the default reader for properties files.
-                </dd>
-                <dt>xml</dt>
-                <dd>
-                The <code>xml</code> element can be used to load XML configuration
-                files. It also uses the <code>fileName</code> attribute to
-                determine the name of the file to load and creates an instance
-                of <code>XMLConfiguration</code>.
-                </dd>
-                <dt>jndi</dt>
-                <dd>
-                As the name implies, with this element JNDI resources can be
-                included in the resulting configuration. Under the hood this is
-                done by an instance of the <code>JNDIConfiguration</code>
-                class. The <code>prefix</code> attribute can be used to
-                select a subset of the JNDI tree.
-                </dd>
-                <dt>plist</dt>
-                <dd>
-                The <code>plist</code> element allows to embedd configuration
-                files in the NeXT / OpenStep or Mac OS X format. Again the
-                name of the file to load is specified through the
-                <code>fileName</code> attribute. If a XML file is specified,
-                a <code>XMLPropertyListConfiguration</code> object is created
-                to process the file. Otherwise this task is delegated to a
-                <code>PropertyListConfiguration</code> instance.
-                </dd>
-                <dt>system</dt>
-                <dd>
-                With this element an instance of <code>SystemConfiguration</code>
-                is added to the resulting configuration allowing access to
-                system properties.
-                </dd>
-            </dl>
-        </p>
-        <p>
-            All of these elements can occur in a configuration definition file
-            in arbitrary number and order. The following listing shows an
-            example file using many of these tags.
-        </p>
-		<source><![CDATA[
-<?xml version="1.0" encoding="ISO-8859-1" ?>
-
-<configuration>
-  <system/>
-  <jndi prefix="java:comp/env"/>
-  <properties fileName="test.properties"/>
-  <xml fileName="test.xml"/>
-  <properties fileName="test.properties.xml"/>
-</configuration>
-]]></source>
-
-    <subsection name="Setting further options">
-        <p>
-            Many specialized configuration classes support initialization
-            properties that influence the behavior of their instances. For
-            example for file based configurations the encoding of the files
-            to load can be specified using the <code>setEncoding()</code>
-            method, or an <code>XMLConfiguration</code> can be told to
-            perform validation by calling the <code>setValidating()</code>
-            method. How can such properties be set in a configuration definition
-            file?
-        </p>
-        <p>
-            Fortunately this is easy possible. For each XML element in a
-            configuration definition file additional attributes can be
-            specified that correspond to (bean) setter methods defined in the
-            associated configuration class. To derive the name of an attribute
-            from a setter method to be called, just drop the prefix "set" and
-            make the first letter lower case. So for instance the attribute
-            that invokes the <code>setEncoding()</code> method would be
-            <code>encoding</code>. The following example shows how a XML
-            document with a certain encoding and enabled validation can be
-            loaded:
-        </p>
-		<source><![CDATA[
-<?xml version="1.0" encoding="ISO-8859-1" ?>
-
-<configuration>
-  <xml fileName="test.xml" encoding="UTF-8" validating="true"/>
-</configuration>
-]]></source>
-        <p>
-          Using this mechanism many properties of configuration classes can
-          be set when they are used together with <code>ConfigurationFactory</code>.
-          To find out, which attributes are supported by a specific XML
-          element, refer to the list in the previous section that explains,
-          which configuration classes are used for which tags. In the JavaDoc
-          of the corresponding class you can find the setter methods you can
-          address by attributes.
-        </p>
-    </subsection>
-    </section>
-</body>
-
+<?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 Factory Howto</title>
+  <author email="oliver.heger@t-online.de">Oliver Heger</author>
+ </properties>
+
+<body>		
+	<section name="Using a Configuration Factory">
+		<p>
+ 	 		This section explains how a
+    		<code>ConfigurationFactory</code> object is setup that provides access
+    		to a collection of different configuration sources.
+    	</p>
+    		
+		<subsection name="The configuration definition file">
+			<p>
+				When a single configuration file (e.g. a properties file) is the only
+				source of configuration data it is very simple to
+				load it using the specific configuration class that deals with
+                the corresponding format (e.g. <code>PropertiesConfiguration</code>
+                for properties files or <code>XMLConfiguration</code> for XML files). But because
+				we think that later other sources will be added (otherwise
+				this example section would be too silly) we will use a
+				<code>ConfigurationFactory</code> object to load it.
+			</p>
+			<p>
+				<code>ConfigurationFactory</code> allows to combine
+				multiple configuration sources. The properties defined in these
+				sources can then be accessed as if they were defined in a
+				single configuration file. To make use of this we have to
+				create a XML file which tells the factory from which sources
+				the properties are to be collected. The following listing shows
+				the content of this file:
+			</p>
+   			<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<configuration>
+  <properties fileName="usergui.properties"/>
+</configuration>
+]]></source>
+			<p>
+				Definition files for <code>ConfigurationFactory</code> are
+				normal XML files. The root element must be named
+				<code>configuration</code>. It can contain different sub
+				elements that specify the configuration sources to load. The
+				<code>properties</code> element is one of these; it is used to
+				include properties files.
+			</p>
+			<p>
+				For this example we store the definition file for
+				<code>ConfigurationFactory</code> in the same directory as the
+				properties file and call it <code>config.xml</code>. The
+                properties file used in this example is the same as in the
+                section about <a href="howto_properties.html">properties
+                files</a>.
+			</p>
+		</subsection>
+		<subsection name="Setting up a ConfigurationFactory">
+			<p>
+				Now we have to create a <code>ConfigurationFactory</code>
+				object and let it read this definition file. This is quite simple:
+				Just create a new instance and set the name of the definition
+				file with the <code>setConfigurationFileName()</code> method.
+			</p>
+    			<source><![CDATA[
+ConfigurationFactory factory = new ConfigurationFactory();
+URL configURL = new File("config.xml").toURL();
+factory.setConfigurationFileName(configURL.toString());
+Configuration config = factory.getConfiguration();
+]]></source>
+			<p>
+				As this code fragment shows the file name passed to the factory
+				can be a full URL. This is also the recommended way of
+				specifying the file because it provides the greatest flexibility
+				and a consistent way of handling relative file names found in
+				the definition file.
+			</p>
+			<p>
+				Here we assumed the configuration definition file to be located
+				in the current directory. It is also possible (and probably a
+				better approach) to load the file from the class path. This
+				could be done as follows:
+			</p>
+   			<source><![CDATA[
+ConfigurationFactory factory = new ConfigurationFactory();
+URL configURL = getClass().getResource("/config.xml");
+factory.setConfigurationURL(configURL);
+Configuration config = factory.getConfiguration();
+]]></source>
+    	</subsection>
+    	<subsection name="Accessing properties">
+    		<p>
+    			Whatever way we used to load the configuration factory, we
+    			should now have a <code>Configuration</code> object that was
+    			returned by the factory's <code>getConfiguration()</code>
+    			method. This object is actually an instance of the
+                <code>CompositeConfiguration</code> class, a specific implementation
+                of the <code>Configuration</code> interface that is able to
+                deal with multiple contained configuration objects. Of course
+                this class provides all the getter methods defined in the
+                <code>Configuration</code> interface, so for accessing a
+                string property for instance we	would use the <code>getString()</code> method:
+    		</p>
+   			<source><![CDATA[
+String backColor = config.getString("color.background");
+]]></source>
+    	</subsection>
+	</section>
+	
+	<section name="Multiple configuration sources">
+		<p>
+			Using <code>ConfigurationFactory</code> to collect configuration
+			sources does not make much sense if there is only one source to be
+			loaded. So let's add another one! This time we will embedd a XML file.
+		</p>
+		<subsection name="Overriding properties">
+			<p>
+				Many applications use the popular XML format for storing
+				configuration information. So it is no wonder that Configuration
+				also supports this type of configuration sources. In general
+				each XML document can be used to define configuration settings.
+				We start here with a rather simple one:
+			</p>
+   			<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<gui-definition>
+  <colors>
+    <background>#808080</background>
+    <text>#000000</text>
+    <header>#008000</header>
+    <link normal="#000080" visited="#800080"/>
+  </colors>
+  <rowsPerPage>15</rowsPerPage>
+</gui-definition>
+]]></source>
+			<p>
+				To make this XML document part of our global configuration we
+				have to modify our configuration definition file to also include
+				the new file. For XML documents the element <code>xml</code>
+				can be used so that we have now:
+			</p>
+   			<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<configuration>
+  <properties fileName="usergui.properties"/>
+  <xml fileName="gui.xml"/>
+</configuration>
+]]></source>
+			<p>
+				The code for setting up the <code>ConfigurationFactory</code>
+				object remains the same. From the <code>Configuration</code>
+                object returned by the factory the new properties can be
+                accessed in the usual way.
+			</p>
+			<p>
+				There is one problem with this example configuration setup:
+				The <code>color.background</code> property
+				is defined in both the properties and the XML file, and -
+				to make things worse - with different values. Which value will
+				be returned by a call to <code>getString()</code>?
+			</p>
+			<p>
+				The answer is that the configuration sources are searched in the
+				order they are defined in the configuration definition file.
+				Here the properties file is included first, then comes the XML
+				file. Because the <code>color.background</code> property can
+				be found in the properties file the value specified there will
+				be returned (which happens to be <code>#FFFFFF</code>).
+			</p>
+			<p>
+				It might not be obvious why it makes sense to define the value
+				of one and the same property in multiple configuration sources.
+				But consider the following scenario: An application comes with
+				a set of default properties and allows the user to override some
+				or all of them. This can now easy be realized by saving the
+				user's settings in a file and the default settings in another.
+				Then in the configuration definition file the file with the
+				user settings is included first and after that the file with the
+				default values. The application code that queries these
+				settings need not be aware whether a property was overriden by
+				the user. The <code>ConfigurationFactory</code> takes care
+				that properties defined in the first file (the user file) are
+				found; other properties which the user has not changed will
+				still be returned from the second file (the defaults file).
+			</p>
+		</subsection>
+		<subsection name="Optional configuration sources">
+			<p>
+				The example above with two configuration sources - one for user
+				settings and one with default values - raises an interesting
+				question: What will happen if the user has not defined specific
+				properties yet? Or what if a new user starts our application for
+				the first time and thus no user specific properties exist?
+			</p>
+			<p>
+				The default behavior of <code>ConfigurationFactory</code> is to
+				throw a <code>ConfigurationException</code> exception if one of
+				the sources defined in the configuration definition file cannot
+				be loaded. For our example this behavior is not desired: the
+				properties file with specific user settings is not required. If it
+				cannot be loaded, the example application will still work because
+				a complete set of configuration properties is defined in the
+				second file.
+			</p>
+			<p>
+				<code>ConfigurationFactory</code> supports such optional
+				configuration sources. For this purpose in the definition of a
+				(file based) configuration source the <code>optional</code>
+				attribute can be placed. An example of this is shown below:
+			</p>
+   			<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<configuration>
+  <properties fileName="usersettings.properties" optional="true"/>
+  <properties fileName="default.properties"/>
+</configuration>
+]]></source>
+			<p>
+				In this configuration definition file the first properties file
+				with user specific settings is marked as optional. This means that
+				if it cannot be loaded, <code>ConfigurationFactory</code> will
+				not throw an exception, but only write a warning message to its
+				logger. Note that the <code>optional</code> attribute is absent
+				for the second properties file. Thus it is mandatory, and the
+				<code>getConfiguration()</code> method of
+				<code>ConfigurationFactory</code> would throw an exception if it
+				could not be found.
+			</p>
+		</subsection>
+	</section>
+
+	<section name="Union configuration">
+		<p>
+			In an earlier section about the configuration definition file for
+			<code>ConfigurationFactory</code> it was stated that configuration
+			files included first can override properties in configuraton files
+			included later and an example use case for this behaviour was given.
+			There may be times when there are other requirements.
+		</p>
+		<p>
+			Let's continue the example with the application that somehow process
+			database tables and that reads the definitions of the affected tables from
+			its configuration. This example and the corresponding XML configuration
+            files were introduced in the section about <a href="howto_xml.html">XMLConfiguration</a>.
+            Now consider that this application grows larger and
+			must be maintained by a team of developers. Each developer works on
+			a separated set of tables. In such a scenario it would be problematic
+			if the definitions for all tables would be kept in a single file. It can be
+			expected that this file needs to be changed very often and thus can be
+			a bottleneck for team development when it is nearly steadily checked
+			out. It would be much better if each developer had an associated file
+			with table definitions and all these information could be linked together
+			at the end.
+		</p>
+		<p>
+			<code>ConfigurationFactory</code> provides support for such a use case,
+			too. It is possible to specify in the configuration definition file that
+			from a set of configuration sources a logic union configuration is to be
+			constructed. Then all properties defined in the provided sources are
+			collected and can be accessed as if they had been defined in a single
+			source. To demonstrate this feature let us assume that a developer of
+			the database application has defined a specific XML file with a table
+			definition named <code>tasktables.xml</code>:
+		</p>
+   		<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<config>
+  <table tableType="application">
+    <name>tasks</name>
+    <fields>
+      <field>
+        <name>taskid</name>
+        <type>long</type>
+      </field>
+      <field>
+        <name>name</name>
+        <type>java.lang.String</type>
+      </field>
+      <field>
+        <name>description</name>
+        <type>java.lang.String</type>
+      </field>
+      <field>
+        <name>responsibleID</name>
+        <type>long</type>
+      </field>
+      <field>
+        <name>creatorID</name>
+        <type>long</type>
+      </field>
+      <field>
+        <name>startDate</name>
+        <type>java.util.Date</type>
+      </field>
+      <field>
+        <name>endDate</name>
+        <type>java.util.Date</type>
+      </field>
+    </fields>
+  </table>
+</config>
+]]></source>
+		<p>
+			This file defines the structure of an additional table, which should be
+			added to the so far existing table definitions. To achieve this the
+			configuration definition file has to be changed: A new section is added
+			that contains the include elements of all configuration sources which
+			are to be combined.
+		</p>
+		<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<!-- Configuration definition file that demonstrates the
+     override and additional sections -->
+
+<configuration>
+  <override>
+    <properties fileName="usergui.properties"/>
+    <xml fileName="gui.xml"/>
+  </override>
+  
+  <additional>
+    <xml fileName="tables.xml"/>
+    <xml fileName="tasktables.xml" at="tables"/>
+  </additional>
+</configuration>
+]]></source>
+		<p>
+			Compared to the older versions of this file a couple of changes has been
+			done. One major difference is that the elements for including configuration
+			sources are no longer direct children of the root element, but are now
+			contained in either an <code>override</code> or <code>additional</code>
+			section. The names of these sections already imply their purpose.
+		</p>
+		<p>
+			The <code>override</code> section is not strictly necessary. Elements in
+			this section are treated as if they were children of the root element, i.e.
+			properties in the included configuration sources override properties in
+			sources included later. So the <code>override</code> tags could have
+			been ommitted, but for sake of clearity it is recommended to use them
+			when there is also an <code>additional</code> section.
+		</p>
+		<p>
+			It is the <code>additonal</code> section that introduces a new behaviour.
+			All configuration sources listed here are combined to a union configuration.
+			In our example we have put two <code>xml</code> elements in this area
+			that load the available files with database table definitions. The syntax
+			of elements in the <code>additional</code> section is analogous to the
+			syntax described so far. The only difference is an additionally supported
+			<code>at</code> attribute that specifies the position in the logic union
+			configuration where the included properties are to be added. In this
+			example we set the <code>at</code> attribute of the second element to
+			<em>tables</em>. This is because the file starts with a <code>table</code>
+			element, but to be compatible with the other table definition file it should be
+			accessable under the key <code>tables.table</code>.
+		</p>
+		<p>
+			After these modifications have been performed the configuration obtained
+			from the <code>ConfigurationFactory</code> will allow access to three
+			database tables. A call of <code>config.getString("tables.table(2).name");</code>
+			will result in a value of <em>tasks</em>. In an analogous way it is possible
+			to retrieve the fields of the third table.
+		</p>
+		<p>
+			Note that it is also possible to override properties defined in an
+			<code>additonal</code> section. This can be done by placing a
+			configuration source in the <code>override</code> section that defines
+			properties that are also defined in one of the sources listed in the
+			<code>additional</code> section. The example does not make use of that.
+			Note also that the order of the <code>override</code> and
+			<code>additional</code> sections in a configuration definition file does
+			not matter. Sources in an <code>override</code> section are always treated with
+			higher priority (otherwise they could not override the values of other
+			sources).
+		</p>
+	</section>
+    
+    <section name="The configuration definition file">
+        <p>
+            We have seen how to write configuration definition files for
+            including properties and XML files. This section deals with other
+            options that can be specified in such a definition file and that
+            are evaluated by <code>ConfigurationFactory</code>.
+        </p>
+        <p>
+            From time to time the question is raised whether there is a
+            document type definition that exactly defines the structure of a
+            configuration definition file. Frankly, the answer is no. This is
+            because for a future version of Commons Configuration it is planed
+            to make the configuration definition files extensible, i.e. allow
+            developers to register their own tags and corresponding implementations
+            of the Configuration interface.
+        </p>
+        <p>
+            In the current version the set of supported XML elements is fixed.
+            Below is a list of all supported tags and a description of each:
+        </p>
+        <p>
+            <dl>
+                <dt>properties</dt>
+                <dd>
+                With this element properties files can be included. The name of
+                the file to load is specified using the <code>fileName</code>
+                attribute. Which configuration class is created by this tag
+                depends on the extension of the file to load: If the extension
+                is ".xml", a <code>XMLPropertiesConfiguration</code> object is
+                created, which is able to process the XML properties format
+                introduced in Java 5.0. Otherwise a <code>PropertiesConfiguration</code>
+                object is created, the default reader for properties files.
+                </dd>
+                <dt>xml</dt>
+                <dd>
+                The <code>xml</code> element can be used to load XML configuration
+                files. It also uses the <code>fileName</code> attribute to
+                determine the name of the file to load and creates an instance
+                of <code>XMLConfiguration</code>.
+                </dd>
+                <dt>jndi</dt>
+                <dd>
+                As the name implies, with this element JNDI resources can be
+                included in the resulting configuration. Under the hood this is
+                done by an instance of the <code>JNDIConfiguration</code>
+                class. The <code>prefix</code> attribute can be used to
+                select a subset of the JNDI tree.
+                </dd>
+                <dt>plist</dt>
+                <dd>
+                The <code>plist</code> element allows to embedd configuration
+                files in the NeXT / OpenStep or Mac OS X format. Again the
+                name of the file to load is specified through the
+                <code>fileName</code> attribute. If a XML file is specified,
+                a <code>XMLPropertyListConfiguration</code> object is created
+                to process the file. Otherwise this task is delegated to a
+                <code>PropertyListConfiguration</code> instance.
+                </dd>
+                <dt>system</dt>
+                <dd>
+                With this element an instance of <code>SystemConfiguration</code>
+                is added to the resulting configuration allowing access to
+                system properties.
+                </dd>
+            </dl>
+        </p>
+        <p>
+            All of these elements can occur in a configuration definition file
+            in arbitrary number and order. The following listing shows an
+            example file using many of these tags.
+        </p>
+		<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<configuration>
+  <system/>
+  <jndi prefix="java:comp/env"/>
+  <properties fileName="test.properties"/>
+  <xml fileName="test.xml"/>
+  <properties fileName="test.properties.xml"/>
+</configuration>
+]]></source>
+
+    <subsection name="Setting further options">
+        <p>
+            Many specialized configuration classes support initialization
+            properties that influence the behavior of their instances. For
+            example for file based configurations the encoding of the files
+            to load can be specified using the <code>setEncoding()</code>
+            method, or an <code>XMLConfiguration</code> can be told to
+            perform validation by calling the <code>setValidating()</code>
+            method. How can such properties be set in a configuration definition
+            file?
+        </p>
+        <p>
+            Fortunately this is easy possible. For each XML element in a
+            configuration definition file additional attributes can be
+            specified that correspond to (bean) setter methods defined in the
+            associated configuration class. To derive the name of an attribute
+            from a setter method to be called, just drop the prefix "set" and
+            make the first letter lower case. So for instance the attribute
+            that invokes the <code>setEncoding()</code> method would be
+            <code>encoding</code>. The following example shows how a XML
+            document with a certain encoding and enabled validation can be
+            loaded:
+        </p>
+		<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<configuration>
+  <xml fileName="test.xml" encoding="UTF-8" validating="true"/>
+</configuration>
+]]></source>
+        <p>
+          Using this mechanism many properties of configuration classes can
+          be set when they are used together with <code>ConfigurationFactory</code>.
+          To find out, which attributes are supported by a specific XML
+          element, refer to the list in the previous section that explains,
+          which configuration classes are used for which tags. In the JavaDoc
+          of the corresponding class you can find the setter methods you can
+          address by attributes.
+        </p>
+    </subsection>
+    </section>
+</body>
+
 </document>
\ No newline at end of file

Propchange: commons/proper/configuration/trunk/src/site/xdoc/userguide-1.2/howto_configurationfactory.xml
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message