Return-Path: X-Original-To: apmail-commons-commits-archive@minotaur.apache.org Delivered-To: apmail-commons-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 492A0112DB for ; Thu, 19 Jun 2014 18:58:16 +0000 (UTC) Received: (qmail 69445 invoked by uid 500); 19 Jun 2014 18:58:15 -0000 Delivered-To: apmail-commons-commits-archive@commons.apache.org Received: (qmail 69379 invoked by uid 500); 19 Jun 2014 18:58:15 -0000 Mailing-List: contact commits-help@commons.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@commons.apache.org Delivered-To: mailing list commits@commons.apache.org Received: (qmail 69370 invoked by uid 99); 19 Jun 2014 18:58:15 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 19 Jun 2014 18:58:15 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 19 Jun 2014 18:58:14 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id 97FEA23889F7; Thu, 19 Jun 2014 18:57:49 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1604003 - /commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_configurationbuilder.xml Date: Thu, 19 Jun 2014 18:57:49 -0000 To: commits@commons.apache.org From: oheger@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20140619185749.97FEA23889F7@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: oheger Date: Thu Jun 19 18:57:49 2014 New Revision: 1604003 URL: http://svn.apache.org/r1604003 Log: Reworked section about the definition file reference. Modified: commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_configurationbuilder.xml Modified: commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_configurationbuilder.xml URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_configurationbuilder.xml?rev=1604003&r1=1604002&r2=1604003&view=diff ============================================================================== --- commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_configurationbuilder.xml (original) +++ commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_configurationbuilder.xml Thu Jun 19 18:57:49 2014 @@ -475,7 +475,7 @@ CombinedConfiguration config = builder.g

Configuration definition files are XML documents telling - DefaultConfigurationBuilder which configuration sources to + CombinedConfigurationBuilder which configuration sources to load and how to process them in order to create the resulting combined configuration.

@@ -483,7 +483,7 @@ CombinedConfiguration config = builder.g Overall structure of a configuration definition file

- A configuration definition file for DefaultConfigurationBuilder + A configuration definition file for CombinedConfigurationBuilder can contain three sections, all of which are optional. A skeleton looks as follows:

@@ -507,7 +507,7 @@ CombinedConfiguration config = builder.g

The override and additional sections have already - been introduced when the basics of DefaultConfigurationBuilder + been introduced when the basics of CombinedConfigurationBuilder were discussed. They contain declarations for the configuration sources to be embedded. For convenience reasons it is also possible to declare configuration sources outside these sections; they are then treated as if @@ -518,7 +518,7 @@ CombinedConfiguration config = builder.g element whose name determines the type of the configuration source. Attributes or nested elements can be used to provide additional configuration options for the sources to be included (e.g. a name of a - file to be loaded or a reloading strategy). Below is a list of all + file to be loaded or further flags). Below is a list of all tags which can be used out of the box:

@@ -528,50 +528,72 @@ CombinedConfiguration config = builder.g the file to load is specified using the fileName attribute. Which configuration class is created by this tag depends on the extension of the file to load: If the extension - is ".xml", a XMLPropertiesConfiguration object is + is ".xml", a + + XMLPropertiesConfiguration object is created, which is able to process the XML properties format - introduced in Java 5.0. Otherwise a PropertiesConfiguration - object is created, the default reader for properties files. + introduced in Java 5.0. Otherwise a + + PropertiesConfiguration object is created, the default reader + for properties files.

xml
The xml element can be used to load XML configuration files. It also uses the fileName attribute to determine the name of the file to load and creates an instance - of XMLConfiguration.
+ of + XMLConfiguration.
jndi
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 JNDIConfiguration - class. The prefix attribute can be used to - select a subset of the JNDI tree.
+ done by an instance of the + + JndiConfiguration class. The prefix attribute + can be used to select a subset of the JNDI tree.
plist
-
The plist element allows to embedd configuration +
The plist element allows embedding configuration files in the NeXT / OpenStep or Mac OS X format. Again the name of the file to load is specified through the fileName attribute. If a XML file is specified, - a XMLPropertyListConfiguration object is created - to process the file. Otherwise this task is delegated to a - PropertyListConfiguration instance.
+ a + XMLPropertyListConfiguration object is created + to process the file. Otherwise, this task is delegated to a + + PropertyListConfiguration instance.
system
-
With this element an instance of SystemConfiguration - is added to the resulting configuration allowing access to - system properties. Note: Using this element system properties - are directly made available. Alternatively the - interpolation features introduced in version 1.4 (see - +
With this element an instance of + + SystemConfiguration is added to the resulting configuration + allowing access to system properties. Note: Using this element + system properties are directly made available. Alternatively the + interpolation features (see Variable Interpolation for more details) can be used for referencing system properties.
+
ini
+
This tag can be used to include an ini file into the resulting + combined configuration. Behind the scenes an instance of + + INIConfiguration is used to load the ini file.
+
env
+
With this tag direct access to environment properties can be enabled. + This works in the same way as the <system> tag for + Java system properties.
+
multFile
+
Using this tag, a builder for a multi-file configuration can be + integrated into the resulting combined configuration. This is described in a + later + chapter.
configuration
The configuration tag allows other configuration definition files to be included. This makes it possible to nest these definition files up to an arbitrary depth. In fact, this tag will - create another DefaultConfigurationBuilder object, + create another CombinedConfigurationBuilder object, initialize it, and obtain the CombinedConfiguation from it. This combined configuration will then be added to the resulting combined configuration. Like all file-based configurations the fileName attribute can be used to specify the configuration definition file to be loaded. This file must be an XML document that conforms to the format described here. Some of the most important - settings are copied from the original DefaultConfigurationBuilder + settings are copied from the original CombinedConfigurationBuilder object to the newly created builder:
  • the base path under which configuration files are searched
    • @@ -581,35 +603,24 @@ CombinedConfiguration config = builder.g
  • the configuration and error listeners
-
ini
-
This tag can be used to include an ini file into the resulting - combined configuration. Behind the scenes an instance of - - HierarchicalINIConfiguration is used to load the ini file.
-
env
-
With this tag direct access to environment properties can be enabled. - This works in the same way as the <system> tag for - Java system properties.

In the declaration of a configuration source it is possible to set properties on the corresponding configuration objects. Configuration declarations are indeed - Bean - declarations. That means they can have attributes matching simple + Bean declarations. That means they can have attributes matching simple properties of the configuration object to create, and sub elements matching complex properties. The following example fragment shows how complex initialization can be performed in a configuration declaration:

- + - - + + ]]>

@@ -617,19 +628,26 @@ CombinedConfiguration config = builder.g an XML document are defined. For the properties source the throwExceptionOnMissing property is set to true, which means that it should throw an exception if a requested property is - not found. In addition it is assigned a reloading strategy, which is + not found. In addition, it is assigned a custom reloading detector, which is declared and configured in a sub element. The XML configuration source is initialized in a similar way: a simple property is set, and an expression - engine is assigned. More information about the format for declaring objects - and initializing their properties can be found in the section about - bean - declarations. + engine is assigned. In fact, the properties defined in these declarations + are not directly set on configuration instances, but on + initialization + parameters objects for configuration builders. These builders are + created for the declared configuration sources and configured with the + defined properties. Then their managed configurations are obtained and + combined into the resulting configuration. Nevertheless, the declarations + share the same syntax as other bean declarations supported by + Commons Configuration. More information about the format for + declaring beans and initializing their properties can be found in the + section about bean declarations.

In addition to the attributes that correspond to properties of the - configuration object to be created, a configuration declaration can have a + configuration sources to be created, a configuration declaration can have a set of special attributes that are evaluated by - DefaultConfigurationBuilder when it creates the objects. + CombinedConfigurationBuilder when it creates the objects. These attributes are listed in the following table:

@@ -665,7 +683,7 @@ CombinedConfiguration config = builder.g config-forceCreate This boolean attribute is only evaluated for configurations declared as - optional. It determines the behavior of the configuration builder when + optional. It determines the behavior of the combined configuration builder when the optional configuration could not be created. If set to true, the builder tries to create an empty, uninitialized configuration of the correct type and add it to the resulting combined configuration. This is @@ -729,7 +747,7 @@ CombinedConfiguration config = builder.g ]]>

This example differs from the previous one by the systemProperties - attribute added to the root element. It causes the specified to be read + attribute added to the root element. It causes the specified properties file to be read and all properties defined therein to be added to the system properties. So properties like CONFIG_FILE can be defined in a properties file and are then treated as if they were system properties. @@ -742,13 +760,13 @@ CombinedConfiguration config = builder.g object can be set. The main part of this section is a bean declaration that is used for creating the resulting configuration object. Other elements can be used for customizing the - Node combiners + Node combiners used by the override and the union combined configuration. The following - example shows a header section that uses all supported properties: + example shows a header section that uses some of the supported properties:

- + @@ -780,14 +798,67 @@ CombinedConfiguration config = builder.g The combiner section allows nodes to be defined as list nodes. This can be necessary for certain node combiner implementations to work correctly. More information can be found in the section about - Node combiners. + Node combiners. +

+

+ There are some more tags for specific use cases which can occur in the + header section of a configuration declaration: +

+
providers
+
This tag can be used to define new tags for including custom + configuration sources. An example is provided later in this document.
+
fileSystem
+
Allows defining the File + System to be used for file-based configuration sources: + +
+ +
+ + +]]> +
+
lookups
+
In the sub section + Customizing + interpolation it was described how variable interpolation can be + extended by defining custom lookup objects. In the configuration + definition file of CombinedConfigurationBuilder it is + possible to declare such lookup objects and make them available for + the processing of this definition file and the resulting combined + configuration. For this purpose, the header section of the definition + file can contain a <lookup> element in which an + arbitrary number of lookups can be defined. Have a look at the + following example: + +
+ + + +
+ + + +]]> + Here a custom lookup class is declared and registered under the prefix + file (as defined by the config-prefix attribute). + The lookup is immediately active. It is then used to obtain the concrete + file name for the embedded XML configuration. Note that the variable + prefix matches the prefix provided in the lookup declaration. The + variable name is passed to the lookup object, and the custom implementation + can compute a suitable value.
+

Note: From time to time the question is raised whether there is a document type definition or a schema defining exactly the structure of a configuration definition file. Frankly, the answer is no. This is due to the fact that the format is extensible. As will be shown below, it is - possible to register yout own tags in order to embedd custom configuration + possible to register your own tags in order to embedd custom configuration sources.