Package org.apache.commons.configuration2.reloading

# Class PeriodicReloadingTrigger

java.lang.Object
org.apache.commons.configuration2.reloading.PeriodicReloadingTrigger

public class PeriodicReloadingTrigger extends Object

A timer-based trigger for reloading checks.

An instance of this class is constructed with a reference to a `ReloadingController` and a period. After calling the `start()` method a periodic task is started which calls `ReloadingController.checkForReloading(Object)` on the associated reloading controller. This way changes on a configuration source can be detected without client code having to poll actively. The `ReloadingController` will perform its checks and generates events if it detects the need for a reloading operation.

Triggering of the controller can be disabled by calling the `stop()` method and later be resumed by calling `start()` again. When the trigger is no more needed its `shutdown()` method should be called.

When creating an instance a `ScheduledExecutorService` can be provided which is then used by the object. Otherwise, a default executor service is created and used. When shutting down this object it can be specified whether the `ScheduledExecutorService` should be shut down, too.

Since:
  2.0
See Also:
  - `ReloadingController`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PeriodicReloadingTrigger(ReloadingController ctrl, Object ctrlParam, long triggerPeriod, TimeUnit unit)`
  Creates a new instance of `PeriodicReloadingTrigger` with a default executor service.
  `PeriodicReloadingTrigger(ReloadingController ctrl, Object ctrlParam, long triggerPeriod, TimeUnit unit, ScheduledExecutorService exec)`
  Creates a new instance of `PeriodicReloadingTrigger` and sets all parameters.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `isRunning()`
  Returns a flag whether this trigger is currently active.
  `void`
  `shutdown()`
  Shuts down this trigger and its `ScheduledExecutorService`.
  `void`
  `shutdown(boolean shutdownExecutor)`
  Shuts down this trigger and optionally shuts down the `ScheduledExecutorService` used by this object.
  `void`
  `start()`
  Starts this trigger.
  `void`
  `stop()`
  Stops this trigger.

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

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

- ## Constructor Details

  - ### PeriodicReloadingTrigger

    public PeriodicReloadingTrigger(ReloadingController ctrl, Object ctrlParam, long triggerPeriod, TimeUnit unit)
    Creates a new instance of `PeriodicReloadingTrigger` with a default executor service.
    Parameters:
      `ctrl` - the `ReloadingController` (must not be null)
      `ctrlParam` - the optional parameter to be passed to the controller when doing reloading checks
      `triggerPeriod` - the period in which the controller is triggered
      `unit` - the time unit for the period
    Throws:
      `IllegalArgumentException` - if a required argument is missing

  - ### PeriodicReloadingTrigger

    public PeriodicReloadingTrigger(ReloadingController ctrl, Object ctrlParam, long triggerPeriod, TimeUnit unit, ScheduledExecutorService exec)
    Creates a new instance of `PeriodicReloadingTrigger` and sets all parameters.
    Parameters:
      `ctrl` - the `ReloadingController` (must not be null)
      `ctrlParam` - the optional parameter to be passed to the controller when doing reloading checks
      `triggerPeriod` - the period in which the controller is triggered
      `unit` - the time unit for the period
      `exec` - the executor service to use (can be null, then a default executor service is created
    Throws:
      `IllegalArgumentException` - if a required argument is missing

- ## Method Details

  - ### isRunning

    public boolean isRunning()
    Returns a flag whether this trigger is currently active.
    Returns:
      a flag whether this trigger is running

  - ### shutdown

    public void shutdown()
    Shuts down this trigger and its `ScheduledExecutorService`. This is a shortcut for `shutdown(true)`.
    See Also:
      - `shutdown(boolean)`

  - ### shutdown

    public void shutdown(boolean shutdownExecutor)
    Shuts down this trigger and optionally shuts down the `ScheduledExecutorService` used by this object. This method should be called if this trigger is no more needed. It ensures that the trigger is stopped. If the parameter is true, the executor service is also shut down. This should be done if this trigger is the only user of this executor service.
    Parameters:
      `shutdownExecutor` - a flag whether the associated `ScheduledExecutorService` is to be shut down

  - ### start

    public void start()
    Starts this trigger. The associated `ReloadingController` will be triggered according to the specified period. The first triggering happens after a period. If this trigger is already started, this invocation has no effect.

  - ### stop

    public void stop()
    Stops this trigger. The associated `ReloadingController` is no more triggered. If this trigger is already stopped, this invocation has no effect.