org.apache.commons.configuration2.reloading

Class ReloadingController

java.lang.Object

org.apache.commons.configuration2.reloading.ReloadingController

All Implemented Interfaces:

EventSource

Direct Known Subclasses:

CombinedReloadingController

public class ReloadingController
extends Object
implements EventSource

A class for adding support for reload operations in a generic way.

A ReloadingController monitors a specific source and triggers reloading events if necessary. So it does not perform reloading itself, but only sends out notifications when it thinks that this should be done. This allows for a very generic setup in which different components involved in reloading are loosely coupled via events.

A typical usage scenario is as follows:

• A ReloadingController instance is created and initialized with a ReloadingDetector object.
• A number of EventListener objects for reloading events can be registered at the controller.
• Now the controller's checkForReloading() method is called whenever a check is to be performed. This could be done for instance by a timer in regular intervals or by any other means appropriate for a specific application.
• When a check reveals that a reload operation is necessary all registered event listeners are notified.
• Typically one of the listeners is responsible to perform the actual reload operation. (How this is done is not in the scope of the controller object.) After this has been done, the controller's resetReloadingState() method must be called. It tells the controller that the last notification has been processed and that new checks are possible again. It is important that this method is called. Otherwise, checkForReloading() will not do any new checks or send out event notifications any more.

This class can be accessed from multiple threads concurrently. It shields the associated ReloadingDetector object for concurrent access, so that a concrete detector implementation does not have to be thread-safe.

Since:

2.0

Constructor Summary

Constructors

Constructor and Description
ReloadingController(ReloadingDetector detect) Creates a new instance of ReloadingController and associates it with the given ReloadingDetector object.

Method Summary

Modifier and Type	Method and Description
<T extends Event> void	addEventListener(EventType<T> eventType, EventListener<? super T> listener) Adds an event listener for the specified event type.
boolean	checkForReloading(Object data) Performs a check whether a reload operation is necessary.
ReloadingDetector	getDetector() Returns the ReloadingDetector used by this controller.
boolean	isInReloadingState() Tests whether this controller is in reloading state.
<T extends Event> boolean	removeEventListener(EventType<T> eventType, EventListener<? super T> listener) Removes the event listener registration for the given event type and listener.
void	resetReloadingState() Resets the reloading state.

Methods inherited from class java.lang.Object

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

Constructor Detail

ReloadingController

public ReloadingController(ReloadingDetector detect)

Creates a new instance of ReloadingController and associates it with the given ReloadingDetector object.

Parameters:

detect - the ReloadingDetector (must not be null)

Throws:

IllegalArgumentException - if the detector is undefined

Method Detail

getDetector

public ReloadingDetector getDetector()

Returns the ReloadingDetector used by this controller.

Returns:

the ReloadingDetector

addEventListener

public <T extends Event> void addEventListener(EventType<T> eventType,
                                               EventListener<? super T> 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 class generates events of type ReloadingEvent.

Specified by:

addEventListener in interface EventSource

Type Parameters:

T - 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)

removeEventListener

public <T extends Event> boolean removeEventListener(EventType<T> eventType,
                                                     EventListener<? super T> listener)

Description copied from interface: EventSource

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.

Specified by:

removeEventListener in interface EventSource

Type Parameters:

T - 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

isInReloadingState

public boolean isInReloadingState()

Tests whether this controller is in reloading state. A return value of true means that a previous invocation of checkForReloading() has detected the necessity for a reload operation, but resetReloadingState() has not been called yet. In this state no further reloading checks are possible.

Returns:

a flag whether this controller is in reloading state

checkForReloading

public boolean checkForReloading(Object data)

Performs a check whether a reload operation is necessary. This method has to be called to trigger the generation of reloading events. It delegates to the associated ReloadingDetector and sends out notifications if necessary. The argument can be an arbitrary data object; it will be part of the event notification sent out when a reload operation should be performed. The return value indicates whether a change was detected and an event was sent. Once a need for a reload is detected, this controller is in reloading state. Until this state is reset (by calling resetReloadingState()), no further reloading checks are performed by this method, and no events are fired; it then returns always true.

Parameters:

data - additional data for an event notification

Returns:

a flag whether a reload operation is necessary

resetReloadingState

public void resetReloadingState()

Resets the reloading state. This tells the controller that reloading has been performed and new checks are possible again. If this controller is not in reloading state, this method has no effect.