Package org.jtrim2.concurrent

Class RepeatingTask

java.lang.Object
org.jtrim2.concurrent.RepeatingTask
All Implemented Interfaces:
Runnable
public abstract class RepeatingTask extends Object implements Runnable
Defines a task which can repeatedly be executed by a ScheduledExecutorService and this task controls if it is needed to be rescheduled.

Note that as of Java 5 ScheduledThreadPoolExecutor is preferred over Timer (because of its caveats). Most tasks can be relatively easily ported to use the more robust ScheduledThreadPoolExecutor. However there are certain tasks which can be easily done using a Timer but not a ScheduledExecutorService. One such particular task is when the task itself needs to make sure that it never runs again. This is not so easy to do with a ScheduledExecutorService because a task submitted to it can be canceled by the future returned by the schedule method. This class is intended to fill this gap.

To use this class subclass this abstract class and implement the runAndTest() method. This method returns a boolean to determine if the task can be scheduled again to run.

Thread safety

The methods of this class are safe to use by multiple threads concurrently but the runAndTest() method is not required to be thread-safe.

Synchronization transparency

The methods of this class are not synchronization transparent and the runAndTest() method is not required to be synchronization transparent either.

  • Constructor Summary

    Constructors
    Constructor
    Description
    RepeatingTask(ScheduledExecutorService executor, long period, TimeUnit periodUnit)
    Initializes a RepeatingTask with a ScheduledExecutorService and the time to wait between consecutive execution of this task.
    RepeatingTask(ScheduledExecutorService executor, long period, TimeUnit periodUnit, boolean scheduleOnFailure)
    Initializes a RepeatingTask with a ScheduledExecutorService, the time to wait between consecutive execution of this task and if it need to be rescheduled in case this task throws an unchecked exception.

  • Method Summary

    Modifier and Type
    Method
    Description
    final void
    execute()
    Submits this task to be executed a single time as soon as possible by the ScheduledExecutorService specified at construction time.
    final void
    run()
    Invokes the runAndTest() method and reschedules it to the ScheduledExecutorService specified at construction time according to the construction time definitions.
    protected abstract boolean
    runAndTest()
    Implement this method to actually execute the given task.
    final void
    schedule(long delay, TimeUnit delayUnit)
    Submits this task to be executed a periodically after the given initial delay by the ScheduledExecutorService specified at construction time.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • RepeatingTask

      public RepeatingTask(ScheduledExecutorService executor, long period, TimeUnit periodUnit)
      Initializes a RepeatingTask with a ScheduledExecutorService and the time to wait between consecutive execution of this task. The task will be be rescheduled to execute again even if it throws an exception.

      To actually start execution this task periodically: Call the schedule(long, TimeUnit) method or call the execute() method to submit this task for execution for a single run (in this case it will be executed without delay).

      Parameters:
      executor - the ScheduledExecutorService to which this task will be submitted to. This argument cannot be null.
      period - the time to wait between consecutive execution of this task in the given time unit. This argument must be greater than or equal to zero.
      periodUnit - the time unit of the period argument. This argument cannot be null.
      Throws:
      IllegalArgumentException - thrown if period &lt 0
      NullPointerException - thrown if either executor or periodUnit is null

    • RepeatingTask

      public RepeatingTask(ScheduledExecutorService executor, long period, TimeUnit periodUnit, boolean scheduleOnFailure)
      Initializes a RepeatingTask with a ScheduledExecutorService, the time to wait between consecutive execution of this task and if it need to be rescheduled in case this task throws an unchecked exception.

      To actually start execution this task periodically: Call the schedule(long, TimeUnit) method or call the execute() method to submit this task for execution for a single run (in this case it will be executed without delay).

      Parameters:
      executor - the ScheduledExecutorService to which this task will be submitted to. This argument cannot be null.
      period - the time to wait between consecutive execution of this task in the given time unit. This argument must be greater than or equal to zero.
      periodUnit - the time unit of the period argument. This argument cannot be null.
      scheduleOnFailure - true if the task needs to be rescheduled in case it throws an unchecked exception, false if the task must not be executed again in case of such an exception
      Throws:
      IllegalArgumentException - thrown if period &lt 0
      NullPointerException - thrown if either executor or periodUnit is null

  • Method Details

    • execute

      public final void execute()
      Submits this task to be executed a single time as soon as possible by the ScheduledExecutorService specified at construction time.
      See Also:

    • schedule

      public final void schedule(long delay, TimeUnit delayUnit)
      Submits this task to be executed a periodically after the given initial delay by the ScheduledExecutorService specified at construction time.
      Parameters:
      delay - the initial delay before the first execution of this task in the given time unit. This argument must be greater than or equal to zero.
      delayUnit - the time unit of the delay argument. This argument cannot be null.
      Throws:
      IllegalArgumentException - thrown if delay &lt 0
      NullPointerException - thrown if the specified time unit is null
      See Also:

    • runAndTest

      protected abstract boolean runAndTest()
      Implement this method to actually execute the given task. This method will be invoked by the run() method of this task which will also reschedule this task if needed.
      Returns:
      true if this task needed to be executed again, false in case this task must not be executed again

    • run

      public final void run()
      Invokes the runAndTest() method and reschedules it to the ScheduledExecutorService specified at construction time according to the construction time definitions.

      Note that this method is only intended to be called by the underlying ScheduledExecutorService.

      Specified by:
      run in interface Runnable