Class BasicConfigurationBuilder<T extends ImmutableConfiguration>
- java.lang.Object
-
- org.apache.commons.configuration2.builder.BasicConfigurationBuilder<T>
-
- Type Parameters:
T
- the concrete type ofImmutableConfiguration
objects created by this builder
- All Implemented Interfaces:
ConfigurationBuilder<T>
,EventSource
- Direct Known Subclasses:
CombinedConfigurationBuilder
,FileBasedConfigurationBuilder
,MultiFileConfigurationBuilder
public class BasicConfigurationBuilder<T extends ImmutableConfiguration> extends java.lang.Object implements ConfigurationBuilder<T>
An implementation of the
ConfigurationBuilder
interface which is able to create different concreteImmutableConfiguration
implementations based on reflection.When constructing an instance of this class the concrete
ImmutableConfiguration
implementation class has to be provided. Then properties for the newImmutableConfiguration
instance can be set. The first call togetConfiguration()
creates and initializes the newImmutableConfiguration
object. It is cached and returned by subsequent calls. This cache - and also the initialization properties set so far - can be flushed by calling one of thereset()
methods. That way otherImmutableConfiguration
instances with different properties can be created.If the newly created
ImmutableConfiguration
object implements theInitializable
interface, itsinitialize()
method is called after all initialization properties have been set. This way a concrete implementation class can perform arbitrary initialization steps.There are multiple options for setting up a
BasicConfigurationBuilder
instance:- All initialization properties can be set in one or multiple calls of the
configure()
method. In each call an arbitrary number ofBuilderParameters
objects can be passed. The API allows method chaining and is intended to be used from Java code. - If builder instances are created by other means - e.g. using a dependency
injection framework -, the fluent API approach may not be suitable. For those
use cases it is also possible to pass in all initialization parameters as a
map. The keys of the map have to match initialization properties of the
ImmutableConfiguration
object to be created, the values are the corresponding property values. For instance, the key throwExceptionOnMissing in the map will cause the methodsetThrowExceptionOnMissing()
on theImmutableConfiguration
object to be called with the corresponding value as parameter.
A builder instance can be constructed with an allowFailOnInit flag. If set to true, exceptions during initialization of the configuration are ignored; in such a case an empty configuration object is returned. A use case for this flag is a scenario in which a configuration is optional and created on demand the first time configuration data is to be stored. Consider an application that stores user-specific configuration data in the user's home directory: When started for the first time by a new user there is no configuration file; so it makes sense to start with an empty configuration object. On application exit, settings can be stored in this object and written to the associated file. Then they are available on next application start.
This class is thread-safe. Multiple threads can modify initialization properties and call
getConfiguration()
. However, the intended use case is that the builder is configured by a single thread first. ThengetConfiguration()
can be called concurrently, and it is guaranteed that always the sameImmutableConfiguration
instance is returned until the builder is reset.- Since:
- 2.0
-
-
Constructor Summary
Constructors Constructor Description BasicConfigurationBuilder(java.lang.Class<? extends T> resCls)
Creates a new instance ofBasicConfigurationBuilder
and initializes it with the given result class.BasicConfigurationBuilder(java.lang.Class<? extends T> resCls, java.util.Map<java.lang.String,java.lang.Object> params)
Creates a new instance ofBasicConfigurationBuilder
and initializes it with the given result class and an initial set of builder parameters.BasicConfigurationBuilder(java.lang.Class<? extends T> resCls, java.util.Map<java.lang.String,java.lang.Object> params, boolean allowFailOnInit)
Creates a new instance ofBasicConfigurationBuilder
and initializes it with the given result class, an initial set of builder parameters, and the allowFailOnInit flag.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description <E extends Event>
voidaddEventListener(EventType<E> eventType, EventListener<? super E> listener)
Adds an event listener for the specified event type.BasicConfigurationBuilder<T>
addParameters(java.util.Map<java.lang.String,java.lang.Object> params)
Adds the content of the given map to the already existing initialization parameters.BasicConfigurationBuilder<T>
configure(BuilderParameters... params)
Appends the content of the specifiedBuilderParameters
objects to the current initialization parameters.void
connectToReloadingController(ReloadingController controller)
Connects this builder with aReloadingController
.protected void
copyEventListeners(BasicConfigurationBuilder<?> target)
Copies allEventListener
objects registered at this builder to the specified target configuration builder.protected void
copyEventListeners(BasicConfigurationBuilder<?> target, EventListenerList listeners)
Copies all event listeners in the specified list to the specified target configuration builder.protected T
createResult()
Creates a new, initialized result object.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.protected T
createResultInstance()
Creates the new, uninitialized result object.protected BeanHelper
fetchBeanHelper()
Obtains theBeanHelper
object to be used when dealing with bean declarations.protected void
fireBuilderEvent(ConfigurationBuilderEvent event)
Sends the specified builder event to all registered listeners.T
getConfiguration()
Returns the configuration provided by this builder.protected java.util.Map<java.lang.String,java.lang.Object>
getParameters()
Returns a (unmodifiable) map with the current initialization parameters set for this builder.java.lang.Class<? extends T>
getResultClass()
Returns the result class of this builder.protected BeanDeclaration
getResultDeclaration()
Returns theBeanDeclaration
that is used to create and initialize result objects.protected void
initResultInstance(T obj)
Initializes a newly created result object.protected <E extends Event>
voidinstallEventListener(EventType<E> eventType, EventListener<? super E> listener)
Adds the specified event listener to this object.boolean
isAllowFailOnInit()
Returns the allowFailOnInit flag.<E extends Event>
booleanremoveEventListener(EventType<E> eventType, EventListener<? super E> listener)
Removes the event listener registration for the given event type and listener.void
reset()
Resets this builder.void
resetParameters()
Removes all initialization parameters of this builder.void
resetResult()
Clears an existing result object.BasicConfigurationBuilder<T>
setParameters(java.util.Map<java.lang.String,java.lang.Object> params)
Sets the initialization parameters of this builder.
-
-
-
Constructor Detail
-
BasicConfigurationBuilder
public BasicConfigurationBuilder(java.lang.Class<? extends T> resCls)
Creates a new instance ofBasicConfigurationBuilder
and initializes it with the given result class. No initialization properties are set.- Parameters:
resCls
- the result class (must not be null)- Throws:
java.lang.IllegalArgumentException
- if the result class is null
-
BasicConfigurationBuilder
public BasicConfigurationBuilder(java.lang.Class<? extends T> resCls, java.util.Map<java.lang.String,java.lang.Object> params)
Creates a new instance ofBasicConfigurationBuilder
and initializes it with the given result class and an initial set of builder parameters. The allowFailOnInit flag is set to false.- Parameters:
resCls
- the result class (must not be null)params
- a map with initialization parameters- Throws:
java.lang.IllegalArgumentException
- if the result class is null
-
BasicConfigurationBuilder
public BasicConfigurationBuilder(java.lang.Class<? extends T> resCls, java.util.Map<java.lang.String,java.lang.Object> params, boolean allowFailOnInit)
Creates a new instance ofBasicConfigurationBuilder
and initializes it with the given result class, an initial set of builder parameters, and the allowFailOnInit flag. The map with parameters may be null, in this case no initialization parameters are set.- Parameters:
resCls
- the result class (must not be null)params
- a map with initialization parametersallowFailOnInit
- a flag whether exceptions on initializing a newly createdImmutableConfiguration
object are allowed- Throws:
java.lang.IllegalArgumentException
- if the result class is null
-
-
Method Detail
-
getResultClass
public java.lang.Class<? extends T> getResultClass()
Returns the result class of this builder. The objects produced by this builder have the class returned here.- Returns:
- the result class of this builder
-
isAllowFailOnInit
public boolean isAllowFailOnInit()
Returns the allowFailOnInit flag. See the header comment for information about this flag.- Returns:
- the allowFailOnInit flag
-
setParameters
public BasicConfigurationBuilder<T> setParameters(java.util.Map<java.lang.String,java.lang.Object> params)
Sets the initialization parameters of this builder. Already existing parameters are replaced by the content of the given map.- Parameters:
params
- the new initialization parameters of this builder; can be null, then all initialization parameters are removed- Returns:
- a reference to this builder for method chaining
-
addParameters
public BasicConfigurationBuilder<T> addParameters(java.util.Map<java.lang.String,java.lang.Object> params)
Adds the content of the given map to the already existing initialization parameters.- Parameters:
params
- the map with additional initialization parameters; may be null, then this call has no effect- Returns:
- a reference to this builder for method chaining
-
configure
public BasicConfigurationBuilder<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.- Parameters:
params
- an arbitrary number of objects with builder parameters- Returns:
- a reference to this builder for method chaining
- Throws:
java.lang.NullPointerException
- if a null array is passed
-
getConfiguration
public T getConfiguration() throws ConfigurationException
Returns 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).- Specified by:
getConfiguration
in interfaceConfigurationBuilder<T extends ImmutableConfiguration>
- Returns:
- the configuration
- Throws:
ConfigurationException
- if an error occurs
-
addEventListener
public <E extends Event> void addEventListener(EventType<E> eventType, EventListener<? super E> listener)
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.- Specified by:
addEventListener
in interfaceEventSource
- Type Parameters:
E
- the type of events processed by this listener- Parameters:
eventType
- the event type (must not be null)listener
- the listener to be registered (must not be null)- Throws:
java.lang.IllegalArgumentException
- if the event type or the listener is null
-
removeEventListener
public <E extends Event> boolean removeEventListener(EventType<E> eventType, EventListener<? super E> listener)
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.- Specified by:
removeEventListener
in interfaceEventSource
- Type Parameters:
E
- the type of events processed by this listener- Parameters:
eventType
- the event typelistener
- the event listener to be removed- Returns:
- a flag whether a listener registration was removed
-
resetResult
public void resetResult()
Clears an existing result object. An invocation of this method causes a newImmutableConfiguration
object to be created the next timegetConfiguration()
is called.
-
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.
-
reset
public void reset()
Resets this builder. This is a convenience method which combines calls toresetResult()
andresetParameters()
.
-
connectToReloadingController
public final void connectToReloadingController(ReloadingController controller)
Connects this builder with aReloadingController
. With this method support for reloading can be added to an arbitrary builder object. Event listeners are registered at the reloading controller and this builder with connect both objects:- When the reloading controller detects that a reload is required, the
builder's
resetResult()
method is called; so the managed result object is invalidated. - When a new result object has been created the controller's reloading state is reset, so that new changes can be detected again.
- Parameters:
controller
- theReloadingController
to connect to (must not be null)- Throws:
java.lang.IllegalArgumentException
- if the controller is null
- When the reloading controller detects that a reload is required, the
builder's
-
createResult
protected T createResult() throws ConfigurationException
Creates a new, initialized result object. This method is called bygetConfiguration()
if no valid result object exists. This base implementation performs two steps:createResultInstance()
is called to create a new, uninitialized result object.initResultInstance()
is called to process all initialization parameters.
- Returns:
- the newly created result object
- Throws:
ConfigurationException
- if an error occurs
-
createResultInstance
protected T createResultInstance() throws ConfigurationException
Creates the new, uninitialized result object. This is the first step of the process of producing a result object for this builder. This implementation uses theBeanHelper
class to create a new object based on theBeanDeclaration
returned bygetResultDeclaration()
. Note: This method is invoked in a synchronized block.- Returns:
- the newly created, yet uninitialized result object
- Throws:
ConfigurationException
- if an exception occurs
-
initResultInstance
protected void initResultInstance(T obj) 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 bygetResultDeclaration()
. 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.- Parameters:
obj
- the object to be initialized- Throws:
ConfigurationException
- if an error occurs
-
getResultDeclaration
protected final BeanDeclaration getResultDeclaration() throws ConfigurationException
Returns theBeanDeclaration
that is used to create and initialize result objects. The declaration is created on first access (by invokingcreateResultDeclaration(Map)
) based on the current initialization parameters.- Returns:
- the
BeanDeclaration
for dynamically creating a result object - Throws:
ConfigurationException
- if an error occurs
-
getParameters
protected final java.util.Map<java.lang.String,java.lang.Object> getParameters()
Returns a (unmodifiable) map with the current initialization parameters set for this builder. The map is populated with the parameters set using the various configuration options.- Returns:
- a map with the current set of initialization parameters
-
fetchBeanHelper
protected final BeanHelper fetchBeanHelper()
Obtains theBeanHelper
object to be used when dealing with bean declarations. This method checks whether this builder was configured with a specificBeanHelper
instance. If so, this instance is used. Otherwise, the defaultBeanHelper
is returned.- Returns:
- the
BeanHelper
to be used
-
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.- Parameters:
params
- a snapshot of the current initialization parameters- Returns:
- the
BeanDeclaration
for creating result objects - Throws:
ConfigurationException
- if an error occurs
-
copyEventListeners
protected void copyEventListeners(BasicConfigurationBuilder<?> target)
Copies allEventListener
objects registered at this builder to the specified target configuration builder. This method is intended to be used by derived classes which support inheritance of their properties to other builder objects.- Parameters:
target
- the target configuration builder (must not be null)- Throws:
java.lang.NullPointerException
- if the target builder is null
-
copyEventListeners
protected void copyEventListeners(BasicConfigurationBuilder<?> target, EventListenerList listeners)
Copies all event listeners in the specified list to the specified target configuration builder. This method is intended to be used by derived classes which have to deal with managed configuration builders that need to be initialized with event listeners.- Parameters:
target
- the target configuration builder (must not be null)listeners
- the event listeners to be copied over- Throws:
java.lang.NullPointerException
- if the target builder is null
-
installEventListener
protected final <E extends Event> void installEventListener(EventType<E> eventType, EventListener<? super E> listener)
Adds the specified event listener to this object. This method is called byaddEventListener()
, it does the actual listener registration. Because it is final it can be called by sub classes in the constructor if there is already the need to register an event listener.- Type Parameters:
E
- the event type- Parameters:
eventType
- the event type objectlistener
- the listener to be registered
-
fireBuilderEvent
protected void fireBuilderEvent(ConfigurationBuilderEvent event)
Sends the specified builder event to all registered listeners.- Parameters:
event
- the event to be fired
-
-