Author: oheger
Date: Fri May 2 19:57:08 2014
New Revision: 1592019
URL: http://svn.apache.org/r1592019
Log:
Updated the overview section of the user guide.
Added information about immutable configurations, extended the description of
the methods of the Configuration interface. Re-ordered sections.
Modified:
commons/proper/configuration/trunk/src/site/xdoc/userguide/overview.xml
Modified:
commons/proper/configuration/trunk/src/site/xdoc/userguide/overview.xml
URL:
http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/site/xdoc/userguide/overview.xml?rev=1592019&r1=1592018&r2=1592019&view=diff
==============================================================================
--- commons/proper/configuration/trunk/src/site/xdoc/userguide/overview.xml
(original)
+++ commons/proper/configuration/trunk/src/site/xdoc/userguide/overview.xml Fri
May 2 19:57:08 2014
@@ -89,52 +89,6 @@
</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>
<subsection name="The Configuration interface">
<p>
@@ -145,7 +99,18 @@ Configuration config = factory.getConfig
in a generic way.
</p>
<p>
- A major part of the methods defined in the <code>Configuration</code>
+ The methods defined in the <code>Configuration</code> interface can be
+ divided into methods which query data from the configuration and
+ methods which alter the configuration object. In fact, the
+ <code>Configuration</code> interface extends a base interface called
+ <code><a
href="../apidocs/org/apache/commons/configuration/ImmutableConfiguration.html">
+ ImmutableConfiguration</a></code>. <code>ImmutableConfiguration</code>
+ defines all methods which read data from a configuration object without
+ changing its state. <code>Configuration</code> adds methods for
+ manipulating the configuration.
+ </p>
+ <p>
+ A major part of the methods defined in the
<code>ImmutableConfiguration</code>
interface deals with retrieving properties of different data types. All
these methods take a key as an argument that points to the desired
property. This is a string value whose exact meaning depends on the
@@ -154,7 +119,7 @@ Configuration config = factory.getConfig
target type; this converted value will be returned. There are also
overloaded variants of all methods that allow to specify a default
value,
which will be returned if the property cannot be found. The following
- data types are supported:
+ data types are supported out of the box:
<ul>
<li>BigDecimal</li>
<li>BigInteger</li>
@@ -169,9 +134,7 @@ Configuration config = factory.getConfig
</ul>
The names of these methods start with <code>get</code> followed by
their
data type. The <code>getString()</code> method for instance will return
- String values, <code>getInt()</code> will operate on integers. In
- addition, there is a generic <code>get()</code> method which tries to
- convert the value of a property to a specified target class.
+ String values, <code>getInt()</code> will operate on integers.
</p>
<p>
Properties can have multiple values, so it is also possible to query a
@@ -179,6 +142,22 @@ Configuration config = factory.getConfig
using the <code>getList()</code> or <code>getArray()</code> methods.
</p>
<p>
+ In addition, there are a couple of generic get methods which try to
+ convert the requested property value to a specified data type. Such
+ conversions are also supported for the elements of collections or
arrays.
+ More details about conversions can be found in the section
+ <a href="howto_basicfeatures.html#Data_type_conversions">
+ Data type conversions</a>.
+ </p>
+ <p>
+ The <code>subset()</code> method is useful if configuration settings
+ are organized in a specific structure and a module of an
+ application is only interested in a part of this structure.
+ <code>subset()</code> is passed a String with a key prefix and returns
+ a <code>Configuration</code> object that contains only the keys
starting
+ with this prefix.
+ </p>
+ <p>
For manipulating properties or their values the following methods can
be used:
<dl>
@@ -198,6 +177,73 @@ Configuration config = factory.getConfig
</p>
</subsection>
+ <subsection name="Immutable Configurations">
+ <p>
+ Most of the classes provided by the <em>Commons Configuration</em>
+ library implement the <code>Configuration</code> interface, i.e. they
+ allow client code to change their internal state. For some use cases,
+ this may not be desired. For instance, an application may want to
+ protect a central configuration object against uncontrolled
modifications
+ done by sub modules.
+ </p>
+ <p>
+ There is an easy way to convert a normal <code>Configuration</code>
+ object into an <code>ImmutableConfiguration</code>: just pass the
+ configuration in question to the
<code>unmodifiableConfiguration()</code>
+ method of the
+ <code><a
href="../apidocs/org/apache/commons/configuration/ConfigurationUtils.html">
+ ConfigurationUtils</a></code> utility class. This results in an
+ immutable configuration containing the same data as the original
+ configuration.
+ </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>
+
<subsection name="Threading issues">
<p>
The most concrete implementations of the <code>Configuration</code>
