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, e.g. a timer.

Since:

2.0

Constructor Summary

Constructors

Constructor and 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 and 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() Returns 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 Detail

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

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

Method Detail

getReloadingController

public ReloadingController getReloadingController()

Returns 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

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

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