src/site/xdoc/userguide/overview.xml - commons-configuration - Git at Google

 <?xml version="1.0"?>
 <!--
    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
 -->

 <document>
   <properties>
     <title>Configuration Overview</title>
     <author email="epugh@upstate.com">Eric Pugh</author>
     <author email="smanux@lfjr.net">Emmanuel Bourg</author>
   </properties>
   <body>

     <section name="Using Configuration">
       <p>
         Commons Configuration allows you to access configuration properties from
         a variety of different sources. No matter if they are stored in a properties file,
         a XML document, or a JNDI tree, they can all be accessed in the same way
         through the generic <code><a href="../apidocs/org/apache/commons/configuration2/Configuration.html">Configuration</a></code>
         interface.
       </p>
       <p>
         Another strength of Commons Configuration is its ability to mix configurations
         from heterogeneous sources and treat them like a single logic configuration.
         This section will introduce you to the different configurations
         available and will show you how to combine them.
       </p>

       <subsection name="Configuration Sources">
       <p>
         Currently there are quite a number of different sources of Configuration objects. But,
         by just using a Configuration object versus a specific type like XMLConfiguration or
         JNDIConfiguration, you are sheltered from the mechanics of actually retrieving the
         configuration values. These various sources include:
         <ul>
           <li>
               <strong>EnvironmentConfiguration</strong>
               Reads the plattform specific environment variables.
           </li>
           <li>
               <strong>PropertiesConfiguration</strong>
               Loads configuration values from a properties file.
           </li>
           <li>
               <strong>XMLConfiguration</strong>
               Takes values from an XML document.
           </li>
           <li>
               <strong>INIConfiguration</strong>
               Loads the values from a .ini file as used by Windows.
           </li>
           <li>
               <strong>PropertyListConfiguration</strong>
               Loads values from an OpenStep .plist file. XMLPropertyListConfiguration is also
               available to read the XML variant used by Mac OS X.
           </li>
           <li>
               <strong>JNDIConfiguration</strong>
               Using a key in the JNDI tree, can retrieve values as configuration properties.
           </li>
           <li>
               <strong>BaseConfiguration</strong>
               An in-memory method of populating a Configuration object.
           </li>
           <li>
               <strong>HierarchicalConfiguration</strong>
               An in-memory Configuration object that is able to deal with complex
               structured data.
           </li>
           <li>
               <strong>SystemConfiguration</strong>
               A configuration using the system properties
           </li>
           <li>
               <strong>ConfigurationConverter</strong>
               Takes a java.util.Properties or an org.apache.commons.collections.ExtendedProperties
               and converts it to a Configuration object.
           </li>
        </ul>

       </p>
       </subsection>

       <subsection name="The Configuration interface">
       <p>
         All the classes in this package that represent different kinds of configuration
         sources share a single interface:
         <code><a href="../apidocs/org/apache/commons/configuration2/Configuration.html">Configuration</a></code>.
         This interface allows you to access and manipulate configuration properties
         in a generic way.
       </p>
       <p>
         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/configuration2/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
         concrete <code>Configuration</code> implementation used. They try to
         find the property specified by the passed in key and convert it to their
         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 out of the box:
         <ul>
           <li>BigDecimal</li>
           <li>BigInteger</li>
           <li>boolean</li>
           <li>byte</li>
           <li>double</li>
           <li>float</li>
           <li>int</li>
           <li>long</li>
           <li>short</li>
           <li>String</li>
         </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.
       </p>
       <p>
         Properties can have multiple values, so it is also possible to query a
         list or an array containing all of the available values. This is done
         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>
           <dt><code>addProperty()</code></dt>
           <dd>Adds a new property to the configuration. If this property already
           exists, another value is added to it (so it becomes a multi-valued
           property).</dd>
           <dt><code>clearProperty()</code></dt>
           <dd>Removes the specified property from the configuration.</dd>
           <dt><code>setProperty()</code></dt>
           <dd>Overwrites the value of the specified property. This is the same
           as removing the property and then calling <code>addProperty()</code>
           with the new property value.</dd>
           <dt><code>clear()</code></dt>
           <dd>Wipes out the whole configuration</dd>
         </dl>
       </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/configuration2/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="Threading issues">
       <p>
         When accessing configurations from multiple threads - be it in a
         read-only or in a manipulating manner - the question arises whether
         <code>Configuration</code> implementations are thread-safe. When
         using immutable configurations as described in the previous section
         you are typically on the safe side because immutable objects can
         safely be shared between multiple threads. However, the
         <code>ImmutableConfiguration</code> objects created by
         <code>ConfigurationUtils</code> are just wrappers around a mutable
         <code>Configuration</code> object. So if code holds a reference to the
         underlying <code>Configuration</code>, it can still be changed.
       </p>
       <p>
         Because concurrency is a complex topic this user's guide contains a
         dedicated section to this topic: <a href="howto_concurrency.html">
         Configurations and Concurrent Access</a>.
       </p>
       </subsection>
     </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>Configuration Overview</title>
	<author email="epugh@upstate.com">Eric Pugh</author>
	<author email="smanux@lfjr.net">Emmanuel Bourg</author>
	</properties>
	<body>

	<section name="Using Configuration">
	<p>
	Commons Configuration allows you to access configuration properties from
	a variety of different sources. No matter if they are stored in a properties file,
	a XML document, or a JNDI tree, they can all be accessed in the same way
	through the generic <code><a href="../apidocs/org/apache/commons/configuration2/Configuration.html">Configuration</a></code>
	interface.
	</p>
	<p>
	Another strength of Commons Configuration is its ability to mix configurations
	from heterogeneous sources and treat them like a single logic configuration.
	This section will introduce you to the different configurations
	available and will show you how to combine them.
	</p>

	<subsection name="Configuration Sources">
	<p>
	Currently there are quite a number of different sources of Configuration objects. But,
	by just using a Configuration object versus a specific type like XMLConfiguration or
	JNDIConfiguration, you are sheltered from the mechanics of actually retrieving the
	configuration values. These various sources include:
	<ul>
	<li>
	<strong>EnvironmentConfiguration</strong>
	Reads the plattform specific environment variables.
	</li>
	<li>
	<strong>PropertiesConfiguration</strong>
	Loads configuration values from a properties file.
	</li>
	<li>
	<strong>XMLConfiguration</strong>
	Takes values from an XML document.
	</li>
	<li>
	<strong>INIConfiguration</strong>
	Loads the values from a .ini file as used by Windows.
	</li>
	<li>
	<strong>PropertyListConfiguration</strong>
	Loads values from an OpenStep .plist file. XMLPropertyListConfiguration is also
	available to read the XML variant used by Mac OS X.
	</li>
	<li>
	<strong>JNDIConfiguration</strong>
	Using a key in the JNDI tree, can retrieve values as configuration properties.
	</li>
	<li>
	<strong>BaseConfiguration</strong>
	An in-memory method of populating a Configuration object.
	</li>
	<li>
	<strong>HierarchicalConfiguration</strong>
	An in-memory Configuration object that is able to deal with complex
	structured data.
	</li>
	<li>
	<strong>SystemConfiguration</strong>
	A configuration using the system properties
	</li>
	<li>
	<strong>ConfigurationConverter</strong>
	Takes a java.util.Properties or an org.apache.commons.collections.ExtendedProperties
	and converts it to a Configuration object.
	</li>
	</ul>

	</p>
	</subsection>

	<subsection name="The Configuration interface">
	<p>
	All the classes in this package that represent different kinds of configuration
	sources share a single interface:
	<code><a href="../apidocs/org/apache/commons/configuration2/Configuration.html">Configuration</a></code>.
	This interface allows you to access and manipulate configuration properties
	in a generic way.
	</p>
	<p>
	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/configuration2/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
	concrete <code>Configuration</code> implementation used. They try to
	find the property specified by the passed in key and convert it to their
	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 out of the box:
	<ul>
	<li>BigDecimal</li>
	<li>BigInteger</li>
	<li>boolean</li>
	<li>byte</li>
	<li>double</li>
	<li>float</li>
	<li>int</li>
	<li>long</li>
	<li>short</li>
	<li>String</li>
	</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.
	</p>
	<p>
	Properties can have multiple values, so it is also possible to query a
	list or an array containing all of the available values. This is done
	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>
	<dt><code>addProperty()</code></dt>
	<dd>Adds a new property to the configuration. If this property already
	exists, another value is added to it (so it becomes a multi-valued
	property).</dd>
	<dt><code>clearProperty()</code></dt>
	<dd>Removes the specified property from the configuration.</dd>
	<dt><code>setProperty()</code></dt>
	<dd>Overwrites the value of the specified property. This is the same
	as removing the property and then calling <code>addProperty()</code>
	with the new property value.</dd>
	<dt><code>clear()</code></dt>
	<dd>Wipes out the whole configuration</dd>
	</dl>
	</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/configuration2/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="Threading issues">
	<p>
	When accessing configurations from multiple threads - be it in a
	read-only or in a manipulating manner - the question arises whether
	<code>Configuration</code> implementations are thread-safe. When
	using immutable configurations as described in the previous section
	you are typically on the safe side because immutable objects can
	safely be shared between multiple threads. However, the
	<code>ImmutableConfiguration</code> objects created by
	<code>ConfigurationUtils</code> are just wrappers around a mutable
	<code>Configuration</code> object. So if code holds a reference to the
	underlying <code>Configuration</code>, it can still be changed.
	</p>
	<p>
	Because concurrency is a complex topic this user's guide contains a
	dedicated section to this topic: <a href="howto_concurrency.html">
	Configurations and Concurrent Access</a>.
	</p>
	</subsection>
	</section>

	</body>
	</document>