A factory class that creates a composite configuration from 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, the corresponding
Configurationclass is instantiated and initialized using the classes of the
beanutils package (namely
org.apache.commons.configuration.beanutils.XMLBeanDeclarationwill 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 register your own
ConfigurationProviderimplementation for your tag using the
addConfigurationProvider()method. This provider will then be called when the corresponding custom tag
is detected. For the 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 composite 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
ConfigurationProvider. This can be one of the
predefined tags like
properties, or
xml, or
a custom tag, for which a configuration provider was registered. 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 to specify a name for this configuration. This name can be used
to obtain a reference to the configuration from the resulting combined
configuration (see below). |
config-at |
With this attribute an optional prefix can be specified for the
properties of the corresponding configuration. |
config-optional |
Declares a configuration as optional. This means that errors that occur
when creating the configuration are ignored. (However
org.apache.commons.configuration.event.ConfigurationErrorListeners
registered at the builder instance will get notified about this error: they
receive an event of type
EVENT_ERR_LOAD_OPTIONAL. The key
property of this event contains the name of the optional configuration source
that caused this problem.) |
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. The return value of the
getConfiguration() method can be casted to this type, and the
getConfiguration(boolean) method directly declares
CombinedConfiguration as return type. 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">
The CatalogResolver can be used for all XMLConfiguration 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_NAMEconstant.
Implementation note: This class is not thread-safe. Especially the
getConfiguration() methods should be called by a single thread
only.