Configuration Builder Howto

- This section explains how a - - DefaultConfigurationBuilderobject is setup that provides - access to a collection of different configuration sources. - DefaultConfigurationBuilder is the option of choice for + While simple applications often store their configuration data in a + single configuration file, there may be advanced requirements for more + complex systems. From a certain size of configuration data it surely + makes sense to divide the settings available on a set of configuration + files each of which is related to a specific sub-domain. This makes it + easier for users or administrators to adapt specific configuration + settings. However, rather than reading multiple files and dealing with + multiple Configuration objects, an application propably + prefers a combined view on its configuration data. Commons + Configuration supports this use case with a special configuration + builder implementation: + + CombinedConfigurationBuilder. +

+ CombinedConfigurationBuilder is the option of choice for applications that have to deal with multiple configuration sources. It provides the following features:

Various configuration sources can be combined to a single - + CombinedConfiguration object. This is a truly hierarchical configuration supporting enhanced query facilities.
As configuration sources the most relevant Configuration implementations provided by this library are supported. Sources are - defined as bean + defined as bean declarations, so complex initializations are possible.
Meta data can be provided to fine-tune the constructed configuration.
DefaultConfigurationBuilder is extensible. Custom +
CombinedConfigurationBuilder is extensible. Custom configuration sources can be added.

This document starts with some explanations of - DefaultConfigurationBuilder basics. Then the configuration - definition files processed by DefaultConfigurationBuilder + CombinedConfigurationBuilder basics. Then the configuration + definition files processed by CombinedConfigurationBuilder are discussed in detail. Finally an advanced example is presented.

@@ -60,16 +71,13 @@ In previous chapters we have already seen how specific configuration classes like PropertiesConfiguration or XMLConfiguration can be used to load configuration data from - a single source. This may be sufficient for small applications, but if - requirements for configuration become more complex, additional support - for managing a set of different configuration sources is desired. This is - the domain of DefaultConfigurationBuilder which allows - combining multiple configuration sources. The properties defined in these - sources can then be accessed as if they were defined in a single - configuration file. The sources to be loaded have to be defined in a - XML document with a specific structure, a so-called configuration - definition file. The following listing shows a simple example of such - a definition file: + a single source. CombinedConfigurationBuilder now allows + combining multiple configuration sources to a single +


+      CombinedConfiguration

object. The sources to be loaded have to + be defined in an XML document with a specific structure, a so-called + configuration definition file. The following listing shows a + simple example of such a definition file:

@@ -90,36 +98,99 @@

- +

- Now we have to create a DefaultConfigurationBuilder 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 - (DefaultConfigurationBuilder is derived from - XMLConfiguration, so all options for specifying the document - to load are available here, too). The combined configuration collecting + Now we have to create a CombinedConfigurationBuilder object + and let it read this definition file. This works in a similar way as + the construction of other typical + configuration builders: A new instance is created, and the + configure() method is called with initialization parameters + (CombinedConfigurationBuilder is derived from + + BasicConfigurationBuilder; so all features common to + configuration builders are available here as well). The combined configuration collecting all sources defined in the configuration definition file can then be - obtained by calling the getConfiguration() method: + obtained by calling the builder's getConfiguration() method. +

+ The easiest way to define the configuration definition file is to pass an + initialized parameters object for file-based configurations to the + builder. In this case, no other specific settings are set for the builder, + and the file is read as an XML document:

Now the config object can be accessed in the usual way to query configuration properties, e.g. by using methods like getString(), - or getInt(). We will see in a moment how properties defined - in different configuration sources are accessed. + or getInt(). Just defining the configuration definition file + via a file-based parameters object is a special case. Internally, a builder + for an XMLConfiguration object is constructed which is then + used to load and interprete the definition file. This should be appropriate + for many cases. A drawback of this method is that there is no way to set + additional initialization parameters for the + CombinedConfigurationBuilder. For this purpose, a special + parameters object exists offering some more specialized settings. If this + object is to be used, information about the file to be loaded can be + passed via the definitionBuilderParameters property: +

+ +

+ In this example, the combined() method of + + Parameters is used to obtain a special parameters object for a + combined configuration builder. Internally, again a builder for + constructing an XMLConfiguration for the definition file is + created. The object stored in the definitionBuilderParameters + property is passed to this builder's configure() method. +

+ It is even possible to construct the builder for the configuration + definition file externally and then pass it to the + CombinedConfigurationBuilder via the + definitionBuilder property of its initialization parameters + object: +

+ > defBuilder = ...; + +// Create the combined builder and pass it the definition builder +CombinedConfigurationBuilder builder = new CombinedConfigurationBuilder() + .configure(params.combined().setDefinitionBuilder(defBuilder)); +CombinedConfiguration config = builder.getConfiguration(); +]]> +

+ This is the most flexible variant. It makes it possible in theory to + read the definition for the combined configuration builder from a + completely different source. In practice, most applications will stick + to XML files defining a combined configuration source because this is + the native format for listing configuration sources and defining + additional meta data (as described in the following sections). But + making use of the definitionBuilder property allows at least + passing in a specially configured builder object.

- Using DefaultConfigurationBuilder to collect configuration + Using CombinedConfigurationBuilder to collect configuration sources does not make much sense if there is only a single source to be - loaded. So let's add another one! This time we will embedd a XML file: - gui.xml which is shown in the next listing: + loaded. So let's add another one to the example definition file used + before! This time we will embedd a XML file: gui.xml which is + shown in the next listing:

@@ -134,10 +205,10 @@ Configuration config = builder.getConfig ]]>

- To make this XML document part of our global configuration we have to + 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 <xml> can be used so that we - ave now: + have now:

@@ -148,13 +219,13 @@ Configuration config = builder.getConfig ]]>

- The code for setting up the DefaultConfigurationBuilder + The code for setting up the CombinedConfigurationBuilder object remains the same. From the Configuration object returned by the factory the new properties can be accessed in the usual way.

- There is one problem with this example configuration setup: The + There is one open question with this example configuration setup: The color.background 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 getString()? @@ -175,8 +246,8 @@ Configuration config = builder.getConfig be realized by saving the user's settings in one 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 needs no - be aware whether a property was overriden by the user. DefaultConfigurationBuilder + default values. The application code that queries these settings does not + have to bother whether a property was overriden by the user. CombinedConfigurationBuilder 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). @@ -192,7 +263,7 @@ Configuration config = builder.getConfig properties exist?

- The default behavior of DefaultConfigurationBuilder is to + The default behavior of CombinedConfigurationBuilder is to throw a ConfigurationException 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 @@ -201,7 +272,7 @@ Configuration config = builder.getConfig defined in the second file.

- DefaultConfigurationBuilder supports such optional configuration + CombinedConfigurationBuilder supports such optional configuration sources. For this purpose in the definition of a configuration source the config-optional attribute can be placed. An example of this is shown below: @@ -217,19 +288,49 @@ Configuration config = builder.getConfig

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, DefaultConfigurationBuilder will not throw an exception, + loaded, CombinedConfigurationBuilder will not throw an exception, but only write a warning message to its logger. Note that the config-optional attribute is absent for the second properties file. Thus it is mandatory, and the getConfiguration() method - of DefaultConfigurationBuilder would throw an exception if it + of CombinedConfigurationBuilder would throw an exception if it could not be found.

+ A configuration source with the config-optional attribute + that cannot be loaded is simply ignored; in the resulting combined + configuration no reference for this source is stored. In the example + with the user configuration, it would be good if in case of a failure + (because the user configuration file does not yet exist) an empty + configuration object is created and added to the combined configuration. + This configuration object can then be used to store specific user + settings which the user might define. +

+ For configuration sources marked as optional, an additional attribute is + supported providing exactly this functionality: config-forceCreate. + If set to true, a configuration is created in any case + for this source. If the source can be loaded successfully, this is of + course the resulting configuration. Otherwise, an empty configuration + (of the same type) is created. The example below shows how this attribute + can be used. Here we also define a name for the configuration source, so + that the produced configuration can later be retrieved from the resulting + combined configuration. +

+ + + + + + +]]>

In an earlier section about the configuration definition file for - DefaultConfigurationBuilder it was stated that configuration + CombinedConfigurationBuilder 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 cases when there are other requirements. @@ -238,18 +339,19 @@ Configuration config = builder.getConfig 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 XMLConfiguration. + files were introduced in the section about + hierarchical configurations. 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 + tables were 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 + if each developer had an associated file with table definitions, and all these information could be linked together at the end.

- DefaultConfigurationBuilder provides support for such a use case, + CombinedConfigurationBuilder 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 @@ -301,7 +403,7 @@ Configuration config = builder.getConfig 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 + that contains the declaring elements of all configuration sources which are to be combined.

After these modifications have been performed, the configuration obtained - from DefaultConfigurationBuilder allows access to three database + from CombinedConfigurationBuilder allows access to three database tables. A call of config.getString("tables.table(2).name"); results in a value of tasks. In an analogous way it is possible to retrieve the fields of the third table. Modified: commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml?rev=1604002&r1=1604001&r2=1604002&view=diff ============================================================================== --- commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml (original) +++ commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml Thu Jun 19 18:57:30 2014 @@ -134,10 +134,10 @@

Constructor arguments

Extending the Basic Mechanism

Using DefaultConfigurationBuilder

Combining Configuration Sources