Class MultiFileConfigurationBuilder<T extends FileBasedConfiguration>
- java.lang.Object
-
- org.apache.commons.configuration2.builder.BasicConfigurationBuilder<T>
-
- org.apache.commons.configuration2.builder.combined.MultiFileConfigurationBuilder<T>
-
- Type Parameters:
T
- the concrete type ofConfiguration
objects created by this builder
- All Implemented Interfaces:
ConfigurationBuilder<T>
,EventSource
- Direct Known Subclasses:
ReloadingMultiFileConfigurationBuilder
public class MultiFileConfigurationBuilder<T extends FileBasedConfiguration> extends BasicConfigurationBuilder<T>
A specialized
ConfigurationBuilder
implementation providing access to multiple file-based configurations based on a file name pattern.This builder class is initialized with a pattern string and a
ConfigurationInterpolator
object. Each time a configuration is requested, the pattern is evaluated against theConfigurationInterpolator
(so all variables are replaced by their current values). The resulting string is interpreted as a file name for a configuration file to be loaded. For example, providing a pattern of file:///opt/config/${product}/${client}/config.xml will result in product and client being resolved on every call. By storing configuration files in a corresponding directory structure, specialized configuration files associated with a specific product and client can be loaded. Thus an application can be made multi-tenant in a transparent way.This builder class keeps a map with configuration builders for configurations already loaded. The
getConfiguration()
method first evaluates the pattern string and checks whether a builder for the resulting file name is available. If yes, it is queried for its configuration. Otherwise, a new file-based configuration builder is created now and initialized.Configuration of an instance happens in the usual way for configuration builders. A
MultiFileBuilderParametersImpl
parameters object is expected which must contain a file name pattern string and aConfigurationInterpolator
. Other properties of this parameters object are used to initialize the builders for managed configurations.- Since:
- 2.0
-
-
Field Summary
Fields Modifier and Type Field Description private EventListenerList
configurationListeners
A list for the event listeners to be passed to managed builders.private java.lang.ThreadLocal<java.lang.Boolean>
inInterpolation
A flag for preventing reentrant access to managed builders on interpolation of the file name pattern.private java.util.concurrent.atomic.AtomicReference<ConfigurationInterpolator>
interpolator
Stores theConfigurationInterpolator
object.private static java.lang.String
KEY_INTERPOLATOR
Constant for the name of the key referencing theConfigurationInterpolator
in this builder's parameters.private EventListener<ConfigurationBuilderEvent>
managedBuilderDelegationListener
A specialized event listener which gets registered at all managed builders.private java.util.concurrent.ConcurrentMap<java.lang.String,FileBasedConfigurationBuilder<T>>
managedBuilders
A cache for already created managed builders.
-
Constructor Summary
Constructors Constructor Description MultiFileConfigurationBuilder(java.lang.Class<? extends T> resCls)
Creates a new instance ofMultiFileConfigurationBuilder
without setting initialization parameters.MultiFileConfigurationBuilder(java.lang.Class<? extends T> resCls, java.util.Map<java.lang.String,java.lang.Object> params)
Creates a new instance ofMultiFileConfigurationBuilder
and sets initialization parameters.MultiFileConfigurationBuilder(java.lang.Class<? extends T> resCls, java.util.Map<java.lang.String,java.lang.Object> params, boolean allowFailOnInit)
Creates a new instance ofMultiFileConfigurationBuilder
and sets initialization parameters and a flag whether initialization failures should be ignored.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description <E extends Event>
voidaddEventListener(EventType<E> eventType, EventListener<? super E> l)
Adds an event listener for the specified event type.MultiFileConfigurationBuilder<T>
configure(BuilderParameters... params)
Appends the content of the specifiedBuilderParameters
objects to the current initialization parameters.protected java.lang.String
constructFileName(MultiFileBuilderParametersImpl multiParams)
Determines the file name of a configuration based on the file name pattern.private ConfigurationBuilderEvent
createEventWithChangedSource(ConfigurationBuilderEvent event)
Creates a newConfigurationBuilderEvent
based on the passed in event, but with the source changed to this builder.protected FileBasedConfigurationBuilder<T>
createInitializedManagedBuilder(java.lang.String fileName, java.util.Map<java.lang.String,java.lang.Object> params)
Creates a fully initialized builder for a managed configuration.protected ConfigurationInterpolator
createInterpolator()
Creates theConfigurationInterpolator
to be used by this instance.protected FileBasedConfigurationBuilder<T>
createManagedBuilder(java.lang.String fileName, java.util.Map<java.lang.String,java.lang.Object> params)
Creates a builder for a managed configuration.private static java.util.Map<java.lang.String,java.lang.Object>
createManagedBuilderParameters(java.util.Map<java.lang.String,java.lang.Object> params, MultiFileBuilderParametersImpl multiParams)
Creates a map with parameters for a new managed configuration builder.private java.lang.String
fetchFileName(MultiFileBuilderParametersImpl multiParams)
Generates a file name for a managed builder based on the file name pattern.T
getConfiguration()
Gets the configuration provided by this builder.protected ConfigurationInterpolator
getInterpolator()
Gets theConfigurationInterpolator
used by this instance.FileBasedConfigurationBuilder<T>
getManagedBuilder()
Gets the managedFileBasedConfigurationBuilder
for the current file name pattern.protected java.util.concurrent.ConcurrentMap<java.lang.String,FileBasedConfigurationBuilder<T>>
getManagedBuilders()
Gets the map with the managed builders created so far by thisMultiFileConfigurationBuilder
.private void
handleManagedBuilderEvent(ConfigurationBuilderEvent event)
Handles events received from managed configuration builders.private void
initListeners(FileBasedConfigurationBuilder<T> newBuilder)
Registers event listeners at the passed in newly created managed builder.private static boolean
isEventTypeForManagedBuilders(EventType<?> eventType)
Checks whether the given event type is of interest for the managed configuration builders.<E extends Event>
booleanremoveEventListener(EventType<E> eventType, EventListener<? super E> l)
Removes the event listener registration for the given event type and listener.void
resetParameters()
Removes all initialization parameters of this builder.-
Methods inherited from class org.apache.commons.configuration2.builder.BasicConfigurationBuilder
addParameters, connectToReloadingController, copyEventListeners, copyEventListeners, createResult, createResultDeclaration, createResultInstance, fetchBeanHelper, fireBuilderEvent, getParameters, getResultClass, getResultDeclaration, initResultInstance, installEventListener, isAllowFailOnInit, reset, resetResult, setParameters
-
-
-
-
Field Detail
-
KEY_INTERPOLATOR
private static final java.lang.String KEY_INTERPOLATOR
Constant for the name of the key referencing theConfigurationInterpolator
in this builder's parameters.- See Also:
- Constant Field Values
-
managedBuilders
private final java.util.concurrent.ConcurrentMap<java.lang.String,FileBasedConfigurationBuilder<T extends FileBasedConfiguration>> managedBuilders
A cache for already created managed builders.
-
interpolator
private final java.util.concurrent.atomic.AtomicReference<ConfigurationInterpolator> interpolator
Stores theConfigurationInterpolator
object.
-
inInterpolation
private final java.lang.ThreadLocal<java.lang.Boolean> inInterpolation
A flag for preventing reentrant access to managed builders on interpolation of the file name pattern.
-
configurationListeners
private final EventListenerList configurationListeners
A list for the event listeners to be passed to managed builders.
-
managedBuilderDelegationListener
private final EventListener<ConfigurationBuilderEvent> managedBuilderDelegationListener
A specialized event listener which gets registered at all managed builders. This listener just propagates notifications from managed builders to the listeners registered at thisMultiFileConfigurationBuilder
.
-
-
Constructor Detail
-
MultiFileConfigurationBuilder
public MultiFileConfigurationBuilder(java.lang.Class<? extends T> resCls)
Creates a new instance ofMultiFileConfigurationBuilder
without setting initialization parameters.- Parameters:
resCls
- the result configuration class- Throws:
java.lang.IllegalArgumentException
- if the result class is null
-
MultiFileConfigurationBuilder
public MultiFileConfigurationBuilder(java.lang.Class<? extends T> resCls, java.util.Map<java.lang.String,java.lang.Object> params)
Creates a new instance ofMultiFileConfigurationBuilder
and sets initialization parameters.- Parameters:
resCls
- the result configuration classparams
- a map with initialization parameters- Throws:
java.lang.IllegalArgumentException
- if the result class is null
-
MultiFileConfigurationBuilder
public MultiFileConfigurationBuilder(java.lang.Class<? extends T> resCls, java.util.Map<java.lang.String,java.lang.Object> params, boolean allowFailOnInit)
Creates a new instance ofMultiFileConfigurationBuilder
and sets initialization parameters and a flag whether initialization failures should be ignored.- Parameters:
resCls
- the result configuration classparams
- a map with initialization parametersallowFailOnInit
- a flag whether initialization errors should be ignored- Throws:
java.lang.IllegalArgumentException
- if the result class is null
-
-
Method Detail
-
createManagedBuilderParameters
private static java.util.Map<java.lang.String,java.lang.Object> createManagedBuilderParameters(java.util.Map<java.lang.String,java.lang.Object> params, MultiFileBuilderParametersImpl multiParams)
Creates a map with parameters for a new managed configuration builder. This method merges the basic parameters set for this builder with the specific parameters object for managed builders (if provided).- Parameters:
params
- the parameters of this buildermultiParams
- the parameters object for this builder- Returns:
- the parameters for a new managed builder
-
isEventTypeForManagedBuilders
private static boolean isEventTypeForManagedBuilders(EventType<?> eventType)
Checks whether the given event type is of interest for the managed configuration builders. This method is called by the methods for managing event listeners to find out whether a listener should be passed to the managed builders, too.- Parameters:
eventType
- the event type object- Returns:
- a flag whether this event type is of interest for managed builders
-
addEventListener
public <E extends Event> void addEventListener(EventType<E> eventType, EventListener<? super E> l)
Adds an event listener for the specified event type. This listener is notified about events of this type and all its sub types. This implementation also takes care that the event listener is added to the managed configuration object. This implementation ensures that the listener is also added to managed configuration builders if necessary. Listeners for the builder-related event types are excluded because otherwise they would be triggered by the internally used configuration builders.- Specified by:
addEventListener
in interfaceEventSource
- Overrides:
addEventListener
in classBasicConfigurationBuilder<T extends FileBasedConfiguration>
- Type Parameters:
E
- the type of events processed by this listener- Parameters:
eventType
- the event type (must not be null)l
- the listener to be registered (must not be null)
-
configure
public MultiFileConfigurationBuilder<T> 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<T extends FileBasedConfiguration>
- Parameters:
params
- an arbitrary number of objects with builder parameters- Returns:
- a reference to this builder for method chaining
-
constructFileName
protected java.lang.String constructFileName(MultiFileBuilderParametersImpl multiParams)
Determines the file name of a configuration based on the file name pattern. This method is called on every access to this builder's configuration. It obtains theConfigurationInterpolator
from this builder's parameters and uses it to interpolate the file name pattern.- Parameters:
multiParams
- the parameters object for this builder- Returns:
- the name of the configuration file to be loaded
-
createEventWithChangedSource
private ConfigurationBuilderEvent createEventWithChangedSource(ConfigurationBuilderEvent event)
Creates a newConfigurationBuilderEvent
based on the passed in event, but with the source changed to this builder. This method is called when an event was received from a managed builder. In this case, the event has to be passed to the builder listeners registered at this object, but with the correct source property.- Parameters:
event
- the event received from a managed builder- Returns:
- the event to be propagated
-
createInitializedManagedBuilder
protected FileBasedConfigurationBuilder<T> createInitializedManagedBuilder(java.lang.String fileName, java.util.Map<java.lang.String,java.lang.Object> params) throws ConfigurationException
Creates a fully initialized builder for a managed configuration. This method is called bygetConfiguration()
whenever a configuration file is requested which has not yet been loaded. This implementation delegates tocreateManagedBuilder()
for actually creating the builder object. Then it sets the location to the configuration file.- Parameters:
fileName
- the name of the file to be loadedparams
- a map with initialization parameters for the new builder- Returns:
- the newly created and initialized builder instance
- Throws:
ConfigurationException
- if an error occurs
-
createInterpolator
protected ConfigurationInterpolator createInterpolator()
Creates theConfigurationInterpolator
to be used by this instance. This method is called when a file name is to be constructed, but no currentConfigurationInterpolator
instance is available. It obtains an instance from this builder's parameters. If no properties of theConfigurationInterpolator
are specified in the parameters, a default instance without lookups is returned (which is probably not very helpful).- Returns:
- the
ConfigurationInterpolator
to be used
-
createManagedBuilder
protected FileBasedConfigurationBuilder<T> createManagedBuilder(java.lang.String fileName, java.util.Map<java.lang.String,java.lang.Object> params) throws ConfigurationException
Creates a builder for a managed configuration. This method is called whenever a configuration for a file name is requested which has not yet been loaded. The passed in map with parameters is populated from this builder's configuration (i.e. the basic parameters plus the optional parameters for managed builders). This base implementation creates a standard builder for file-based configurations. Derived classes may override it to create special purpose builders.- Parameters:
fileName
- the name of the file to be loadedparams
- a map with initialization parameters for the new builder- Returns:
- the newly created builder instance
- Throws:
ConfigurationException
- if an error occurs
-
fetchFileName
private java.lang.String fetchFileName(MultiFileBuilderParametersImpl multiParams)
Generates a file name for a managed builder based on the file name pattern. This method prevents infinite loops which could happen if the file name pattern cannot be resolved and theConfigurationInterpolator
used by this object causes a recursive lookup to this builder's configuration.- Parameters:
multiParams
- the current builder parameters- Returns:
- the file name for a managed builder
-
getConfiguration
public T getConfiguration() throws ConfigurationException
Gets the configuration provided by this builder. An implementation has to perform all necessary steps for creating and initializing aImmutableConfiguration
object. This implementation creates the result configuration on first access. Later invocations return the same object until this builder is reset. The double-check idiom for lazy initialization is used (Bloch, Effective Java, item 71). This implementation evaluates the file name pattern using the configuredConfigurationInterpolator
. If this file has already been loaded, the corresponding builder is accessed. Otherwise, a new builder is created for loading this configuration file.- Specified by:
getConfiguration
in interfaceConfigurationBuilder<T extends FileBasedConfiguration>
- Overrides:
getConfiguration
in classBasicConfigurationBuilder<T extends FileBasedConfiguration>
- Returns:
- the configuration
- Throws:
ConfigurationException
- if an error occurs
-
getInterpolator
protected ConfigurationInterpolator getInterpolator()
Gets theConfigurationInterpolator
used by this instance. This is the object used for evaluating the file name pattern. It is created on demand.- Returns:
- the
ConfigurationInterpolator
-
getManagedBuilder
public FileBasedConfigurationBuilder<T> getManagedBuilder() throws ConfigurationException
Gets the managedFileBasedConfigurationBuilder
for the current file name pattern. It is determined based on the evaluation of the file name pattern using the configuredConfigurationInterpolator
. If this is the first access to this configuration file, the builder is created.- Returns:
- the configuration builder for the configuration corresponding to the current evaluation of the file name pattern
- Throws:
ConfigurationException
- if the builder cannot be determined (e.g. due to missing initialization parameters)
-
getManagedBuilders
protected java.util.concurrent.ConcurrentMap<java.lang.String,FileBasedConfigurationBuilder<T>> getManagedBuilders()
Gets the map with the managed builders created so far by thisMultiFileConfigurationBuilder
. This map is exposed to derived classes so they can access managed builders directly. However, derived classes are not expected to manipulate this map.- Returns:
- the map with the managed builders
-
handleManagedBuilderEvent
private void handleManagedBuilderEvent(ConfigurationBuilderEvent event)
Handles events received from managed configuration builders. This method creates a new event with a source pointing to this builder and propagates it to all registered listeners.- Parameters:
event
- the event received from a managed builder
-
initListeners
private void initListeners(FileBasedConfigurationBuilder<T> newBuilder)
Registers event listeners at the passed in newly created managed builder. This method registers a specialEventListener
which propagates builder events to listeners registered at this builder. In addition,ConfigurationListener
andConfigurationErrorListener
objects are registered at the new builder.- Parameters:
newBuilder
- the builder to be initialized
-
removeEventListener
public <E extends Event> boolean removeEventListener(EventType<E> eventType, EventListener<? super E> l)
Removes the event listener registration for the given event type and listener. An event listener instance may be registered multiple times for different event types. Therefore, when removing a listener the event type of the registration in question has to be specified. The return value indicates whether a registration was removed. A value of false means that no such combination of event type and listener was found. This implementation also takes care that the event listener is removed from the managed configuration object. This implementation ensures that the listener is also removed from managed configuration builders if necessary.- Specified by:
removeEventListener
in interfaceEventSource
- Overrides:
removeEventListener
in classBasicConfigurationBuilder<T extends FileBasedConfiguration>
- Type Parameters:
E
- the type of events processed by this listener- Parameters:
eventType
- the event typel
- the event listener to be removed- Returns:
- a flag whether a listener registration was removed
-
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 clears the cache with all managed builders.- Overrides:
resetParameters
in classBasicConfigurationBuilder<T extends FileBasedConfiguration>
-
-