public class CombinedConfigurationBuilder extends BasicConfigurationBuilder<CombinedConfiguration>
A specialized ConfigurationBuilder
implementation that creates a CombinedConfiguration
from multiple
configuration sources defined by an XML-based configuration definition file.
This class provides an easy and flexible means for loading multiple configuration sources and combining the results
into a single configuration object. The sources to be loaded are defined in an XML document that can contain certain
tags representing the different supported configuration classes. If such a tag is found, a corresponding
ConfigurationBuilder
class is instantiated and initialized using the classes of the beanutils
package
(namely XMLBeanDeclaration
will be used to
extract the configuration's initialization parameters, which allows for complex initialization scenarios).
It is also possible to add custom tags to the configuration definition file. For this purpose an implementation of
CombinedConfigurationBuilderProvider
has to be created which is responsible for the creation of a
ConfigurationBuilder
associated with the custom tag. An instance of this class has to be registered at the
CombinedBuilderParametersImpl
object which is used to initialize this CombinedConfigurationBuilder
.
This provider will then be called when the corresponding custom tag is detected. For many default configuration
classes providers are already registered.
The configuration definition file has the following basic structure:
<configuration systemProperties="properties file name"> <header> <!-- Optional meta information about the combined configuration --> </header> <override> <!-- Declarations for override configurations --> </override> <additional> <!-- Declarations for union configurations --> </additional> </configuration>
The name of the root element (here configuration
) is arbitrary. The optional systemProperties
attribute identifies the path to a property file containing properties that should be added to the system properties.
If specified on the root element, the system properties are set before the rest of the configuration is processed.
There are two sections (both of them are optional) for declaring override and additional configurations. Configurations in the former section are evaluated in the order of their declaration, and properties of configurations declared earlier hide those of configurations declared later. Configurations in the latter section are combined to a union configuration, i.e. all of their properties are added to a large hierarchical configuration. Configuration declarations that occur as direct children of the root element are treated as override declarations.
Each configuration declaration consists of a tag whose name is associated with a
CombinedConfigurationBuilderProvider
. This can be one of the predefined tags like properties
, or
xml
, or a custom tag, for which a configuration builder provider was registered (as described above).
Attributes and sub elements with specific initialization parameters can be added. There are some reserved attributes
with a special meaning that can be used in every configuration declaration:
Attribute | Meaning |
---|---|
config-name |
Allows specifying a name for this configuration. This name can be used to obtain a reference to the configuration
from the resulting combined configuration (see below). It can also be passed to the getNamedBuilder(String)
method. |
config-at |
With this attribute an optional prefix can be specified for the properties of the corresponding configuration. |
config-optional |
Declares a configuration source as optional. This means that errors that occur when creating the configuration are ignored. |
config-reload |
Many configuration sources support a reloading mechanism. For those sources it is possible to enable reloading by providing this attribute with a value of true. |
The optional header section can contain some meta data about the created configuration itself. For instance,
it is possible to set further properties of the NodeCombiner
objects used for constructing the resulting
configuration.
The default configuration object returned by this builder is an instance of the CombinedConfiguration
class.
This allows for convenient access to the configuration objects maintained by the combined configuration (e.g. for
updates of single configuration objects). It has also the advantage that the properties stored in all declared
configuration objects are collected and transformed into a single hierarchical structure, which can be accessed using
different expression engines. The actual CombinedConfiguration
implementation can be overridden by specifying
the class in the config-class attribute of the result element.
A custom EntityResolver can be used for all XMLConfigurations by adding
<entity-resolver config-class="EntityResolver fully qualified class name">
A specific CatalogResolver can be specified for all XMLConfiguration sources by adding
<entity-resolver catalogFiles="comma separated list of catalog files">
Additional ConfigurationProviders can be added by configuring them in the header section.
<providers> <provider config-tag="tag name" config-class="provider fully qualified class name"/> </providers>
Additional variable resolvers can be added by configuring them in the header section.
<lookups> <lookup config-prefix="prefix" config-class="StrLookup fully qualified class name"/> </lookups>
All declared override configurations are directly added to the resulting combined configuration. If they are given
names (using the config-name
attribute), they can directly be accessed using the
getConfiguration(String)
method of CombinedConfiguration
. The additional configurations are
altogether added to another combined configuration, which uses a union combiner. Then this union configuration is
added to the resulting combined configuration under the name defined by the ADDITIONAL_NAME
constant. The
getNamedBuilder(String)
method can be used to access the ConfigurationBuilder
objects for all
configuration sources which have been assigned a name; care has to be taken that these names are unique.
Modifier and Type | Field and Description |
---|---|
static String |
ADDITIONAL_NAME
Constant for the name of the additional configuration.
|
Constructor and Description |
---|
CombinedConfigurationBuilder()
Creates a new instance of
CombinedConfigurationBuilder . |
CombinedConfigurationBuilder(Map<String,Object> params)
Creates a new instance of
CombinedConfigurationBuilder and sets the specified initialization parameters. |
CombinedConfigurationBuilder(Map<String,Object> params,
boolean allowFailOnInit)
Creates a new instance of
CombinedConfigurationBuilder and sets the specified initialization parameters and
the allowFailOnInit flag. |
Modifier and Type | Method and Description |
---|---|
Set<String> |
builderNames()
Returns a set with the names of all child configuration builders.
|
CombinedConfigurationBuilder |
configure(BuilderParameters... params)
Appends the content of the specified
BuilderParameters objects to the current initialization parameters. |
protected void |
configureEntityResolver(HierarchicalConfiguration<?> config,
XMLBuilderParametersImpl xmlParams)
Creates and initializes a default
EntityResolver if the definition configuration contains a corresponding
declaration. |
protected CombinedConfiguration |
createAdditionalsConfiguration(CombinedConfiguration resultConfig)
Creates the
CombinedConfiguration for the configuration sources in the <additional> section. |
protected BeanDeclaration |
createResultDeclaration(Map<String,Object> params)
Creates a new
BeanDeclaration which is used for creating new result objects dynamically. |
protected ConfigurationBuilder<? extends HierarchicalConfiguration<?>> |
createXMLDefinitionBuilder(BuilderParameters builderParams)
Creates a default builder for the definition configuration and initializes it with a parameters object.
|
protected Collection<ConfigurationBuilder<? extends Configuration>> |
getChildBuilders()
Returns a collection with the builders for all child configuration sources.
|
ConfigurationBuilder<? extends HierarchicalConfiguration<?>> |
getDefinitionBuilder()
Returns the
ConfigurationBuilder which creates the definition configuration. |
protected HierarchicalConfiguration<?> |
getDefinitionConfiguration()
Returns the configuration containing the definition of the combined configuration to be created.
|
ConfigurationBuilder<? extends Configuration> |
getNamedBuilder(String name)
Returns the configuration builder with the given name.
|
protected void |
initChildBuilderParameters(BuilderParameters params)
Initializes a parameters object for a child builder.
|
protected FileSystem |
initFileSystem(HierarchicalConfiguration<?> config)
Creates and initializes a default
FileSystem if the definition configuration contains a corresponding
declaration. |
protected void |
initResultInstance(CombinedConfiguration result)
Initializes a newly created result object.
|
protected void |
initSystemProperties(HierarchicalConfiguration<?> config,
String basePath)
Handles a file with system properties that may be defined in the definition configuration.
|
protected ConfigurationBuilderProvider |
providerForTag(String tagName)
Returns the
ConfigurationBuilderProvider for the given tag. |
protected void |
registerConfiguredLookups(HierarchicalConfiguration<?> defConfig,
Configuration resultConfig)
Processes custom
Lookup objects that might be declared in the definition configuration. |
void |
resetParameters()
Removes all initialization parameters of this builder.
|
protected ConfigurationBuilder<? extends HierarchicalConfiguration<?>> |
setupDefinitionBuilder(Map<String,Object> params)
Obtains the
ConfigurationBuilder object which provides access to the configuration containing the definition
of the combined configuration to create. |
addEventListener, addParameters, connectToReloadingController, copyEventListeners, copyEventListeners, createResult, createResultInstance, fetchBeanHelper, fireBuilderEvent, getConfiguration, getParameters, getResultClass, getResultDeclaration, installEventListener, isAllowFailOnInit, removeEventListener, reset, resetResult, setParameters
public static final String ADDITIONAL_NAME
additional
section, a special union configuration is created and added under this name to the resulting
combined configuration.public CombinedConfigurationBuilder()
CombinedConfigurationBuilder
. No parameters are set.public CombinedConfigurationBuilder(Map<String,Object> params)
CombinedConfigurationBuilder
and sets the specified initialization parameters.params
- a map with initialization parameterspublic CombinedConfigurationBuilder(Map<String,Object> params, boolean allowFailOnInit)
CombinedConfigurationBuilder
and sets the specified initialization parameters and
the allowFailOnInit flag.params
- a map with initialization parametersallowFailOnInit
- the allowFailOnInit flagpublic ConfigurationBuilder<? extends HierarchicalConfiguration<?>> getDefinitionBuilder() throws ConfigurationException
ConfigurationBuilder
which creates the definition configuration.ConfigurationException
- if an error occurspublic CombinedConfigurationBuilder configure(BuilderParameters... params)
BuilderParameters
objects to the current initialization parameters.
Calling this method multiple times will create a union of the parameters provided. This method is overridden to adapt the return type.configure
in class BasicConfigurationBuilder<CombinedConfiguration>
params
- an arbitrary number of objects with builder parameterspublic ConfigurationBuilder<? extends Configuration> getNamedBuilder(String name) throws ConfigurationException
Returns the configuration builder with the given name. With this method a builder of a child configuration which was given a name in the configuration definition file can be accessed directly.
Important note: This method only returns a meaningful result after the result configuration has been
created by calling getConfiguration()
. If called before, always an exception is thrown.
name
- the name of the builder in questionConfigurationException
- if information about named builders is not yet available or no builder with this name
existspublic Set<String> builderNames()
Returns a set with the names of all child configuration builders. A tag defining a configuration source in the
configuration definition file can have the config-name
attribute. If this attribute is present, the
corresponding builder is assigned this name and can be directly accessed through the getNamedBuilder(String)
method. This method returns a collection with all available builder names.
Important note: This method only returns a meaningful result after the result configuration has been
created by calling getConfiguration()
. If called before, always an empty set is returned.
public void resetParameters()
resetParameters
in class BasicConfigurationBuilder<CombinedConfiguration>
protected ConfigurationBuilder<? extends HierarchicalConfiguration<?>> setupDefinitionBuilder(Map<String,Object> params) throws ConfigurationException
ConfigurationBuilder
object which provides access to the configuration containing the definition
of the combined configuration to create. If a definition builder is defined in the parameters, it is used. Otherwise,
we check whether the combined builder parameters object contains a parameters object for the definition builder. If
this is the case, a builder for an XMLConfiguration
is created and configured with this object. As a last
resort, it is looked for a FileBasedBuilderParametersImpl
object in the properties. If found, also a XML
configuration builder is created which loads this file. Note: This method is called from a synchronized block.params
- the current parameters for this builderConfigurationException
- if an error occursprotected ConfigurationBuilder<? extends HierarchicalConfiguration<?>> createXMLDefinitionBuilder(BuilderParameters builderParams)
XMLConfiguration
; it expects a corresponding file specification. Note:
This method is called in a synchronized block.builderParams
- the parameters object for the builderprotected HierarchicalConfiguration<?> getDefinitionConfiguration() throws ConfigurationException
ConfigurationException
- if an error occursprotected Collection<ConfigurationBuilder<? extends Configuration>> getChildBuilders()
protected BeanDeclaration createResultDeclaration(Map<String,Object> params) throws ConfigurationException
BeanDeclaration
which is used for creating new result objects dynamically. This implementation
creates a specialized BeanDeclaration
object that is initialized from the given map of initialization
parameters. The BeanDeclaration
must be initialized with the result class of this builder, otherwise
exceptions will be thrown when the result object is created. Note: This method is invoked in a synchronized block. This implementation evaluates the result
property of the definition configuration. It creates a
combined bean declaration with both the properties specified in the definition file and the properties defined as
initialization parameters.createResultDeclaration
in class BasicConfigurationBuilder<CombinedConfiguration>
params
- a snapshot of the current initialization parametersBeanDeclaration
for creating result objectsConfigurationException
- if an error occursprotected void initResultInstance(CombinedConfiguration result) throws ConfigurationException
BeanHelper
class to initialize the object's property based on the
BeanDeclaration
returned by BasicConfigurationBuilder.getResultDeclaration()
. Note: This method is invoked in a synchronized
block. This is required because internal state is accessed. Sub classes must not call this method without proper
synchronization. This implementation processes the definition configuration in order to
CombinedConfiguration
CombinedConfiguration
initResultInstance
in class BasicConfigurationBuilder<CombinedConfiguration>
result
- the object to be initializedConfigurationException
- if an error occursprotected CombinedConfiguration createAdditionalsConfiguration(CombinedConfiguration resultConfig)
CombinedConfiguration
for the configuration sources in the <additional>
section.
This method is called when the builder constructs the final configuration. It creates a new
CombinedConfiguration
and initializes some properties from the result configuration.resultConfig
- the result configuration (this is the configuration that will be returned by the builder)CombinedConfiguration
for the additional configuration sourcesprotected void registerConfiguredLookups(HierarchicalConfiguration<?> defConfig, Configuration resultConfig) throws ConfigurationException
Lookup
objects that might be declared in the definition configuration. Each Lookup
object is registered at the definition configuration and at the result configuration. It is also added to all child
configurations added to the resulting combined configuration.defConfig
- the definition configurationresultConfig
- the resulting configurationConfigurationException
- if an error occursprotected FileSystem initFileSystem(HierarchicalConfiguration<?> config) throws ConfigurationException
FileSystem
if the definition configuration contains a corresponding
declaration. The file system returned by this method is used as default for all file-based child configuration
sources.config
- the definition configurationFileSystem
(may be null)ConfigurationException
- if an error occursprotected void initSystemProperties(HierarchicalConfiguration<?> config, String basePath) throws ConfigurationException
config
- the definition configurationbasePath
- the base path defined for this builder (may be null)ConfigurationException
- if an error occurs.protected void configureEntityResolver(HierarchicalConfiguration<?> config, XMLBuilderParametersImpl xmlParams) throws ConfigurationException
EntityResolver
if the definition configuration contains a corresponding
declaration.config
- the definition configurationxmlParams
- the (already partly initialized) object with XML parameters; here the new resolver is to be storedConfigurationException
- if an error occursprotected ConfigurationBuilderProvider providerForTag(String tagName)
ConfigurationBuilderProvider
for the given tag. This method is called during creation of the
result configuration. (It is not allowed to call it at another point of time; result is then unpredictable!) It
supports all default providers and custom providers added through the parameters object as well.tagName
- the name of the tagprotected void initChildBuilderParameters(BuilderParameters params)
params
- the parameters object to be initializedCopyright © 2001–2022 The Apache Software Foundation. All rights reserved.