Package org.apache.commons.configuration2.builder.combined

# 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 of `Configuration` 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 the `ConfigurationInterpolator` (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 a `ConfigurationInterpolator`. Other properties of this parameters object are used to initialize the builders for managed configurations.

Since:
  2.0

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `MultiFileConfigurationBuilder(Class<? extends T> resCls)`
  Creates a new instance of `MultiFileConfigurationBuilder` without setting initialization parameters.
  `MultiFileConfigurationBuilder(Class<? extends T> resCls, Map<String,Object> params)`
  Creates a new instance of `MultiFileConfigurationBuilder` and sets initialization parameters.
  `MultiFileConfigurationBuilder(Class<? extends T> resCls, Map<String,Object> params, boolean allowFailOnInit)`
  Creates a new instance of `MultiFileConfigurationBuilder` and sets initialization parameters and a flag whether initialization failures should be ignored.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<E extends Event>
  void`
  `addEventListener(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 specified `BuilderParameters` objects to the current initialization parameters.
  `protected String`
  `constructFileName(MultiFileBuilderParametersImpl multiParams)`
  Determines the file name of a configuration based on the file name pattern.
  `protected FileBasedConfigurationBuilder<T>`
  `createInitializedManagedBuilder(String fileName, Map<String,Object> params)`
  Creates a fully initialized builder for a managed configuration.
  `protected ConfigurationInterpolator`
  `createInterpolator()`
  Creates the `ConfigurationInterpolator` to be used by this instance.
  `protected FileBasedConfigurationBuilder<T>`
  `createManagedBuilder(String fileName, Map<String,Object> params)`
  Creates a builder for a managed configuration.
  `T`
  `getConfiguration()`
  Gets the configuration provided by this builder.
  `protected ConfigurationInterpolator`
  `getInterpolator()`
  Gets the `ConfigurationInterpolator` used by this instance.
  `FileBasedConfigurationBuilder<T>`
  `getManagedBuilder()`
  Gets the managed `FileBasedConfigurationBuilder` for the current file name pattern.
  `protected ConcurrentMap<String,FileBasedConfigurationBuilder<T>>`
  `getManagedBuilders()`
  Gets the map with the managed builders created so far by this `MultiFileConfigurationBuilder`.
  `<E extends Event>
  boolean`
  `removeEventListener(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`

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

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

- ## Constructor Details

  - ### MultiFileConfigurationBuilder

    public MultiFileConfigurationBuilder(Class<? extends T> resCls)
    Creates a new instance of `MultiFileConfigurationBuilder` without setting initialization parameters.
    Parameters:
      `resCls` - the result configuration class
    Throws:
      `IllegalArgumentException` - if the result class is null

  - ### MultiFileConfigurationBuilder

    public MultiFileConfigurationBuilder(Class<? extends T> resCls, Map<String,Object> params)
    Creates a new instance of `MultiFileConfigurationBuilder` and sets initialization parameters.
    Parameters:
      `resCls` - the result configuration class
      `params` - a map with initialization parameters
    Throws:
      `IllegalArgumentException` - if the result class is null

  - ### MultiFileConfigurationBuilder

    public MultiFileConfigurationBuilder(Class<? extends T> resCls, Map<String,Object> params, boolean allowFailOnInit)
    Creates a new instance of `MultiFileConfigurationBuilder` and sets initialization parameters and a flag whether initialization failures should be ignored.
    Parameters:
      `resCls` - the result configuration class
      `params` - a map with initialization parameters
      `allowFailOnInit` - a flag whether initialization errors should be ignored
    Throws:
      `IllegalArgumentException` - if the result class is null

- ## Method Details

  - ### 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 interface `EventSource`
    Overrides:
      `addEventListener` in class `BasicConfigurationBuilder<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 specified `BuilderParameters` 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 class `BasicConfigurationBuilder<T extends FileBasedConfiguration>`
    Parameters:
      `params` - an arbitrary number of objects with builder parameters
    Returns:
      a reference to this builder for method chaining

  - ### constructFileName

    protected 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 the `ConfigurationInterpolator` 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

  - ### createInitializedManagedBuilder

    protected FileBasedConfigurationBuilder<T> createInitializedManagedBuilder(String fileName, Map<String,Object> params) throws ConfigurationException
    Creates a fully initialized builder for a managed configuration. This method is called by `getConfiguration()` whenever a configuration file is requested which has not yet been loaded. This implementation delegates to `createManagedBuilder()` for actually creating the builder object. Then it sets the location to the configuration file.
    Parameters:
      `fileName` - the name of the file to be loaded
      `params` - 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 the `ConfigurationInterpolator` to be used by this instance. This method is called when a file name is to be constructed, but no current `ConfigurationInterpolator` instance is available. It obtains an instance from this builder's parameters. If no properties of the `ConfigurationInterpolator` 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(String fileName, Map<String,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 loaded
      `params` - a map with initialization parameters for the new builder
    Returns:
      the newly created builder instance
    Throws:
      `ConfigurationException` - if an error occurs

  - ### 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). This implementation evaluates the file name pattern using the configured `ConfigurationInterpolator`. 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 interface `ConfigurationBuilder<T extends FileBasedConfiguration>`
    Overrides:
      `getConfiguration` in class `BasicConfigurationBuilder<T extends FileBasedConfiguration>`
    Returns:
      the configuration
    Throws:
      `ConfigurationException` - if an error occurs

  - ### getInterpolator

    protected ConfigurationInterpolator getInterpolator()
    Gets the `ConfigurationInterpolator` 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 managed `FileBasedConfigurationBuilder` for the current file name pattern. It is determined based on the evaluation of the file name pattern using the configured `ConfigurationInterpolator`. 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 (for example due to missing initialization parameters)

  - ### getManagedBuilders

    protected ConcurrentMap<String,FileBasedConfigurationBuilder<T>> getManagedBuilders()
    Gets the map with the managed builders created so far by this `MultiFileConfigurationBuilder`. 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

  - ### 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 interface `EventSource`
    Overrides:
      `removeEventListener` in class `BasicConfigurationBuilder<T extends FileBasedConfiguration>`
    Type Parameters:
      `E` - the type of events processed by this listener
    Parameters:
      `eventType` - the event type
      `l` - 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 class `BasicConfigurationBuilder<T extends FileBasedConfiguration>`