Package 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 Details

    • 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 Details

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

    • 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

    • getDetector

      public ReloadingDetector getDetector()
      Gets the ReloadingDetector used by this controller.
      Returns:
      the ReloadingDetector

    • 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

    • 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

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