T
- the concrete type of ImmutableConfiguration
objects created by this builderpublic class BasicConfigurationBuilder<T extends ImmutableConfiguration> extends Object implements ConfigurationBuilder<T>
An implementation of the ConfigurationBuilder
interface which is able to create different concrete
ImmutableConfiguration
implementations based on reflection.
When constructing an instance of this class the concrete ImmutableConfiguration
implementation class has to
be provided. Then properties for the new ImmutableConfiguration
instance can be set. The first call to
getConfiguration()
creates and initializes the new ImmutableConfiguration
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 the reset()
methods. That way other ImmutableConfiguration
instances with different
properties can be created.
If the newly created ImmutableConfiguration
object implements the Initializable
interface, its
initialize()
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:
configure()
method. In each call
an arbitrary number of BuilderParameters
objects can be passed. The API allows method chaining and is
intended to be used from Java code.ImmutableConfiguration
object to be
created, the values are the corresponding property values. For instance, the key throwExceptionOnMissing in
the map will cause the method setThrowExceptionOnMissing()
on the ImmutableConfiguration
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. Then
getConfiguration()
can be called concurrently, and it is guaranteed that always the same
ImmutableConfiguration
instance is returned until the builder is reset.
Constructor and Description |
---|
BasicConfigurationBuilder(Class<? extends T> resCls)
Creates a new instance of
BasicConfigurationBuilder and initializes it with the given result class. |
BasicConfigurationBuilder(Class<? extends T> resCls,
Map<String,Object> params)
Creates a new instance of
BasicConfigurationBuilder and initializes it with the given result class and an
initial set of builder parameters. |
BasicConfigurationBuilder(Class<? extends T> resCls,
Map<String,Object> params,
boolean allowFailOnInit)
Creates a new instance of
BasicConfigurationBuilder and initializes it with the given result class, an
initial set of builder parameters, and the allowFailOnInit flag. |
Modifier and Type | Method and Description |
---|---|
<E extends Event> |
addEventListener(EventType<E> eventType,
EventListener<? super E> listener)
Adds an event listener for the specified event type.
|
BasicConfigurationBuilder<T> |
addParameters(Map<String,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 specified
BuilderParameters objects to the current initialization parameters. |
void |
connectToReloadingController(ReloadingController controller)
Connects this builder with a
ReloadingController . |
protected void |
copyEventListeners(BasicConfigurationBuilder<?> target)
Copies all
EventListener 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(Map<String,Object> params)
Creates a new
BeanDeclaration which is used for creating new result objects dynamically. |
protected T |
createResultInstance()
Creates the new, uninitialized result object.
|
protected BeanHelper |
fetchBeanHelper()
Obtains the
BeanHelper 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()
Gets the configuration provided by this builder.
|
protected Map<String,Object> |
getParameters()
Returns a (unmodifiable) map with the current initialization parameters set for this builder.
|
Class<? extends T> |
getResultClass()
Returns the result class of this builder.
|
protected BeanDeclaration |
getResultDeclaration()
Returns the
BeanDeclaration that is used to create and initialize result objects. |
protected void |
initResultInstance(T obj)
Initializes a newly created result object.
|
protected <E extends Event> |
installEventListener(EventType<E> eventType,
EventListener<? super E> listener)
Adds the specified event listener to this object.
|
boolean |
isAllowFailOnInit()
Returns the allowFailOnInit flag.
|
<E extends Event> |
removeEventListener(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(Map<String,Object> params)
Sets the initialization parameters of this builder.
|
public BasicConfigurationBuilder(Class<? extends T> resCls)
BasicConfigurationBuilder
and initializes it with the given result class. No
initialization properties are set.resCls
- the result class (must not be null)IllegalArgumentException
- if the result class is nullpublic BasicConfigurationBuilder(Class<? extends T> resCls, Map<String,Object> params)
BasicConfigurationBuilder
and initializes it with the given result class and an
initial set of builder parameters. The allowFailOnInit flag is set to false.resCls
- the result class (must not be null)params
- a map with initialization parametersIllegalArgumentException
- if the result class is nullpublic BasicConfigurationBuilder(Class<? extends T> resCls, Map<String,Object> params, boolean allowFailOnInit)
BasicConfigurationBuilder
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.resCls
- the result class (must not be null)params
- a map with initialization parametersallowFailOnInit
- a flag whether exceptions on initializing a newly created ImmutableConfiguration
object are allowedIllegalArgumentException
- if the result class is nullpublic Class<? extends T> getResultClass()
public boolean isAllowFailOnInit()
public BasicConfigurationBuilder<T> setParameters(Map<String,Object> params)
params
- the new initialization parameters of this builder; can be null, then all initialization
parameters are removedpublic BasicConfigurationBuilder<T> addParameters(Map<String,Object> params)
params
- the map with additional initialization parameters; may be null, then this call has no effectpublic BasicConfigurationBuilder<T> configure(BuilderParameters... params)
BuilderParameters
objects to the current initialization parameters.
Calling this method multiple times will create a union of the parameters provided.params
- an arbitrary number of objects with builder parametersNullPointerException
- if a null array is passedpublic T getConfiguration() throws ConfigurationException
ImmutableConfiguration
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).getConfiguration
in interface ConfigurationBuilder<T extends ImmutableConfiguration>
ConfigurationException
- if an error occurspublic <E extends Event> void addEventListener(EventType<E> eventType, EventListener<? super E> listener)
addEventListener
in interface EventSource
E
- the type of events processed by this listenereventType
- the event type (must not be null)listener
- the listener to be registered (must not be null)IllegalArgumentException
- if the event type or the listener is nullpublic <E extends Event> boolean removeEventListener(EventType<E> eventType, EventListener<? super E> listener)
removeEventListener
in interface EventSource
E
- the type of events processed by this listenereventType
- the event typelistener
- the event listener to be removedpublic void resetResult()
ImmutableConfiguration
object to
be created the next time getConfiguration()
is called.public void resetParameters()
public void reset()
resetResult()
and
resetParameters()
.public final void connectToReloadingController(ReloadingController controller)
ReloadingController
. 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:
resetResult()
method is
called; so the managed result object is invalidated.controller
- the ReloadingController
to connect to (must not be null)IllegalArgumentException
- if the controller is nullprotected T createResult() throws ConfigurationException
getConfiguration()
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.ConfigurationException
- if an error occursprotected T createResultInstance() throws ConfigurationException
BeanHelper
class to create a new object based on the
BeanDeclaration
returned by getResultDeclaration()
. Note: This method is invoked in a synchronized
block.ConfigurationException
- if an exception occursprotected void initResultInstance(T obj) throws ConfigurationException
BeanHelper
class to initialize the object's property based on the
BeanDeclaration
returned by 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.obj
- the object to be initializedConfigurationException
- if an error occursprotected final BeanDeclaration getResultDeclaration() throws ConfigurationException
BeanDeclaration
that is used to create and initialize result objects. The declaration is created
on first access (by invoking createResultDeclaration(Map)
) based on the current initialization parameters.BeanDeclaration
for dynamically creating a result objectConfigurationException
- if an error occursprotected final Map<String,Object> getParameters()
protected final BeanHelper fetchBeanHelper()
BeanHelper
object to be used when dealing with bean declarations. This method checks whether this
builder was configured with a specific BeanHelper
instance. If so, this instance is used. Otherwise, the
default BeanHelper
is returned.BeanHelper
to be usedprotected BeanDeclaration createResultDeclaration(Map<String,Object> params) throws ConfigurationException
BeanDeclaration
which is used for creating new result objects dynamically. This implementation
creates a specialized BeanDeclaration
object that is initialized from the given map of initialization
parameters. The BeanDeclaration
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.params
- a snapshot of the current initialization parametersBeanDeclaration
for creating result objectsConfigurationException
- if an error occursprotected void copyEventListeners(BasicConfigurationBuilder<?> target)
EventListener
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.target
- the target configuration builder (must not be null)NullPointerException
- if the target builder is nullprotected void copyEventListeners(BasicConfigurationBuilder<?> target, EventListenerList listeners)
target
- the target configuration builder (must not be null)listeners
- the event listeners to be copied overNullPointerException
- if the target builder is nullprotected final <E extends Event> void installEventListener(EventType<E> eventType, EventListener<? super E> listener)
addEventListener()
, 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.E
- the event typeeventType
- the event type objectlistener
- the listener to be registeredprotected void fireBuilderEvent(ConfigurationBuilderEvent event)
event
- the event to be firedCopyright © 2001–2022 The Apache Software Foundation. All rights reserved.