Class DefaultConfigurationBuilder
- java.lang.Object
-
- org.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
-
- All Implemented Interfaces:
java.io.Serializable
,java.lang.Cloneable
,Configuration
,ConfigurationBuilder
,ConfigurationErrorListener
,ConfigurationListener
,FileConfiguration
,FileSystemBased
,Reloadable
,EntityRegistry
,org.xml.sax.EntityResolver
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 thebeanutils
package (namelyXMLBeanDeclaration
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 theaddConfigurationProvider()
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 likeproperties
, orxml
, 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 ConfigurationErrorListener
s registered at the builder instance will get notified about this error: they receive an event of typeEVENT_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 thegetConfiguration()
method can be casted to this type, and thegetConfiguration(boolean)
method directly declaresCombinedConfiguration
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 thegetConfiguration(String)
method ofCombinedConfiguration
. 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 theADDITIONAL_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 1366930 2012-07-29 20:05:36Z oheger $
- Author:
- Commons Configuration team
- See Also:
- Serialized Form
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
DefaultConfigurationBuilder.ConfigurationDeclaration
A specializedBeanDeclaration
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.-
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.Node, HierarchicalConfiguration.NodeVisitor
-
-
Field Summary
Fields 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.-
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
Constructors Constructor Description DefaultConfigurationBuilder()
Creates a new instance ofDefaultConfigurationBuilder
.DefaultConfigurationBuilder(java.io.File file)
Creates a new instance ofDefaultConfigurationBuilder
and sets the specified configuration definition file.DefaultConfigurationBuilder(java.lang.String fileName)
Creates a new instance ofDefaultConfigurationBuilder
and sets the specified configuration definition file.DefaultConfigurationBuilder(java.net.URL url)
Creates a new instance ofDefaultConfigurationBuilder
and sets the specified configuration definition file.
-
Method Summary
All Methods Instance Methods Concrete Methods 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 theCombinedConfiguration
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.-
Methods inherited from class org.apache.commons.configuration.XMLConfiguration
addNodes, 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, validate
-
Methods inherited from class org.apache.commons.configuration.AbstractHierarchicalFileConfiguration
addPropertyDirect, 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, subnodeConfigurationChanged
-
Methods inherited from class org.apache.commons.configuration.HierarchicalConfiguration
clearNode, 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, subset
-
Methods inherited from class org.apache.commons.configuration.AbstractConfiguration
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, setThrowExceptionOnMissing
-
Methods inherited from class org.apache.commons.configuration.event.EventSource
addConfigurationListener, addErrorListener, clearConfigurationListeners, clearErrorListeners, createErrorEvent, createEvent, fireError, 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, getList, getList, getLong, getLong, getLong, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, subset
-
-
-
-
Field Detail
-
ADDITIONAL_NAME
public static final java.lang.String ADDITIONAL_NAME
Constant for the name of the additional configuration. If the configuration definition file contains anadditional
section, a special union configuration is created and added under this name to the resulting combined configuration.
-
EVENT_ERR_LOAD_OPTIONAL
public static final int EVENT_ERR_LOAD_OPTIONAL
Constant for the type of error events caused by optional configurations that cannot be loaded.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
DefaultConfigurationBuilder
public DefaultConfigurationBuilder()
Creates a new instance ofDefaultConfigurationBuilder
. 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
public DefaultConfigurationBuilder(java.io.File file)
Creates a new instance ofDefaultConfigurationBuilder
and sets the specified configuration definition file.- Parameters:
file
- the configuration definition file
-
DefaultConfigurationBuilder
public DefaultConfigurationBuilder(java.lang.String fileName) throws ConfigurationException
Creates a new instance ofDefaultConfigurationBuilder
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
public DefaultConfigurationBuilder(java.net.URL url) throws ConfigurationException
Creates a new instance ofDefaultConfigurationBuilder
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
-
-
Method Detail
-
getConfigurationBasePath
public java.lang.String getConfigurationBasePath()
Returns the base path for the configuration sources to load. This path is used to resolve relative paths in the configuration definition file.- Returns:
- the base path for configuration sources
-
setConfigurationBasePath
public void setConfigurationBasePath(java.lang.String configurationBasePath)
Sets the base path for the configuration sources to load. Normally a base path need not to be set because it is determined by the location of the configuration definition file to load. All relative paths in this file are resolved relative to this file. Setting a base path makes sense if such relative paths should be otherwise resolved, e.g. if the configuration file is loaded from the class path and all sub configurations it refers to are stored in a special config directory.- Parameters:
configurationBasePath
- the new base path to set
-
addConfigurationProvider
public void addConfigurationProvider(java.lang.String tagName, DefaultConfigurationBuilder.ConfigurationProvider provider)
Adds a configuration provider for the specified tag. Whenever this tag is encountered in the configuration definition file this provider will be called to create the configuration object.- Parameters:
tagName
- the name of the tag in the configuration definition fileprovider
- the provider for this tag
-
removeConfigurationProvider
public DefaultConfigurationBuilder.ConfigurationProvider removeConfigurationProvider(java.lang.String tagName)
Removes the configuration provider for the specified tag name.- Parameters:
tagName
- the tag name- Returns:
- the removed configuration provider or null if none was registered for that tag
-
providerForTag
public DefaultConfigurationBuilder.ConfigurationProvider providerForTag(java.lang.String tagName)
Returns the configuration provider for the given tag.- Parameters:
tagName
- the name of the tag- Returns:
- the provider that was registered for this tag or null if there is none
-
getConfiguration
public Configuration getConfiguration() throws ConfigurationException
Returns the configuration provided by this builder. Loads and parses the configuration definition file and creates instances for the declared configurations.- Specified by:
getConfiguration
in interfaceConfigurationBuilder
- Returns:
- the configuration
- Throws:
ConfigurationException
- if an error occurs
-
getConfiguration
public CombinedConfiguration getConfiguration(boolean load) throws ConfigurationException
Returns the configuration provided by this builder. If the boolean parameter is true, the configuration definition file will be loaded. It will then be parsed, and instances for the declared configurations will be created.- 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
-
createResultConfiguration
protected CombinedConfiguration createResultConfiguration() throws ConfigurationException
Creates the resulting combined configuration. This method is called bygetConfiguration()
. It checks whether theheader
section of the configuration definition file contains aresult
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
-
createAdditionalsConfiguration
protected CombinedConfiguration createAdditionalsConfiguration(CombinedConfiguration resultConfig)
Creates theCombinedConfiguration
for the configuration sources in the<additional>
section. This method is called when the builder constructs the final configuration. It creates a newCombinedConfiguration
and initializes some properties from the result configuration.- Parameters:
resultConfig
- the result configuration (this is the configuration that will be returned by the builder)- Returns:
- the
CombinedConfiguration
for the additional configuration sources - Since:
- 1.7
-
initCombinedConfiguration
protected void initCombinedConfiguration(CombinedConfiguration config, java.util.List<? extends HierarchicalConfiguration> containedConfigs, java.lang.String keyListNodes) throws ConfigurationException
Initializes a combined configuration for the configurations of a specific section. This method is called for the override and for the additional section (if it exists).- Parameters:
config
- the configuration to be initializedcontainedConfigs
- the list with the declarations of the contained configurationskeyListNodes
- a list with the declaration of list nodes- Throws:
ConfigurationException
- if an error occurs
-
registerDefaultProviders
protected void registerDefaultProviders()
Registers the default configuration providers supported by this class. This method will be called during initialization. It registers configuration providers for the tags that are supported by default.
-
registerConfiguredProviders
protected void registerConfiguredProviders() throws ConfigurationException
Registers providers defined in the configuration.- Throws:
ConfigurationException
- if an error occurs
-
registerConfiguredLookups
protected void registerConfiguredLookups() throws ConfigurationException
Registers StrLookups defined in the configuration.- Throws:
ConfigurationException
- if an error occurs
-
initFileSystem
protected void initFileSystem() throws ConfigurationException
- Throws:
ConfigurationException
-
initSystemProperties
protected void initSystemProperties() throws ConfigurationException
If a property file is configured add the properties to the System properties.- Throws:
ConfigurationException
- if an error occurs.
-
configureEntityResolver
protected void configureEntityResolver() throws ConfigurationException
- Throws:
ConfigurationException
-
interpolate
protected java.lang.Object interpolate(java.lang.Object value)
Performs interpolation. This method will not only take this configuration instance into account (which is the one that loaded the configuration definition file), but also the so far constructed combined configuration. So variables can be used that point to properties that are defined in configuration sources loaded by this builder.- Overrides:
interpolate
in classAbstractConfiguration
- Parameters:
value
- the value to be interpolated- Returns:
- the interpolated value
-
-