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

    All Methods Instance Methods Concrete Methods
    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 Detail

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

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

  - ### Method Detail

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

    - #### 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​(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

    - #### shutdown

          public void shutdown()

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