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 Summary

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

- ## Method Summary

  Modifier and Type
  Method
  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()`
  Gets 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 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.