Configuration, ConfigurationBuilder, ConfigurationErrorListener, ConfigurationListener, FileConfiguration, FileSystemBased, Reloadable, EntityRegistrypublic 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
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 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 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
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_NAME
constant.
Implementation note: This class is not thread-safe. Especially the
getConfiguration() methods should be called by a single thread
only.
| Modifier and Type | Class | Description |
|---|---|---|
static class |
DefaultConfigurationBuilder.ConfigurationDeclaration |
A specialized
BeanDeclaration implementation that
represents the declaration of a configuration source. |
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.XMLConfigurationProvider |
A specialized configuration provider for XML configurations.
|
AbstractHierarchicalFileConfiguration.FileConfigurationDelegateHierarchicalConfiguration.BuilderVisitor, HierarchicalConfiguration.Node, HierarchicalConfiguration.NodeVisitor| Modifier and Type | Field | Description |
|---|---|---|
static java.lang.String |
ADDITIONAL_NAME |
Constant for the name of the additional configuration.
|
static int |
EVENT_ERR_LOAD_OPTIONAL |
Constant for the type of error events caused by optional configurations
that cannot be loaded.
|
END_TOKEN, EVENT_ADD_PROPERTY, EVENT_CLEAR, EVENT_CLEAR_PROPERTY, EVENT_READ_PROPERTY, EVENT_SET_PROPERTY, START_TOKENEVENT_ADD_NODES, EVENT_CLEAR_TREE, EVENT_SUBNODE_CHANGED| Constructor | Description |
|---|---|
DefaultConfigurationBuilder() |
Creates a new instance of
DefaultConfigurationBuilder. |
DefaultConfigurationBuilder(java.io.File file) |
Creates a new instance of
DefaultConfigurationBuilder and
sets the specified configuration definition file. |
DefaultConfigurationBuilder(java.lang.String fileName) |
Creates a new instance of
DefaultConfigurationBuilder and
sets the specified configuration definition file. |
DefaultConfigurationBuilder(java.net.URL url) |
Creates a new instance of
DefaultConfigurationBuilder and
sets the specified configuration definition file. |
| Modifier and Type | Method | Description |
|---|---|---|
void |
addConfigurationProvider(java.lang.String tagName,
DefaultConfigurationBuilder.ConfigurationProvider provider) |
Adds a configuration provider for the specified tag.
|
protected void |
configureEntityResolver() |
|
protected CombinedConfiguration |
createAdditionalsConfiguration(CombinedConfiguration resultConfig) |
Creates the
CombinedConfiguration for the configuration
sources in the <additional> section. |
protected CombinedConfiguration |
createResultConfiguration() |
Creates the resulting combined configuration.
|
Configuration |
getConfiguration() |
Returns the configuration provided by this builder.
|
CombinedConfiguration |
getConfiguration(boolean load) |
Returns the configuration provided by this builder.
|
java.lang.String |
getConfigurationBasePath() |
Returns the base path for the configuration sources to load.
|
protected void |
initCombinedConfiguration(CombinedConfiguration config,
java.util.List<? extends HierarchicalConfiguration> containedConfigs,
java.lang.String keyListNodes) |
Initializes a combined configuration for the configurations of a specific
section.
|
protected void |
initFileSystem() |
|
protected void |
initSystemProperties() |
If a property file is configured add the properties to the System properties.
|
protected java.lang.Object |
interpolate(java.lang.Object value) |
Performs interpolation.
|
DefaultConfigurationBuilder.ConfigurationProvider |
providerForTag(java.lang.String tagName) |
Returns the configuration provider for the given tag.
|
protected void |
registerConfiguredLookups() |
Registers StrLookups defined in the configuration.
|
protected void |
registerConfiguredProviders() |
Registers providers defined in the configuration.
|
protected void |
registerDefaultProviders() |
Registers the default configuration providers supported by this class.
|
DefaultConfigurationBuilder.ConfigurationProvider |
removeConfigurationProvider(java.lang.String tagName) |
Removes the configuration provider for the specified tag name.
|
void |
setConfigurationBasePath(java.lang.String configurationBasePath) |
Sets the base path for the configuration sources to load.
|
addErrorLogListener, addProperty, append, clearPropertyDirect, copy, createInterpolator, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDefaultListDelimiter, getDelimiter, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getInterpolator, getList, getList, getListDelimiter, getLogger, getLong, getLong, getLong, getProperties, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, getSubstitutor, interpolate, interpolateHelper, isDelimiterParsingDisabled, isScalarValue, isThrowExceptionOnMissing, resolveContainerStore, setDefaultListDelimiter, setDelimiter, setDelimiterParsingDisabled, setListDelimiter, setLogger, setThrowExceptionOnMissingaddPropertyDirect, clearProperty, clearTree, configurationChanged, configurationError, containsKey, fetchNodeList, getBasePath, getDelegate, getEncoding, getFile, getFileName, getFileSystem, getKeys, getKeys, getProperty, getReloadingStrategy, getReloadLock, getURL, isAutoSave, isEmpty, load, load, load, load, load, refresh, reload, resetFileSystem, save, save, save, save, save, save, setAutoSave, setBasePath, setDelegate, setEncoding, setFile, setFileName, setFileSystem, setProperty, setReloadingStrategy, setURL, subnodeConfigurationChangedaddProperty, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getList, getList, getLong, getLong, getLong, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, subsetaddConfigurationListener, addErrorListener, clearConfigurationListeners, clearErrorListeners, createErrorEvent, createEvent, fireError, fireEvent, getConfigurationListeners, getErrorListeners, isDetailEvents, removeConfigurationListener, removeErrorListener, setDetailEventsclearNode, clearNode, clearReferences, configurationAt, configurationAt, configurationsAt, createAddPath, createSubnodeConfiguration, createSubnodeConfiguration, fetchAddNode, findLastPathNode, findPropertyNodes, getDefaultExpressionEngine, getExpressionEngine, getMaxIndex, getRoot, getRootNode, interpolatedConfiguration, nodeDefined, nodeDefined, removeNode, removeNode, setDefaultExpressionEngine, setExpressionEngine, setRoot, setRootNode, subsetequals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitaddNodes, clear, clone, createDelegate, createDocument, createDocumentBuilder, createNode, createTransformer, getDocument, getDocumentBuilder, getEntityResolver, getPublicID, getRegisteredEntities, getRootElementName, getSystemID, initProperties, isAttributeSplittingDisabled, isSchemaValidation, isValidating, load, load, registerEntityId, resolveEntity, save, setAttributeSplittingDisabled, setDocumentBuilder, setEntityResolver, setPublicID, setRootElementName, setSchemaValidation, setSystemID, setValidating, validatepublic static final java.lang.String ADDITIONAL_NAME
additional
section, a special union configuration is created and added under this
name to the resulting combined configuration.public static final int EVENT_ERR_LOAD_OPTIONAL
public DefaultConfigurationBuilder()
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.public DefaultConfigurationBuilder(java.io.File file)
DefaultConfigurationBuilder and
sets the specified configuration definition file.file - the configuration definition filepublic DefaultConfigurationBuilder(java.lang.String fileName) throws ConfigurationException
DefaultConfigurationBuilder and
sets the specified configuration definition file.fileName - the name of the configuration definition fileConfigurationException - if an error occurs when the file is loadedpublic DefaultConfigurationBuilder(java.net.URL url) throws ConfigurationException
DefaultConfigurationBuilder and
sets the specified configuration definition file.url - the URL to the configuration definition fileConfigurationException - if an error occurs when the file is loadedpublic java.lang.String getConfigurationBasePath()
public void setConfigurationBasePath(java.lang.String configurationBasePath)
configurationBasePath - the new base path to setpublic void addConfigurationProvider(java.lang.String tagName, DefaultConfigurationBuilder.ConfigurationProvider provider)
tagName - the name of the tag in the configuration definition fileprovider - the provider for this tagpublic DefaultConfigurationBuilder.ConfigurationProvider removeConfigurationProvider(java.lang.String tagName)
tagName - the tag namepublic DefaultConfigurationBuilder.ConfigurationProvider providerForTag(java.lang.String tagName)
tagName - the name of the tagpublic Configuration getConfiguration() throws ConfigurationException
getConfiguration in interface ConfigurationBuilderConfigurationException - if an error occurspublic CombinedConfiguration getConfiguration(boolean load) throws ConfigurationException
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 methodsConfigurationException - if an error occursprotected CombinedConfiguration createResultConfiguration() throws ConfigurationException
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.ConfigurationException - 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 initCombinedConfiguration(CombinedConfiguration config, java.util.List<? extends HierarchicalConfiguration> containedConfigs, java.lang.String keyListNodes) throws ConfigurationException
config - the configuration to be initializedcontainedConfigs - the list with the declarations of the contained
configurationskeyListNodes - a list with the declaration of list nodesConfigurationException - if an error occursprotected void registerDefaultProviders()
protected void registerConfiguredProviders() throws ConfigurationException
ConfigurationException - if an error occursprotected void registerConfiguredLookups() throws ConfigurationException
ConfigurationException - if an error occursprotected void initFileSystem() throws ConfigurationException
ConfigurationExceptionprotected void initSystemProperties() throws ConfigurationException
ConfigurationException - if an error occurs.protected void configureEntityResolver() throws ConfigurationException
ConfigurationExceptionprotected java.lang.Object interpolate(java.lang.Object value)
interpolate in class AbstractConfigurationvalue - the value to be interpolated