Class CombinedConfigurationBuilder
- java.lang.Object
-
- org.apache.commons.configuration2.builder.BasicConfigurationBuilder<CombinedConfiguration>
-
- org.apache.commons.configuration2.builder.combined.CombinedConfigurationBuilder
-
- All Implemented Interfaces:
ConfigurationBuilder<CombinedConfiguration>
,EventSource
- Direct Known Subclasses:
ReloadingCombinedConfigurationBuilder
public class CombinedConfigurationBuilder extends BasicConfigurationBuilder<CombinedConfiguration>
A specialized
ConfigurationBuilder
implementation that creates aCombinedConfiguration
from multiple configuration sources defined by 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, a corresponding
ConfigurationBuilder
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 an implementation of
CombinedConfigurationBuilderProvider
has to be created which is responsible for the creation of aConfigurationBuilder
associated with the custom tag. An instance of this class has to be registered at theCombinedBuilderParametersImpl
object which is used to initialize thisCombinedConfigurationBuilder
. This provider will then be called when the corresponding custom tag is detected. For many 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 combined 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 optionalsystemProperties
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
CombinedConfigurationBuilderProvider
. This can be one of the predefined tags likeproperties
, orxml
, or a custom tag, for which a configuration builder provider was registered (as described above). 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:Standard attributes for configuration declarations Attribute Meaning config-name
Allows specifying a name for this configuration. This name can be used to obtain a reference to the configuration from the resulting combined configuration (see below). It can also be passed to the getNamedBuilder(String)
method.config-at
With this attribute an optional prefix can be specified for the properties of the corresponding configuration. config-optional
Declares a configuration source as optional. This means that errors that occur when creating the configuration are ignored. config-reload
Many configuration sources support a reloading mechanism. For those sources it is possible to enable reloading by providing this attribute with a value of true. 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. 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 actualCombinedConfiguration
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">
A specific CatalogResolver can be specified for all XMLConfiguration sources 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. ThegetNamedBuilder(String)
method can be used to access theConfigurationBuilder
objects for all configuration sources which have been assigned a name; care has to be taken that these names are unique.- Since:
- 1.3
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private class
CombinedConfigurationBuilder.ConfigurationSourceData
A data class for storing information about all configuration sources defined for a combined builder.
-
Field Summary
Fields Modifier and Type Field Description 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_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.(package private) static java.lang.String
ATTR_RELOAD
Constant for the reload attribute.private static java.lang.String
BASIC_BUILDER
Constant for the basic configuration builder class.private static BaseConfigurationBuilderProvider
COMBINED_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 CombinedConfiguration
currentConfiguration
The configuration that is currently constructed.private CombinedBuilderParametersImpl
currentParameters
Stores the current parameters object.private XMLBuilderParametersImpl
currentXMLParameters
The current XML parameters object.private static ConfigurationBuilderProvider[]
DEFAULT_PROVIDERS
An array with the providers for the default tags.private static java.util.Map<java.lang.String,ConfigurationBuilderProvider>
DEFAULT_PROVIDERS_MAP
A map with the default configuration builder providers.private static java.lang.String[]
DEFAULT_TAGS
An array with the names of the default tags.private ConfigurationBuilder<? extends HierarchicalConfiguration<?>>
definitionBuilder
The builder for the definition configuration.private HierarchicalConfiguration<?>
definitionConfiguration
Stores temporarily the configuration with the builder definitions.private static BaseConfigurationBuilderProvider
ENV_PROVIDER
Constant for the provider for environment properties.(package private) static java.lang.String
EXT_XML
Constant for the XML file extension.private static java.lang.String
FILE_BUILDER
Constant for the file-based configuration builder class.private static java.lang.String
FILE_PARAMS
Constant for the name of the file-based builder parameters class.(package private) static java.lang.String
FILE_SYSTEM
Constant for the FileSystem.private static BaseConfigurationBuilderProvider
INI_PROVIDER
Constant for the provider for ini files.private static BaseConfigurationBuilderProvider
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_CONFIGURATION_LOOKUPS
Constant for the key for defining variable resolvers(package private) static java.lang.String
KEY_CONFIGURATION_PROVIDERS
Constant for the key for defining providers in the configuration file.(package private) static java.lang.String
KEY_ENTITY_RESOLVER
Constant for the key for defining entity resolvers(package private) static java.lang.String
KEY_LOOKUP_KEY
Constant for the prefix attribute for lookups.(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_PROVIDER_KEY
Constant for the tag attribute for providers.(package private) static java.lang.String
KEY_RESULT
Constant for the key of the result declaration.(package private) static java.lang.String
KEY_SYSTEM_PROPS
Constant for the tag attribute for providers.(package private) static java.lang.String
KEY_UNION
Constant for an expression that selects the union configurations.private static MultiFileConfigurationBuilderProvider
MULTI_XML_PROVIDER
Constant for the provider for multiple XML configurations.private ConfigurationInterpolator
parentInterpolator
AConfigurationInterpolator
to be used as parent for all child configurations to enable cross-source interpolation.private static BaseConfigurationBuilderProvider
PLIST_PROVIDER
Constant for the provider for plist files.private static ConfigurationBuilderProvider
PROPERTIES_PROVIDER
Constant for the provider for properties files.private static java.lang.String
RELOADING_BUILDER
Constant for the reloading file-based configuration builder class.(package private) static java.lang.String
SEC_HEADER
Constant for the name of the header section.private CombinedConfigurationBuilder.ConfigurationSourceData
sourceData
The object with data about configuration sources.private static BaseConfigurationBuilderProvider
SYSTEM_PROVIDER
Constant for the provider for system properties.private static ConfigurationBuilderProvider
XML_PROVIDER
Constant for the provider for XML files.
-
Constructor Summary
Constructors Constructor Description CombinedConfigurationBuilder()
Creates a new instance ofCombinedConfigurationBuilder
.CombinedConfigurationBuilder(java.util.Map<java.lang.String,java.lang.Object> params)
Creates a new instance ofCombinedConfigurationBuilder
and sets the specified initialization parameters.CombinedConfigurationBuilder(java.util.Map<java.lang.String,java.lang.Object> params, boolean allowFailOnInit)
Creates a new instance ofCombinedConfigurationBuilder
and sets the specified initialization parameters and the allowFailOnInit flag.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description private void
addDefinitionBuilderChangeListener(ConfigurationBuilder<? extends HierarchicalConfiguration<?>> defBuilder)
Adds a listener at the given definition builder which resets this builder when a reset of the definition builder happens.java.util.Set<java.lang.String>
builderNames()
Returns a set with the names of all child configuration builders.CombinedConfigurationBuilder
configure(BuilderParameters... params)
Appends the content of the specifiedBuilderParameters
objects to the current initialization parameters.protected void
configureEntityResolver(HierarchicalConfiguration<?> config, XMLBuilderParametersImpl xmlParams)
Creates and initializes a defaultEntityResolver
if the definition configuration contains a corresponding declaration.protected CombinedConfiguration
createAdditionalsConfiguration(CombinedConfiguration resultConfig)
Creates theCombinedConfiguration
for the configuration sources in the<additional>
section.private java.util.Collection<ConfigurationDeclaration>
createDeclarations(java.util.Collection<? extends HierarchicalConfiguration<?>> configs)
CreatesConfigurationDeclaration
objects for the specified configurations.private static java.util.Map<java.lang.String,ConfigurationBuilderProvider>
createDefaultProviders()
Creates the map with the default configuration builder providers.protected BeanDeclaration
createResultDeclaration(java.util.Map<java.lang.String,java.lang.Object> params)
Creates a newBeanDeclaration
which is used for creating new result objects dynamically.private CombinedConfigurationBuilder.ConfigurationSourceData
createSourceData()
Creates the data object for configuration sources and the corresponding builders.protected ConfigurationBuilder<? extends HierarchicalConfiguration<?>>
createXMLDefinitionBuilder(BuilderParameters builderParams)
Creates a default builder for the definition configuration and initializes it with a parameters object.private java.util.Map<java.lang.String,? extends Lookup>
fetchPrefixLookups()
Returns a map with the current prefix lookup objects.private java.lang.String
getBasePath()
Gets the current base path of this configuration builder.protected java.util.Collection<ConfigurationBuilder<? extends Configuration>>
getChildBuilders()
Gets a collection with the builders for all child configuration sources.(package private) CombinedConfiguration
getConfigurationUnderConstruction()
Gets the configuration object that is currently constructed.ConfigurationBuilder<? extends HierarchicalConfiguration<?>>
getDefinitionBuilder()
Gets theConfigurationBuilder
which creates the definition configuration.protected HierarchicalConfiguration<?>
getDefinitionConfiguration()
Gets the configuration containing the definition of the combined configuration to be created.ConfigurationBuilder<? extends Configuration>
getNamedBuilder(java.lang.String name)
Gets the configuration builder with the given name.private CombinedConfigurationBuilder.ConfigurationSourceData
getSourceData()
Obtains the data object for the configuration sources and the corresponding builders.(package private) void
initBean(java.lang.Object bean, BeanDeclaration decl)
Initializes a bean using the currentBeanHelper
.private void
initChildBasicParameters(BasicBuilderParameters params)
Initializes basic builder parameters for a child configuration with default settings set for this builder.protected void
initChildBuilderParameters(BuilderParameters params)
Initializes a parameters object for a child builder.private void
initChildCombinedParameters(CombinedBuilderParametersImpl params)
Initializes a parameters object for a combined configuration builder with properties already set for this parent builder.(package private) void
initChildEventListeners(BasicConfigurationBuilder<? extends Configuration> dest)
Initializes the event listeners of the specified builder from this object.private void
initChildFileBasedParameters(FileBasedBuilderProperties<?> params)
Initializes a parameters object for a file-based configuration with properties already set for this parent builder.private void
initChildXMLParameters(XMLBuilderProperties<?> params)
Initializes a parameters object for an XML configuration with properties already set for this parent builder.private void
initDefaultBasePath()
Initializes the default base path for all file-based child configuration sources.private void
initDefaultChildParameters(BuilderParameters params)
Executes theDefaultParametersManager
stored in the current parameters on the passed in parameters object.protected FileSystem
initFileSystem(HierarchicalConfiguration<?> config)
Creates and initializes a defaultFileSystem
if the definition configuration contains a corresponding declaration.private static void
initNodeCombinerListNodes(CombinedConfiguration cc, HierarchicalConfiguration<?> defConfig, java.lang.String key)
Initializes the list nodes of the node combiner for the given combined configuration.protected void
initResultInstance(CombinedConfiguration result)
Initializes a newly created result object.protected void
initSystemProperties(HierarchicalConfiguration<?> config, java.lang.String basePath)
Handles a file with system properties that may be defined in the definition configuration.protected ConfigurationBuilderProvider
providerForTag(java.lang.String tagName)
Returns theConfigurationBuilderProvider
for the given tag.protected void
registerConfiguredLookups(HierarchicalConfiguration<?> defConfig, Configuration resultConfig)
Processes customLookup
objects that might be declared in the definition configuration.private void
registerConfiguredProviders(HierarchicalConfiguration<?> defConfig)
Registers providers defined in the configuration.void
resetParameters()
Removes all initialization parameters of this builder.private void
setUpCurrentParameters()
Initializes the current parameters object.private void
setUpCurrentXMLParameters()
Sets up an XML parameters object which is used to store properties related to XML and file-based configurations during creation of the result configuration.protected ConfigurationBuilder<? extends HierarchicalConfiguration<?>>
setupDefinitionBuilder(java.util.Map<java.lang.String,java.lang.Object> params)
Obtains theConfigurationBuilder
object which provides access to the configuration containing the definition of the combined configuration to create.private void
setUpParentInterpolator(Configuration resultConfig, Configuration defConfig)
Sets up a parentConfigurationInterpolator
object.-
Methods inherited from class org.apache.commons.configuration2.builder.BasicConfigurationBuilder
addEventListener, addParameters, connectToReloadingController, copyEventListeners, copyEventListeners, createResult, createResultInstance, fetchBeanHelper, fireBuilderEvent, getConfiguration, getParameters, getResultClass, getResultDeclaration, installEventListener, isAllowFailOnInit, removeEventListener, reset, resetResult, setParameters
-
-
-
-
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.
-
CONFIG_BEAN_FACTORY_NAME
static final java.lang.String CONFIG_BEAN_FACTORY_NAME
Constant for the name of the configuration bean factory.
-
ATTR_NAME
static final java.lang.String ATTR_NAME
Constant for the reserved name attribute.- See Also:
- Constant Field Values
-
ATTR_ATNAME
static final java.lang.String ATTR_ATNAME
Constant for the name of the at attribute.- See Also:
- Constant Field Values
-
ATTR_AT_RES
static final java.lang.String ATTR_AT_RES
Constant for the reserved at attribute.- See Also:
- Constant Field Values
-
ATTR_AT
static final java.lang.String ATTR_AT
Constant for the at attribute without the reserved prefix.- See Also:
- Constant Field Values
-
ATTR_OPTIONALNAME
static final java.lang.String ATTR_OPTIONALNAME
Constant for the name of the optional attribute.- See Also:
- Constant Field Values
-
ATTR_OPTIONAL_RES
static final java.lang.String ATTR_OPTIONAL_RES
Constant for the reserved optional attribute.- See Also:
- Constant Field Values
-
ATTR_OPTIONAL
static final java.lang.String ATTR_OPTIONAL
Constant for the optional attribute without the reserved prefix.- See Also:
- Constant Field Values
-
ATTR_FORCECREATE
static final java.lang.String ATTR_FORCECREATE
Constant for the forceCreate attribute.- See Also:
- Constant Field Values
-
ATTR_RELOAD
static final java.lang.String ATTR_RELOAD
Constant for the reload attribute.- See Also:
- Constant Field Values
-
KEY_SYSTEM_PROPS
static final java.lang.String KEY_SYSTEM_PROPS
Constant for the tag attribute for providers.- See Also:
- Constant Field Values
-
SEC_HEADER
static final java.lang.String SEC_HEADER
Constant for the name of the header section.- See Also:
- Constant Field Values
-
KEY_UNION
static final java.lang.String KEY_UNION
Constant for an expression that selects the union configurations.- See Also:
- Constant Field Values
-
CONFIG_SECTIONS
static final java.lang.String[] CONFIG_SECTIONS
An array with the names of top level configuration sections.
-
KEY_OVERRIDE
static final java.lang.String KEY_OVERRIDE
Constant for an expression that selects override configurations in the override section.- See Also:
- Constant Field Values
-
KEY_OVERRIDE_LIST
static final java.lang.String KEY_OVERRIDE_LIST
Constant for the key that points to the list nodes definition of the override combiner.- See Also:
- Constant Field Values
-
KEY_ADDITIONAL_LIST
static final java.lang.String KEY_ADDITIONAL_LIST
Constant for the key that points to the list nodes definition of the additional combiner.- See Also:
- Constant Field Values
-
KEY_CONFIGURATION_PROVIDERS
static final java.lang.String KEY_CONFIGURATION_PROVIDERS
Constant for the key for defining providers in the configuration file.- See Also:
- Constant Field Values
-
KEY_PROVIDER_KEY
static final java.lang.String KEY_PROVIDER_KEY
Constant for the tag attribute for providers.- See Also:
- Constant Field Values
-
KEY_CONFIGURATION_LOOKUPS
static final java.lang.String KEY_CONFIGURATION_LOOKUPS
Constant for the key for defining variable resolvers- See Also:
- Constant Field Values
-
KEY_ENTITY_RESOLVER
static final java.lang.String KEY_ENTITY_RESOLVER
Constant for the key for defining entity resolvers- See Also:
- Constant Field Values
-
KEY_LOOKUP_KEY
static final java.lang.String KEY_LOOKUP_KEY
Constant for the prefix attribute for lookups.- See Also:
- Constant Field Values
-
FILE_SYSTEM
static final java.lang.String FILE_SYSTEM
Constant for the FileSystem.- See Also:
- Constant Field Values
-
KEY_RESULT
static final java.lang.String KEY_RESULT
Constant for the key of the result declaration. This key can point to a bean declaration, which defines properties of the resulting combined configuration.- See Also:
- Constant Field Values
-
KEY_COMBINER
static final java.lang.String KEY_COMBINER
Constant for the key of the combiner in the result declaration.- See Also:
- Constant Field Values
-
EXT_XML
static final java.lang.String EXT_XML
Constant for the XML file extension.- See Also:
- Constant Field Values
-
BASIC_BUILDER
private static final java.lang.String BASIC_BUILDER
Constant for the basic configuration builder class.- See Also:
- Constant Field Values
-
FILE_BUILDER
private static final java.lang.String FILE_BUILDER
Constant for the file-based configuration builder class.- See Also:
- Constant Field Values
-
RELOADING_BUILDER
private static final java.lang.String RELOADING_BUILDER
Constant for the reloading file-based configuration builder class.- See Also:
- Constant Field Values
-
FILE_PARAMS
private static final java.lang.String FILE_PARAMS
Constant for the name of the file-based builder parameters class.- See Also:
- Constant Field Values
-
PROPERTIES_PROVIDER
private static final ConfigurationBuilderProvider PROPERTIES_PROVIDER
Constant for the provider for properties files.
-
XML_PROVIDER
private static final ConfigurationBuilderProvider XML_PROVIDER
Constant for the provider for XML files.
-
JNDI_PROVIDER
private static final BaseConfigurationBuilderProvider JNDI_PROVIDER
Constant for the provider for JNDI sources.
-
SYSTEM_PROVIDER
private static final BaseConfigurationBuilderProvider SYSTEM_PROVIDER
Constant for the provider for system properties.
-
INI_PROVIDER
private static final BaseConfigurationBuilderProvider INI_PROVIDER
Constant for the provider for ini files.
-
ENV_PROVIDER
private static final BaseConfigurationBuilderProvider ENV_PROVIDER
Constant for the provider for environment properties.
-
PLIST_PROVIDER
private static final BaseConfigurationBuilderProvider PLIST_PROVIDER
Constant for the provider for plist files.
-
COMBINED_PROVIDER
private static final BaseConfigurationBuilderProvider COMBINED_PROVIDER
Constant for the provider for configuration definition files.
-
MULTI_XML_PROVIDER
private static final MultiFileConfigurationBuilderProvider MULTI_XML_PROVIDER
Constant for the provider for multiple XML configurations.
-
DEFAULT_TAGS
private static final java.lang.String[] DEFAULT_TAGS
An array with the names of the default tags.
-
DEFAULT_PROVIDERS
private static final ConfigurationBuilderProvider[] DEFAULT_PROVIDERS
An array with the providers for the default tags.
-
DEFAULT_PROVIDERS_MAP
private static final java.util.Map<java.lang.String,ConfigurationBuilderProvider> DEFAULT_PROVIDERS_MAP
A map with the default configuration builder providers.
-
definitionBuilder
private ConfigurationBuilder<? extends HierarchicalConfiguration<?>> definitionBuilder
The builder for the definition configuration.
-
definitionConfiguration
private HierarchicalConfiguration<?> definitionConfiguration
Stores temporarily the configuration with the builder definitions.
-
sourceData
private CombinedConfigurationBuilder.ConfigurationSourceData sourceData
The object with data about configuration sources.
-
currentParameters
private CombinedBuilderParametersImpl currentParameters
Stores the current parameters object.
-
currentXMLParameters
private XMLBuilderParametersImpl currentXMLParameters
The current XML parameters object.
-
currentConfiguration
private CombinedConfiguration currentConfiguration
The configuration that is currently constructed.
-
parentInterpolator
private ConfigurationInterpolator parentInterpolator
AConfigurationInterpolator
to be used as parent for all child configurations to enable cross-source interpolation.
-
-
Constructor Detail
-
CombinedConfigurationBuilder
public CombinedConfigurationBuilder()
Creates a new instance ofCombinedConfigurationBuilder
. No parameters are set.
-
CombinedConfigurationBuilder
public CombinedConfigurationBuilder(java.util.Map<java.lang.String,java.lang.Object> params)
Creates a new instance ofCombinedConfigurationBuilder
and sets the specified initialization parameters.- Parameters:
params
- a map with initialization parameters
-
CombinedConfigurationBuilder
public CombinedConfigurationBuilder(java.util.Map<java.lang.String,java.lang.Object> params, boolean allowFailOnInit)
Creates a new instance ofCombinedConfigurationBuilder
and sets the specified initialization parameters and the allowFailOnInit flag.- Parameters:
params
- a map with initialization parametersallowFailOnInit
- the allowFailOnInit flag
-
-
Method Detail
-
createDefaultProviders
private static java.util.Map<java.lang.String,ConfigurationBuilderProvider> createDefaultProviders()
Creates the map with the default configuration builder providers.- Returns:
- the map with default providers
-
initNodeCombinerListNodes
private static void initNodeCombinerListNodes(CombinedConfiguration cc, HierarchicalConfiguration<?> defConfig, java.lang.String key)
Initializes the list nodes of the node combiner for the given combined configuration. This information can be set in the header section of the configuration definition file for both the override and the union combiners.- Parameters:
cc
- the combined configuration to initializedefConfig
- the definition configurationkey
- the key for the list nodes
-
addDefinitionBuilderChangeListener
private void addDefinitionBuilderChangeListener(ConfigurationBuilder<? extends HierarchicalConfiguration<?>> defBuilder)
Adds a listener at the given definition builder which resets this builder when a reset of the definition builder happens. This way it is ensured that this builder produces a new combined configuration when its definition configuration changes.- Parameters:
defBuilder
- the definition builder
-
builderNames
public java.util.Set<java.lang.String> builderNames()
Returns a set with the names of all child configuration builders. A tag defining a configuration source in the configuration definition file can have the
config-name
attribute. If this attribute is present, the corresponding builder is assigned this name and can be directly accessed through thegetNamedBuilder(String)
method. This method returns a collection with all available builder names.Important note: This method only returns a meaningful result after the result configuration has been created by calling
getConfiguration()
. If called before, always an empty set is returned.- Returns:
- a set with the names of all builders
-
configure
public CombinedConfigurationBuilder configure(BuilderParameters... params)
Appends the content of the specifiedBuilderParameters
objects to the current initialization parameters. Calling this method multiple times will create a union of the parameters provided. This method is overridden to adapt the return type.- Overrides:
configure
in classBasicConfigurationBuilder<CombinedConfiguration>
- Parameters:
params
- an arbitrary number of objects with builder parameters- Returns:
- a reference to this builder for method chaining
-
configureEntityResolver
protected void configureEntityResolver(HierarchicalConfiguration<?> config, XMLBuilderParametersImpl xmlParams) throws ConfigurationException
Creates and initializes a defaultEntityResolver
if the definition configuration contains a corresponding declaration.- Parameters:
config
- the definition configurationxmlParams
- the (already partly initialized) object with XML parameters; here the new resolver is to be stored- 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
-
createDeclarations
private java.util.Collection<ConfigurationDeclaration> createDeclarations(java.util.Collection<? extends HierarchicalConfiguration<?>> configs)
CreatesConfigurationDeclaration
objects for the specified configurations.- Parameters:
configs
- the list with configurations- Returns:
- a collection with corresponding declarations
-
createResultDeclaration
protected BeanDeclaration createResultDeclaration(java.util.Map<java.lang.String,java.lang.Object> params) throws ConfigurationException
Creates a newBeanDeclaration
which is used for creating new result objects dynamically. This implementation creates a specializedBeanDeclaration
object that is initialized from the given map of initialization parameters. TheBeanDeclaration
must be initialized with the result class of this builder, otherwise exceptions will be thrown when the result object is created. Note: This method is invoked in a synchronized block. This implementation evaluates theresult
property of the definition configuration. It creates a combined bean declaration with both the properties specified in the definition file and the properties defined as initialization parameters.- Overrides:
createResultDeclaration
in classBasicConfigurationBuilder<CombinedConfiguration>
- Parameters:
params
- a snapshot of the current initialization parameters- Returns:
- the
BeanDeclaration
for creating result objects - Throws:
ConfigurationException
- if an error occurs
-
createSourceData
private CombinedConfigurationBuilder.ConfigurationSourceData createSourceData() throws ConfigurationException
Creates the data object for configuration sources and the corresponding builders.- Returns:
- the newly created data object
- Throws:
ConfigurationException
- if an error occurs
-
createXMLDefinitionBuilder
protected ConfigurationBuilder<? extends HierarchicalConfiguration<?>> createXMLDefinitionBuilder(BuilderParameters builderParams)
Creates a default builder for the definition configuration and initializes it with a parameters object. This method is called if no definition builder is defined in this builder's parameters. This implementation creates a default file-based builder which produces anXMLConfiguration
; it expects a corresponding file specification. Note: This method is called in a synchronized block.- Parameters:
builderParams
- the parameters object for the builder- Returns:
- the standard builder for the definition configuration
-
fetchPrefixLookups
private java.util.Map<java.lang.String,? extends Lookup> fetchPrefixLookups()
Returns a map with the current prefix lookup objects. This map is obtained from theConfigurationInterpolator
of the configuration under construction.- Returns:
- the map with current prefix lookups (may be null)
-
getBasePath
private java.lang.String getBasePath()
Gets the current base path of this configuration builder. This is used for instance by all file-based child configurations.- Returns:
- the base path
-
getChildBuilders
protected java.util.Collection<ConfigurationBuilder<? extends Configuration>> getChildBuilders()
Gets a collection with the builders for all child configuration sources. This method can be used by derived classes providing additional functionality on top of the declared configuration sources. It only returns a defined value during construction of the result configuration instance.- Returns:
- a collection with the builders for child configuration sources
-
getConfigurationUnderConstruction
CombinedConfiguration getConfigurationUnderConstruction()
Gets the configuration object that is currently constructed. This method can be called during construction of the result configuration. It is intended for internal usage, e.g. some specialized builder providers need access to this configuration to perform advanced initialization.- Returns:
- the configuration that us currently under construction
-
getDefinitionBuilder
public ConfigurationBuilder<? extends HierarchicalConfiguration<?>> getDefinitionBuilder() throws ConfigurationException
Gets theConfigurationBuilder
which creates the definition configuration.- Returns:
- the builder for the definition configuration
- Throws:
ConfigurationException
- if an error occurs
-
getDefinitionConfiguration
protected HierarchicalConfiguration<?> getDefinitionConfiguration() throws ConfigurationException
Gets the configuration containing the definition of the combined configuration to be created. This method only returns a defined result during construction of the result configuration. The definition configuration is obtained from the definition builder at first access and then stored temporarily to ensure that during result construction always the same configuration instance is used. (Otherwise, it would be possible that the definition builder returns a different instance when queried multiple times.)- Returns:
- the definition configuration
- Throws:
ConfigurationException
- if an error occurs
-
getNamedBuilder
public ConfigurationBuilder<? extends Configuration> getNamedBuilder(java.lang.String name) throws ConfigurationException
Gets the configuration builder with the given name. With this method a builder of a child configuration which was given a name in the configuration definition file can be accessed directly.
Important note: This method only returns a meaningful result after the result configuration has been created by calling
getConfiguration()
. If called before, always an exception is thrown.- Parameters:
name
- the name of the builder in question- Returns:
- the child configuration builder with this name
- Throws:
ConfigurationException
- if information about named builders is not yet available or no builder with this name exists
-
getSourceData
private CombinedConfigurationBuilder.ConfigurationSourceData getSourceData() throws ConfigurationException
Obtains the data object for the configuration sources and the corresponding builders. This object is created on first access and reset when the definition builder sends a change event. This method is called in a synchronized block.- Returns:
- the object with information about configuration sources
- Throws:
ConfigurationException
- if an error occurs
-
initBean
void initBean(java.lang.Object bean, BeanDeclaration decl)
Initializes a bean using the currentBeanHelper
. This is needed by builder providers when the configuration objects for sub builders are constructed.- Parameters:
bean
- the bean to be initializeddecl
- theBeanDeclaration
-
initChildBasicParameters
private void initChildBasicParameters(BasicBuilderParameters params)
Initializes basic builder parameters for a child configuration with default settings set for this builder. This implementation ensures that allLookup
objects are propagated to child configurations and interpolation is setup correctly.- Parameters:
params
- the parameters object
-
initChildBuilderParameters
protected void initChildBuilderParameters(BuilderParameters params)
Initializes a parameters object for a child builder. This combined configuration builder has a bunch of properties which may be inherited by child configurations, e.g. the base path, the file system, etc. While processing the builders for child configurations, this method is called for each parameters object for a child builder. It initializes some properties of the passed in parameters objects which are derived from this parent builder.- Parameters:
params
- the parameters object to be initialized
-
initChildCombinedParameters
private void initChildCombinedParameters(CombinedBuilderParametersImpl params)
Initializes a parameters object for a combined configuration builder with properties already set for this parent builder. This implementation deals only with a subset of properties. Other properties are already handled by the specialized builder provider.- Parameters:
params
- the parameters object
-
initChildEventListeners
void initChildEventListeners(BasicConfigurationBuilder<? extends Configuration> dest)
Initializes the event listeners of the specified builder from this object. This method is used to inherit all listeners from a parent builder.- Parameters:
dest
- the destination builder object which is to be initialized
-
initChildFileBasedParameters
private void initChildFileBasedParameters(FileBasedBuilderProperties<?> params)
Initializes a parameters object for a file-based configuration with properties already set for this parent builder. This method handles properties like a default file system or a base path.- Parameters:
params
- the parameters object
-
initChildXMLParameters
private void initChildXMLParameters(XMLBuilderProperties<?> params)
Initializes a parameters object for an XML configuration with properties already set for this parent builder.- Parameters:
params
- the parameters object
-
initDefaultBasePath
private void initDefaultBasePath() throws ConfigurationException
Initializes the default base path for all file-based child configuration sources. The base path can be explicitly defined in the parameters of this builder. Otherwise, if the definition builder is a file-based builder, it is obtained from there.- Throws:
ConfigurationException
- if an error occurs
-
initDefaultChildParameters
private void initDefaultChildParameters(BuilderParameters params)
Executes theDefaultParametersManager
stored in the current parameters on the passed in parameters object. If default handlers have been registered for this type of parameters, an initialization is now performed. This method is called before the parameters object is initialized from the configuration definition file. So default values can be overridden later with concrete property definitions.- Parameters:
params
- the parameters to be initialized- Throws:
ConfigurationRuntimeException
- if an error occurs when copying properties
-
initFileSystem
protected FileSystem initFileSystem(HierarchicalConfiguration<?> config) throws ConfigurationException
Creates and initializes a defaultFileSystem
if the definition configuration contains a corresponding declaration. The file system returned by this method is used as default for all file-based child configuration sources.- Parameters:
config
- the definition configuration- Returns:
- the default
FileSystem
(may be null) - Throws:
ConfigurationException
- if an error occurs
-
initResultInstance
protected void initResultInstance(CombinedConfiguration result) throws ConfigurationException
Initializes a newly created result object. This is the second step of the process of producing a result object for this builder. This implementation uses theBeanHelper
class to initialize the object's property based on theBeanDeclaration
returned byBasicConfigurationBuilder.getResultDeclaration()
. Note: This method is invoked in a synchronized block. This is required because internal state is accessed. Sub classes must not call this method without proper synchronization. This implementation processes the definition configuration in order to- initialize the resulting
CombinedConfiguration
- determine the builders for all configuration sources
- populate the resulting
CombinedConfiguration
- Overrides:
initResultInstance
in classBasicConfigurationBuilder<CombinedConfiguration>
- Parameters:
result
- the object to be initialized- Throws:
ConfigurationException
- if an error occurs
- initialize the resulting
-
initSystemProperties
protected void initSystemProperties(HierarchicalConfiguration<?> config, java.lang.String basePath) throws ConfigurationException
Handles a file with system properties that may be defined in the definition configuration. If such property file is configured, all of its properties are added to the system properties.- Parameters:
config
- the definition configurationbasePath
- the base path defined for this builder (may be null)- Throws:
ConfigurationException
- if an error occurs.
-
providerForTag
protected ConfigurationBuilderProvider providerForTag(java.lang.String tagName)
Returns theConfigurationBuilderProvider
for the given tag. This method is called during creation of the result configuration. (It is not allowed to call it at another point of time; result is then unpredictable!) It supports all default providers and custom providers added through the parameters object as well.- Parameters:
tagName
- the name of the tag- Returns:
- the provider that was registered for this tag or null if there is none
-
registerConfiguredLookups
protected void registerConfiguredLookups(HierarchicalConfiguration<?> defConfig, Configuration resultConfig) throws ConfigurationException
Processes customLookup
objects that might be declared in the definition configuration. EachLookup
object is registered at the definition configuration and at the result configuration. It is also added to all child configurations added to the resulting combined configuration.- Parameters:
defConfig
- the definition configurationresultConfig
- the resulting configuration- Throws:
ConfigurationException
- if an error occurs
-
registerConfiguredProviders
private void registerConfiguredProviders(HierarchicalConfiguration<?> defConfig)
Registers providers defined in the configuration.- Parameters:
defConfig
- the definition configuration
-
resetParameters
public void resetParameters()
Removes all initialization parameters of this builder. This method can be called if this builder is to be reused for creating result objects with a different configuration. This implementation resets some specific internal state of this builder.- Overrides:
resetParameters
in classBasicConfigurationBuilder<CombinedConfiguration>
-
setUpCurrentParameters
private void setUpCurrentParameters()
Initializes the current parameters object. This object has either been passed at builder configuration time or it is newly created. In any case, it is manipulated during result creation.
-
setUpCurrentXMLParameters
private void setUpCurrentXMLParameters() throws ConfigurationException
Sets up an XML parameters object which is used to store properties related to XML and file-based configurations during creation of the result configuration. The properties stored in this object can be inherited to child configurations.- Throws:
ConfigurationException
- if an error occurs
-
setupDefinitionBuilder
protected ConfigurationBuilder<? extends HierarchicalConfiguration<?>> setupDefinitionBuilder(java.util.Map<java.lang.String,java.lang.Object> params) throws ConfigurationException
Obtains theConfigurationBuilder
object which provides access to the configuration containing the definition of the combined configuration to create. If a definition builder is defined in the parameters, it is used. Otherwise, we check whether the combined builder parameters object contains a parameters object for the definition builder. If this is the case, a builder for anXMLConfiguration
is created and configured with this object. As a last resort, it is looked for aFileBasedBuilderParametersImpl
object in the properties. If found, also a XML configuration builder is created which loads this file. Note: This method is called from a synchronized block.- Parameters:
params
- the current parameters for this builder- Returns:
- the builder for the definition configuration
- Throws:
ConfigurationException
- if an error occurs
-
setUpParentInterpolator
private void setUpParentInterpolator(Configuration resultConfig, Configuration defConfig)
Sets up a parentConfigurationInterpolator
object. This object has a defaultLookup
querying the resulting combined configuration. Thus interpolation works globally across all configuration sources.- Parameters:
resultConfig
- the result configurationdefConfig
- the definition configuration
-
-