org.apache.commons.configuration
public class DefaultConfigurationBuilder extends XMLConfiguration implements ConfigurationBuilder
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 Configuration
class is instantiated and initialized using the classes of the
beanutils
package (namely
will be used to extract the configuration's initialization parameters, which
allows for complex initialization szenarios).
XMLBeanDeclaration
It is also possible to add custom tags to the configuration definition file.
For this purpose register your own ConfigurationProvider
implementation 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> <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. 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
pre-defined 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 silently ignored. |
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 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.
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
alltogether 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.
Implementation note: This class is not thread-safe. Especially the
getConfiguration()
methods should be called by a single thread
only.
Since: 1.3
Version: $Id: DefaultConfigurationBuilder.java 507219 2007-02-13 21:02:09Z oheger $
Nested Class Summary | |
---|---|
static class | DefaultConfigurationBuilder.ConfigurationBeanFactory
A specialized BeanFactory implementation that handles
configuration declarations. |
static class | DefaultConfigurationBuilder.ConfigurationBuilderProvider
A specialized configuration provider class that allows to include other
configuration definition files. |
static class | DefaultConfigurationBuilder.ConfigurationDeclaration
A specialized |
static class | DefaultConfigurationBuilder.ConfigurationProvider A base class for creating and initializing configuration sources. |
static class | DefaultConfigurationBuilder.FileConfigurationProvider
A specialized provider implementation that deals with file based
configurations. |
static class | DefaultConfigurationBuilder.FileExtensionConfigurationProvider
A specialized configuration provider for file based configurations that
can handle configuration sources whose concrete type depends on the
extension of the file to be loaded. |
Field Summary | |
---|---|
static String | ADDITIONAL_NAME
Constant for the name of the additional configuration. |
static String | ATTR_AT Constant for the at attribute without the reserved prefix. |
static String | ATTR_ATNAME Constant for the name of the at attribute. |
static String | ATTR_AT_RES Constant for the reserved at attribute. |
static String | ATTR_FILENAME Constant for the file name attribute. |
static String | ATTR_FORCECREATE Constant for the forceCreate attribute. |
static String | ATTR_NAME Constant for the reserved name attribute. |
static String | ATTR_OPTIONAL Constant for the optional attribute without the reserved prefix. |
static String | ATTR_OPTIONALNAME Constant for the name of the optional attribute. |
static String | ATTR_OPTIONAL_RES Constant for the reserved optional attribute. |
static DefaultConfigurationBuilder.ConfigurationProvider | BUILDER_PROVIDER Constant for the provider for configuration definition files. |
String | configurationBasePath Stores the base path to the configuration sources to load. |
CombinedConfiguration | constructedConfiguration Stores the configuration that is currently constructed. |
static String | CONFIG_BEAN_FACTORY_NAME Constant for the name of the configuration bean factory. |
static String[] | CONFIG_SECTIONS An array with the names of top level configuration sections. |
static DefaultConfigurationBuilder.ConfigurationProvider[] | DEFAULT_PROVIDERS An array with the providers for the default tags. |
static String[] | DEFAULT_TAGS An array with the names of the default tags. |
static String | EXT_XML Constant for the XML file extension. |
static DefaultConfigurationBuilder.ConfigurationProvider | JNDI_PROVIDER Constant for the provider for JNDI sources. |
static String | KEY_ADDITIONAL_LIST
Constant for the key that points to the list nodes definition of the
additional combiner. |
static String | KEY_COMBINER Constant for the key of the combiner in the result declaration. |
static String | KEY_OVERRIDE
Constant for an expression that selects override configurations in the
override section. |
static String | KEY_OVERRIDE_LIST
Constant for the key that points to the list nodes definition of the
override combiner. |
static String | KEY_RESULT
Constant for the key of the result declaration. |
static String | KEY_UNION Constant for an expression that selects the union configurations. |
Map | providers Stores a map with the registered configuration providers. |
static DefaultConfigurationBuilder.ConfigurationProvider | PLIST_PROVIDER Constant for the provider for plist files. |
static DefaultConfigurationBuilder.ConfigurationProvider | PROPERTIES_PROVIDER Constant for the provider for properties files. |
static long | serialVersionUID
The serial version UID. |
static String | SEC_HEADER Constant for the name of the header section. |
static DefaultConfigurationBuilder.ConfigurationProvider | SYSTEM_PROVIDER Constant for the provider for system properties. |
static DefaultConfigurationBuilder.ConfigurationProvider | XML_PROVIDER Constant for the provider for XML files. |
Constructor Summary | |
---|---|
DefaultConfigurationBuilder()
Creates a new instance of DefaultConfigurationBuilder . | |
DefaultConfigurationBuilder(File file)
Creates a new instance of DefaultConfigurationBuilder and
sets the specified configuration definition file.
| |
DefaultConfigurationBuilder(String fileName)
Creates a new instance of DefaultConfigurationBuilder and
sets the specified configuration definition file.
| |
DefaultConfigurationBuilder(URL url)
Creates a new instance of DefaultConfigurationBuilder and
sets the specified configuration definition file.
|
Method Summary | |
---|---|
void | addConfigurationProvider(String tagName, DefaultConfigurationBuilder.ConfigurationProvider provider)
Adds a configuration provider for the specified tag. |
AbstractConfiguration | createConfigurationAt(DefaultConfigurationBuilder.ConfigurationDeclaration decl)
Creates a configuration object from the specified configuration
declaration.
|
protected CombinedConfiguration | createResultConfiguration()
Creates the resulting combined configuration. |
List | fetchChildConfigs(ConfigurationNode node)
Returns a list with SubnodeConfiguration objects for the
child nodes of the specified configuration node.
|
List | fetchChildConfigs(String key)
Returns a list with SubnodeConfiguration objects for the
child nodes of the node specified by the given key.
|
List | fetchTopLevelOverrideConfigs()
Finds the override configurations that are defined as top level elements
in the configuration definition file. |
Configuration | getConfiguration()
Returns the configuration provided by this builder. |
CombinedConfiguration | getConfiguration(boolean load)
Returns the configuration provided by this builder. |
String | getConfigurationBasePath()
Returns the base path for the configuration sources to load. |
protected void | initCombinedConfiguration(CombinedConfiguration config, List containedConfigs, String keyListNodes)
Initializes a combined configuration for the configurations of a specific
section. |
protected Object | interpolate(Object value)
Performs interpolation. |
DefaultConfigurationBuilder.ConfigurationProvider | providerForTag(String tagName)
Returns the configuration provider for the given tag.
|
protected void | registerDefaultProviders()
Registers the default configuration providers supported by this class.
|
DefaultConfigurationBuilder.ConfigurationProvider | removeConfigurationProvider(String tagName)
Removes the configuration provider for the specified tag name.
|
void | setConfigurationBasePath(String configurationBasePath)
Sets the base path for the configuration sources to load. |
additional
section, a special union configuration is created and added under this
name to the resulting combined configuration.DefaultConfigurationBuilder
. A
configuration definition file is not yet loaded. Use the diverse setter
methods provided by file based configurations to specify the
configuration definition file.DefaultConfigurationBuilder
and
sets the specified configuration definition file.
Parameters: file the configuration definition file
DefaultConfigurationBuilder
and
sets the specified configuration definition file.
Parameters: fileName the name of the configuration definition file
Throws: ConfigurationException if an error occurs when the file is loaded
DefaultConfigurationBuilder
and
sets the specified configuration definition file.
Parameters: url the URL to the configuration definition file
Throws: ConfigurationException if an error occurs when the file is loaded
Parameters: tagName the name of the tag in the configuration definition file provider the provider for this tag
Parameters: decl the configuration declaration
Returns: the new configuration object
Throws: ConfigurationException if an error occurs
getConfiguration()
. It checks whether the
header
section of the configuration definition file
contains a result
element. If this is the case, it will be
used to initialize the properties of the newly created configuration
object.
Returns: the resulting configuration object
Throws: ConfigurationException if an error occurs
SubnodeConfiguration
objects for the
child nodes of the specified configuration node.
Parameters: node the start node
Returns: a list with subnode configurations for the node's children
SubnodeConfiguration
objects for the
child nodes of the node specified by the given key.
Parameters: key the key (must define exactly one node)
Returns: a list with subnode configurations for the node's children
Returns: a list with subnode configurations for the top level override configurations
Returns: the configuration
Throws: ConfigurationException if an error occurs
Parameters: load a flag whether the configuration definition file should be loaded; a value of false would make sense if the file has already been created or its content was manipulated using some of the property accessor methods
Returns: the configuration
Throws: ConfigurationException if an error occurs
Returns: the base path for configuration sources
Parameters: config the configuration to be initialized containedConfigs the list with the declaratinos of the contained configurations keyListNodes a list with the declaration of list nodes
Throws: ConfigurationException if an error occurs
Parameters: value the value to be interpolated
Returns: the interpolated value
Parameters: tagName the name of the tag
Returns: the provider that was registered for this tag or null if there is none
Parameters: tagName the tag name
Returns: the removed configuration provider or null if none was registered for that tag
Parameters: configurationBasePath the new base path to set