commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ohe...@apache.org
Subject svn commit: r1592019 - /commons/proper/configuration/trunk/src/site/xdoc/userguide/overview.xml
Date Fri, 02 May 2014 19:57:08 GMT
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>



Mime
View raw message