Package org.apache.commons.configuration2.builder

# Class ReloadingFileBasedConfigurationBuilder<T extends FileBasedConfiguration>

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

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

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

public class ReloadingFileBasedConfigurationBuilder<T extends FileBasedConfiguration> extends FileBasedConfigurationBuilder<T> implements ReloadingControllerSupport

A specialized `ConfigurationBuilder` implementation which can handle configurations read from a `FileHandler` and supports reloading.

This builder class exposes a `ReloadingController` object controlling reload operations on the file-based configuration produced as result object. For the `FileHandler` defining the location of the configuration a configurable `ReloadingDetector` is created and associated with the controller. So changes on the source file can be detected. When ever such a change occurs, the result object of this builder is reset. This means that the next time `getConfiguration()` is called a new `Configuration` object is created which is loaded from the modified file.

Client code interested in notifications can register a listener at this builder to receive reset events. When such an event is received the new result object can be requested. This way client applications can be sure to work with an up-to-date configuration. It is also possible to register a listener directly at the `ReloadingController`.

This builder does not actively trigger the `ReloadingController` to perform a reload check. This has to be done by an external component, for example a timer.

Since:
  2.0

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ReloadingFileBasedConfigurationBuilder(Class<? extends T> resCls)`
  Creates a new instance of `ReloadingFileBasedConfigurationBuilder` which produces result objects of the specified class.
  `ReloadingFileBasedConfigurationBuilder(Class<? extends T> resCls, Map<String,Object> params)`
  Creates a new instance of `ReloadingFileBasedConfigurationBuilder` which produces result objects of the specified class and sets initialization parameters.
  `ReloadingFileBasedConfigurationBuilder(Class<? extends T> resCls, Map<String,Object> params, boolean allowFailOnInit)`
  Creates a new instance of `ReloadingFileBasedConfigurationBuilder` which produces result objects of the specified class and sets initialization parameters and the allowFailOnInit flag.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ReloadingFileBasedConfigurationBuilder<T>`
  `configure(BuilderParameters... params)`
  Appends the content of the specified `BuilderParameters` objects to the current initialization parameters.
  `protected ReloadingDetector`
  `createReloadingDetector(FileHandler handler, FileBasedBuilderParametersImpl fbparams)`
  Creates a `ReloadingDetector` which monitors the passed in `FileHandler`.
  `ReloadingController`
  `getReloadingController()`
  Gets the `ReloadingController` associated with this builder.
  `protected void`
  `initFileHandler(FileHandler handler)`
  Initializes the new current `FileHandler`.

  ### Methods inherited from class org.apache.commons.configuration2.builder.FileBasedConfigurationBuilder

  `getDefaultEncoding, getFileHandler, initResultInstance, isAutoSave, save, setAutoSave, setDefaultEncoding, setParameters`

  ### Methods inherited from class org.apache.commons.configuration2.builder.BasicConfigurationBuilder

  `addEventListener, addParameters, connectToReloadingController, copyEventListeners, copyEventListeners, createResult, createResultDeclaration, createResultInstance, fetchBeanHelper, fireBuilderEvent, getConfiguration, getParameters, getResultClass, getResultDeclaration, installEventListener, isAllowFailOnInit, removeEventListener, reset, resetParameters, resetResult`

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

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

- ## Constructor Details

  - ### ReloadingFileBasedConfigurationBuilder

    public ReloadingFileBasedConfigurationBuilder(Class<? extends T> resCls)
    Creates a new instance of `ReloadingFileBasedConfigurationBuilder` which produces result objects of the specified class.
    Parameters:
      `resCls` - the result class (must not be null
    Throws:
      `IllegalArgumentException` - if the result class is null

  - ### ReloadingFileBasedConfigurationBuilder

    public ReloadingFileBasedConfigurationBuilder(Class<? extends T> resCls, Map<String,Object> params)
    Creates a new instance of `ReloadingFileBasedConfigurationBuilder` which produces result objects of the specified class and sets initialization parameters.
    Parameters:
      `resCls` - the result class (must not be null
      `params` - a map with initialization parameters
    Throws:
      `IllegalArgumentException` - if the result class is null

  - ### ReloadingFileBasedConfigurationBuilder

    public ReloadingFileBasedConfigurationBuilder(Class<? extends T> resCls, Map<String,Object> params, boolean allowFailOnInit)
    Creates a new instance of `ReloadingFileBasedConfigurationBuilder` which produces result objects of the specified class and sets initialization parameters and the allowFailOnInit flag.
    Parameters:
      `resCls` - the result class (must not be null
      `params` - a map with initialization parameters
      `allowFailOnInit` - the allowFailOnInit flag
    Throws:
      `IllegalArgumentException` - if the result class is null

- ## Method Details

  - ### configure

    public ReloadingFileBasedConfigurationBuilder<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 here to change the result type. This method is overridden here to change the result type.
    Overrides:
      `configure` in class `FileBasedConfigurationBuilder<T extends FileBasedConfiguration>`
    Parameters:
      `params` - an arbitrary number of objects with builder parameters
    Returns:
      a reference to this builder for method chaining

  - ### createReloadingDetector

    protected ReloadingDetector createReloadingDetector(FileHandler handler, FileBasedBuilderParametersImpl fbparams) throws ConfigurationException
    Creates a `ReloadingDetector` which monitors the passed in `FileHandler`. This method is called each time a new result object is created with the current `FileHandler`. This implementation checks whether a `ReloadingDetectorFactory` is specified in the current parameters. If this is the case, it is invoked. Otherwise, a default factory is used to create a `FileHandlerReloadingDetector` object. Note: This method is called from a synchronized block.
    Parameters:
      `handler` - the current `FileHandler`
      `fbparams` - the object with parameters related to file-based builders
    Returns:
      a `ReloadingDetector` for this `FileHandler`
    Throws:
      `ConfigurationException` - if an error occurs

  - ### getReloadingController

    public ReloadingController getReloadingController()
    Gets the `ReloadingController` associated with this builder. This controller is directly created. However, it becomes active (i.e. associated with a meaningful reloading detector) not before a result object was created.
    Specified by:
      `getReloadingController` in interface `ReloadingControllerSupport`
    Returns:
      the `ReloadingController`

  - ### initFileHandler

    protected void initFileHandler(FileHandler handler) throws ConfigurationException
    Initializes the new current `FileHandler`. When a new result object is created, a new `FileHandler` is created, too, and associated with the result object. This new handler is passed to this method. If a location is defined, the result object is loaded from this location. Note: This method is called from a synchronized block. This implementation also takes care that a new `ReloadingDetector` for the new current `FileHandler` is created. Also, the reloading controller's reloading state has to be reset; after the creation of a new result object changes in the underlying configuration source have to be monitored again.
    Overrides:
      `initFileHandler` in class `FileBasedConfigurationBuilder<T extends FileBasedConfiguration>`
    Parameters:
      `handler` - the new current `FileHandler`
    Throws:
      `ConfigurationException` - if an error occurs