|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.apache.commons.configuration.event.EventSource
org.apache.commons.configuration.AbstractConfiguration
org.apache.commons.configuration.HierarchicalConfiguration
org.apache.commons.configuration.AbstractHierarchicalFileConfiguration
org.apache.commons.configuration.XMLConfiguration
org.apache.commons.configuration.DefaultConfigurationBuilder
public class DefaultConfigurationBuilder
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
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
s
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 configuration object returned by this builder is an instance of the
class. The return value of the
CombinedConfiguration
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.
Nested Class Summary | |
---|---|
(package private) static class |
DefaultConfigurationBuilder.ConfigurationBeanFactory
A specialized BeanFactory implementation that handles
configuration declarations. |
(package private) static class |
DefaultConfigurationBuilder.ConfigurationBuilderProvider
A specialized configuration provider class that allows to include other configuration definition files. |
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. |
(package private) 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. |
(package private) static class |
DefaultConfigurationBuilder.XMLConfigurationProvider
A specialized configuration provider for XML configurations. |
Nested classes/interfaces inherited from class org.apache.commons.configuration.XMLConfiguration |
---|
XMLConfiguration.XMLBuilderVisitor, XMLConfiguration.XMLNode |
Nested classes/interfaces inherited from class org.apache.commons.configuration.AbstractHierarchicalFileConfiguration |
---|
AbstractHierarchicalFileConfiguration.FileConfigurationDelegate |
Nested classes/interfaces inherited from class org.apache.commons.configuration.HierarchicalConfiguration |
---|
HierarchicalConfiguration.BuilderVisitor, HierarchicalConfiguration.CloneVisitor, HierarchicalConfiguration.DefinedKeysVisitor, HierarchicalConfiguration.DefinedVisitor, HierarchicalConfiguration.Node, HierarchicalConfiguration.NodeVisitor |
Field Summary | |
---|---|
static java.lang.String |
ADDITIONAL_NAME
Constant for the name of the additional configuration. |
(package private) static java.lang.String |
ATTR_AT
Constant for the at attribute without the reserved prefix. |
(package private) static java.lang.String |
ATTR_AT_RES
Constant for the reserved at attribute. |
(package private) static java.lang.String |
ATTR_ATNAME
Constant for the name of the at attribute. |
(package private) static java.lang.String |
ATTR_FILENAME
Constant for the file name attribute. |
(package private) static java.lang.String |
ATTR_FORCECREATE
Constant for the forceCreate attribute. |
(package private) static java.lang.String |
ATTR_NAME
Constant for the reserved name attribute. |
(package private) static java.lang.String |
ATTR_OPTIONAL
Constant for the optional attribute without the reserved prefix. |
(package private) static java.lang.String |
ATTR_OPTIONAL_RES
Constant for the reserved optional attribute. |
(package private) static java.lang.String |
ATTR_OPTIONALNAME
Constant for the name of the optional attribute. |
private static DefaultConfigurationBuilder.ConfigurationProvider |
BUILDER_PROVIDER
Constant for the provider for configuration definition files. |
(package private) static java.lang.String |
CONFIG_BEAN_FACTORY_NAME
Constant for the name of the configuration bean factory. |
(package private) static java.lang.String[] |
CONFIG_SECTIONS
An array with the names of top level configuration sections. |
private java.lang.String |
configurationBasePath
Stores the base path to the configuration sources to load. |
private CombinedConfiguration |
constructedConfiguration
Stores the configuration that is currently constructed. |
private static DefaultConfigurationBuilder.ConfigurationProvider[] |
DEFAULT_PROVIDERS
An array with the providers for the default tags. |
private static java.lang.String[] |
DEFAULT_TAGS
An array with the names of the default tags. |
static int |
EVENT_ERR_LOAD_OPTIONAL
Constant for the type of error events caused by optional configurations that cannot be loaded. |
(package private) static java.lang.String |
EXT_XML
Constant for the XML file extension. |
private static DefaultConfigurationBuilder.ConfigurationProvider |
JNDI_PROVIDER
Constant for the provider for JNDI sources. |
(package private) static java.lang.String |
KEY_ADDITIONAL_LIST
Constant for the key that points to the list nodes definition of the additional combiner. |
(package private) static java.lang.String |
KEY_COMBINER
Constant for the key of the combiner in the result declaration. |
(package private) static java.lang.String |
KEY_OVERRIDE
Constant for an expression that selects override configurations in the override section. |
(package private) static java.lang.String |
KEY_OVERRIDE_LIST
Constant for the key that points to the list nodes definition of the override combiner. |
(package private) static java.lang.String |
KEY_RESULT
Constant for the key of the result declaration. |
(package private) static java.lang.String |
KEY_UNION
Constant for an expression that selects the union configurations. |
private static DefaultConfigurationBuilder.ConfigurationProvider |
PLIST_PROVIDER
Constant for the provider for plist files. |
private static DefaultConfigurationBuilder.ConfigurationProvider |
PROPERTIES_PROVIDER
Constant for the provider for properties files. |
private java.util.Map |
providers
Stores a map with the registered configuration providers. |
(package private) static java.lang.String |
SEC_HEADER
Constant for the name of the header section. |
private static long |
serialVersionUID
The serial version UID. |
private static DefaultConfigurationBuilder.ConfigurationProvider |
SYSTEM_PROVIDER
Constant for the provider for system properties. |
private static DefaultConfigurationBuilder.ConfigurationProvider |
XML_PROVIDER
Constant for the provider for XML files. |
Fields inherited from class org.apache.commons.configuration.HierarchicalConfiguration |
---|
EVENT_ADD_NODES, EVENT_CLEAR_TREE, EVENT_SUBNODE_CHANGED |
Fields inherited from class org.apache.commons.configuration.AbstractConfiguration |
---|
END_TOKEN, EVENT_ADD_PROPERTY, EVENT_CLEAR, EVENT_CLEAR_PROPERTY, EVENT_READ_PROPERTY, EVENT_SET_PROPERTY, START_TOKEN |
Constructor Summary | |
---|---|
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. |
Method Summary | |
---|---|
void |
addConfigurationProvider(java.lang.String tagName,
DefaultConfigurationBuilder.ConfigurationProvider provider)
Adds a configuration provider for the specified tag. |
private AbstractConfiguration |
createConfigurationAt(DefaultConfigurationBuilder.ConfigurationDeclaration decl)
Creates a configuration object from the specified configuration declaration. |
protected CombinedConfiguration |
createResultConfiguration()
Creates the resulting combined configuration. |
private java.util.List |
fetchChildConfigs(ConfigurationNode node)
Returns a list with SubnodeConfiguration objects for the
child nodes of the specified configuration node. |
private java.util.List |
fetchChildConfigs(java.lang.String key)
Returns a list with SubnodeConfiguration objects for the
child nodes of the node specified by the given key. |
private java.util.List |
fetchTopLevelOverrideConfigs()
Finds the override configurations that are defined as top level elements in the configuration definition file. |
protected void |
fireError(int type,
java.lang.String propName,
java.lang.Object propValue,
java.lang.Throwable ex)
Creates an error event object and delivers it to all registered error listeners. |
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 containedConfigs,
java.lang.String keyListNodes)
Initializes a combined configuration for the configurations of a specific section. |
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. |
private void |
registerBeanFactory()
Registers the bean factory used by this class if necessary. |
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. |
Methods inherited from class org.apache.commons.configuration.XMLConfiguration |
---|
addNodes, clear, clone, createDelegate, createDocument, createDocumentBuilder, createNode, createTransformer, getDocument, getDocumentBuilder, getPublicID, getRegisteredEntities, getRootElementName, getSystemID, initProperties, isValidating, load, load, registerEntityId, resolveEntity, save, setDocumentBuilder, setPublicID, setRootElementName, setSystemID, setValidating |
Methods inherited from class org.apache.commons.configuration.AbstractHierarchicalFileConfiguration |
---|
addPropertyDirect, clearProperty, clearTree, configurationChanged, containsKey, fetchNodeList, getBasePath, getDelegate, getEncoding, getFile, getFileName, getKeys, getProperty, getReloadingStrategy, getURL, isAutoSave, isEmpty, load, load, load, load, load, reload, save, save, save, save, save, save, setAutoSave, setBasePath, setDelegate, setEncoding, setFile, setFileName, setProperty, setReloadingStrategy, setURL, subnodeConfigurationChanged |
Methods inherited from class org.apache.commons.configuration.HierarchicalConfiguration |
---|
clearNode, clearNode, clearReferences, configurationAt, configurationAt, configurationsAt, createAddPath, createSubnodeConfiguration, createSubnodeConfiguration, fetchAddNode, findLastPathNode, findPropertyNodes, getDefaultExpressionEngine, getExpressionEngine, getKeys, getMaxIndex, getRoot, getRootNode, interpolatedConfiguration, nodeDefined, nodeDefined, registerSubnodeConfiguration, removeNode, removeNode, setDefaultExpressionEngine, setExpressionEngine, setRoot, setRootNode, subset |
Methods inherited from class org.apache.commons.configuration.event.EventSource |
---|
addConfigurationListener, addErrorListener, clearConfigurationListeners, clearErrorListeners, createErrorEvent, createEvent, fireEvent, getConfigurationListeners, getErrorListeners, isDetailEvents, removeConfigurationListener, removeErrorListener, setDetailEvents |
Methods inherited from class java.lang.Object |
---|
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Methods inherited from interface org.apache.commons.configuration.Configuration |
---|
addProperty, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getKeys, getList, getList, getLong, getLong, getLong, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, subset |
Field Detail |
---|
public 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
static final java.lang.String CONFIG_BEAN_FACTORY_NAME
static final java.lang.String ATTR_NAME
static final java.lang.String ATTR_ATNAME
static final java.lang.String ATTR_AT_RES
static final java.lang.String ATTR_AT
static final java.lang.String ATTR_OPTIONALNAME
static final java.lang.String ATTR_OPTIONAL_RES
static final java.lang.String ATTR_OPTIONAL
static final java.lang.String ATTR_FILENAME
static final java.lang.String ATTR_FORCECREATE
static final java.lang.String SEC_HEADER
static final java.lang.String KEY_UNION
static final java.lang.String[] CONFIG_SECTIONS
static final java.lang.String KEY_OVERRIDE
static final java.lang.String KEY_OVERRIDE_LIST
static final java.lang.String KEY_ADDITIONAL_LIST
static final java.lang.String KEY_RESULT
static final java.lang.String KEY_COMBINER
static final java.lang.String EXT_XML
private static final DefaultConfigurationBuilder.ConfigurationProvider PROPERTIES_PROVIDER
private static final DefaultConfigurationBuilder.ConfigurationProvider XML_PROVIDER
private static final DefaultConfigurationBuilder.ConfigurationProvider JNDI_PROVIDER
private static final DefaultConfigurationBuilder.ConfigurationProvider SYSTEM_PROVIDER
private static final DefaultConfigurationBuilder.ConfigurationProvider PLIST_PROVIDER
private static final DefaultConfigurationBuilder.ConfigurationProvider BUILDER_PROVIDER
private static final java.lang.String[] DEFAULT_TAGS
private static final DefaultConfigurationBuilder.ConfigurationProvider[] DEFAULT_PROVIDERS
private static final long serialVersionUID
private CombinedConfiguration constructedConfiguration
private java.util.Map providers
private java.lang.String configurationBasePath
Constructor Detail |
---|
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 file
ConfigurationException
- 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 file
ConfigurationException
- if an error occurs when the file is loadedMethod Detail |
---|
public 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 name
public DefaultConfigurationBuilder.ConfigurationProvider providerForTag(java.lang.String tagName)
tagName
- the name of the tag
public Configuration getConfiguration() throws ConfigurationException
getConfiguration
in interface ConfigurationBuilder
ConfigurationException
- 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 methods
ConfigurationException
- 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 void initCombinedConfiguration(CombinedConfiguration config, java.util.List containedConfigs, java.lang.String keyListNodes) throws ConfigurationException
config
- the configuration to be initializedcontainedConfigs
- the list with the declaratinos of the contained
configurationskeyListNodes
- a list with the declaration of list nodes
ConfigurationException
- if an error occursprotected void registerDefaultProviders()
protected java.lang.Object interpolate(java.lang.Object value)
interpolate
in class AbstractConfiguration
value
- the value to be interpolated
protected void fireError(int type, java.lang.String propName, java.lang.Object propValue, java.lang.Throwable ex)
EventSource
fireError
in class EventSource
type
- the event's typepropName
- the name of the affected property (can be null)propValue
- the value of the affected property (can be null)ex
- the Throwable
object that caused this error eventprivate AbstractConfiguration createConfigurationAt(DefaultConfigurationBuilder.ConfigurationDeclaration decl) throws ConfigurationException
decl
- the configuration declaration
ConfigurationException
- if an error occursprivate java.util.List fetchChildConfigs(ConfigurationNode node)
SubnodeConfiguration
objects for the
child nodes of the specified configuration node.
node
- the start node
private java.util.List fetchChildConfigs(java.lang.String key)
SubnodeConfiguration
objects for the
child nodes of the node specified by the given key.
key
- the key (must define exactly one node)
private java.util.List fetchTopLevelOverrideConfigs()
private void registerBeanFactory()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |