Package org.apache.commons.configuration2.builder

# Class BasicConfigurationBuilder<T extends ImmutableConfiguration>

java.lang.Object
org.apache.commons.configuration2.builder.BasicConfigurationBuilder<T>

Type Parameters:
  `T` - the concrete type of `ImmutableConfiguration` objects created by this builder

All Implemented Interfaces:
  `ConfigurationBuilder<T>`, `EventSource`

Direct Known Subclasses:
  `CombinedConfigurationBuilder`, `FileBasedConfigurationBuilder`, `MultiFileConfigurationBuilder`

public 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:

- All initialization properties can be set in one or multiple calls of the `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.
- If builder instances are created by other means - for example 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 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.

Since:
  2.0

- ## Constructor Summary

  Constructors
  Constructor
  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.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<E extends Event>
  void`
  `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.
  `final 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 final 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 final Map<String,Object>`
  `getParameters()`
  Gets a (unmodifiable) map with the current initialization parameters set for this builder.
  `Class<? extends T>`
  `getResultClass()`
  Gets the result class of this builder.
  `protected final BeanDeclaration`
  `getResultDeclaration()`
  Gets the `BeanDeclaration` that is used to create and initialize result objects.
  `protected void`
  `initResultInstance(T obj)`
  Initializes a newly created result object.
  `protected final <E extends Event>
  void`
  `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>
  boolean`
  `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.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### BasicConfigurationBuilder

    public BasicConfigurationBuilder(Class<? extends T> resCls)
    Creates a new instance of `BasicConfigurationBuilder` and initializes it with the given result class. No initialization properties are set.
    Parameters:
      `resCls` - the result class (must not be null)
    Throws:
      `IllegalArgumentException` - if the result class is null

  - ### BasicConfigurationBuilder

    public 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. The allowFailOnInit flag is set to false.
    Parameters:
      `resCls` - the result class (must not be null)
      `params` - a map with initialization parameters
    Throws:
      `IllegalArgumentException` - if the result class is null

  - ### BasicConfigurationBuilder

    public 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. 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 parameters
      `allowFailOnInit` - a flag whether exceptions on initializing a newly created `ImmutableConfiguration` object are allowed
    Throws:
      `IllegalArgumentException` - if the result class is null

- ## Method Details

  - ### 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 interface `EventSource`
    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:
      `IllegalArgumentException` - if the event type or the listener is null

  - ### addParameters

    public BasicConfigurationBuilder<T> addParameters(Map<String,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 specified `BuilderParameters` 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:
      `NullPointerException` - if a null array is passed

  - ### connectToReloadingController

    public final void connectToReloadingController(ReloadingController controller)
    Connects this builder with a `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:
    - 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` - the `ReloadingController` to connect to (must not be null)
    Throws:
      `IllegalArgumentException` - if the controller is null

  - ### copyEventListeners

    protected void copyEventListeners(BasicConfigurationBuilder<?> target)
    Copies all `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.
    Parameters:
      `target` - the target configuration builder (must not be null)
    Throws:
      `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:
      `NullPointerException` - if the target builder is null

  - ### createResult

    protected T createResult() throws ConfigurationException
    Creates a new, initialized result object. This method is called by `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.
    It also evaluates the allowFailOnInit flag, i.e. if initialization causes an exception and this flag is set, the exception is ignored, and the newly created, uninitialized configuration is returned. Note that this method is called in a synchronized block.
    Returns:
      the newly created result object
    Throws:
      `ConfigurationException` - if an error occurs

  - ### createResultDeclaration

    protected BeanDeclaration createResultDeclaration(Map<String,Object> params) throws ConfigurationException
    Creates a new `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.
    Parameters:
      `params` - a snapshot of the current initialization parameters
    Returns:
      the `BeanDeclaration` for creating result objects
    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 the `BeanHelper` class to create a new object based on the `BeanDeclaration` returned by `getResultDeclaration()`. Note: This method is invoked in a synchronized block.
    Returns:
      the newly created, yet uninitialized result object
    Throws:
      `ConfigurationException` - if an exception occurs

  - ### fetchBeanHelper

    protected final BeanHelper fetchBeanHelper()
    Obtains the `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.
    Returns:
      the `BeanHelper` to be used

  - ### fireBuilderEvent

    protected void fireBuilderEvent(ConfigurationBuilderEvent event)
    Sends the specified builder event to all registered listeners.
    Parameters:
      `event` - the event to be fired

  - ### 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 a `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).
    Specified by:
      `getConfiguration` in interface `ConfigurationBuilder<T extends ImmutableConfiguration>`
    Returns:
      the configuration
    Throws:
      `ConfigurationException` - if an error occurs

  - ### getParameters

    protected final Map<String,Object> getParameters()
    Gets 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

  - ### getResultClass

    public Class<? extends T> getResultClass()
    Gets the result class of this builder. The objects produced by this builder have the class returned here.
    Returns:
      the result class of this builder

  - ### getResultDeclaration

    protected final BeanDeclaration getResultDeclaration() throws ConfigurationException
    Gets the `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.
    Returns:
      the `BeanDeclaration` for dynamically creating a result object
    Throws:
      `ConfigurationException` - if an error 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 the `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.
    Parameters:
      `obj` - the object to be initialized
    Throws:
      `ConfigurationException` - if an error occurs

  - ### 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 by `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.
    Type Parameters:
      `E` - the event type
    Parameters:
      `eventType` - the event type object
      `listener` - the listener to be registered

  - ### isAllowFailOnInit

    public boolean isAllowFailOnInit()
    Returns the allowFailOnInit flag. See the header comment for information about this flag.
    Returns:
      the allowFailOnInit flag

  - ### 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 interface `EventSource`
    Type Parameters:
      `E` - the type of events processed by this listener
    Parameters:
      `eventType` - the event type
      `listener` - the event listener to be removed
    Returns:
      a flag whether a listener registration was removed

  - ### reset

    public void reset()
    Resets this builder. This is a convenience method which combines calls to `resetResult()` and `resetParameters()`.

  - ### 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.

  - ### resetResult

    public void resetResult()
    Clears an existing result object. An invocation of this method causes a new `ImmutableConfiguration` object to be created the next time `getConfiguration()` is called.

  - ### setParameters

    public BasicConfigurationBuilder<T> setParameters(Map<String,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