Module org.hsqldb

Class HsqlTimer

java.lang.Object
org.hsqldb.lib.HsqlTimer
All Implemented Interfaces:
Comparator, ThreadFactory

public final class HsqlTimer extends Object implements Comparator, ThreadFactory
Facility to schedule tasks for future execution in a background thread.

Tasks may be scheduled for one-time execution or for repeated execution at regular intervals, using either fixed rate or fixed delay policy.

This class is a JDK 1.1 compatible implementation required by HSQLDB both because the java.util.Timer class is available only in JDK 1.3+ and because java.util.Timer starves least recently added tasks under high load and fixed rate scheduling, especially when the average actual task duration is greater than the average requested task periodicity.

An additional (minor) advantage over java.util.Timer is that this class does not retain a live background thread during periods when the task queue is empty.

Since:
1.7.2
Author:
Campbell Burnet (campbell-burnet@users dot sourceforge.net)
  • Constructor Summary

    Constructors
    Constructor
    Description
    Constructs a new HsqlTimer using the default thread factory implementation.
    HsqlTimer(ThreadFactory threadFactory)
    Constructs a new HsqlTimer.
  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    cancel(Object task)
    Causes the task referenced by the supplied argument to be cancelled.
    int
    Required to back the priority queue for scheduled tasks.
    static Date
    Retrieves the last time the referenced task was executed, as a Date object.
    static Date
    Retrieves the next time the referenced task is due to be executed, as a Date object.
    Retrieves the background execution thread.
    static boolean
    Retrieves whether the specified argument references a cancelled task.
    static boolean
    Retrieves whether the specified argument references a task scheduled periodically using fixed delay scheduling.
    static boolean
    Retrieves whether the specified argument references a task scheduled periodically using fixed rate scheduling.
    static boolean
    Retrieves whether the specified argument references a task scheduled for periodic execution.
    newThread(Runnable runnable)
    Default ThreadFactory implementation.
    void
    (Re)starts background processing of the task queue.
    scheduleAfter(long delay, Runnable runnable)
    Causes the specified Runnable to be executed once in the background after the specified delay.
    scheduleAt(Date date, Runnable runnable)
    Causes the specified Runnable to be executed once in the background at the specified time.
    schedulePeriodicallyAfter(long delay, long period, Runnable runnable, boolean relative)
    Causes the specified Runnable to be executed periodically in the background, starting after the specified delay.
    schedulePeriodicallyAt(Date date, long period, Runnable runnable, boolean relative)
    Causes the specified Runnable to be executed periodically in the background, starting at the specified time.
    static Object
    setPeriod(Object task, long period)
    Sets the periodicity of the designated task to a new value.
    void
    Shuts down this timer after the current task (if any) completes.
    void
    for compatibility with previous version
    void
    Shuts down this timer immediately, interrupting the wait state associated with the current head of the task queue or the wait state internal to the currently executing task, if any such state is currently in effect.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Constructor Details

    • HsqlTimer

      public HsqlTimer()
      Constructs a new HsqlTimer using the default thread factory implementation.
    • HsqlTimer

      public HsqlTimer(ThreadFactory threadFactory)
      Constructs a new HsqlTimer. Uses the specified thread factory implementation.
      Parameters:
      threadFactory - the ThreadFactory used to produce this timer's background threads. If null, the default implementation supplied by this class will be used.
  • Method Details

    • compare

      public int compare(Object a, Object b)
      Required to back the priority queue for scheduled tasks.
      Specified by:
      compare in interface Comparator
      Parameters:
      a - the first Task
      b - the second Task
      Returns:
      0 if equal, < 0 if a < b, > 0 if a > b
    • newThread

      public Thread newThread(Runnable runnable)
      Default ThreadFactory implementation.

      Constructs a new Thread from the designated runnable, sets its name to "HSQLDB Timer @" + Integer.toHexString(hashCode()), and sets it as a daemon thread.

      Specified by:
      newThread in interface ThreadFactory
      Parameters:
      runnable - used to construct the new Thread.
      Returns:
      a new Thread constructed from the designated runnable.
    • getThread

      public Thread getThread()
      Retrieves the background execution thread.

      null is returned if there is no such thread.

      Returns:
      the current background thread (may be null)
    • restart

      public void restart() throws IllegalStateException
      (Re)starts background processing of the task queue.
      Throws:
      IllegalStateException - if this timer is shut down.
      See Also:
    • scheduleAfter

      public Object scheduleAfter(long delay, Runnable runnable) throws IllegalArgumentException
      Causes the specified Runnable to be executed once in the background after the specified delay.
      Parameters:
      delay - in milliseconds
      runnable - the Runnable to execute.
      Returns:
      opaque reference to the internal task
      Throws:
      IllegalArgumentException - if runnable is null
    • scheduleAt

      public Object scheduleAt(Date date, Runnable runnable) throws IllegalArgumentException
      Causes the specified Runnable to be executed once in the background at the specified time.
      Parameters:
      date - time at which to execute the specified Runnable
      runnable - the Runnable to execute.
      Returns:
      opaque reference to the internal task
      Throws:
      IllegalArgumentException - if date or runnable is null
    • schedulePeriodicallyAt

      public Object schedulePeriodicallyAt(Date date, long period, Runnable runnable, boolean relative) throws IllegalArgumentException
      Causes the specified Runnable to be executed periodically in the background, starting at the specified time.
      Parameters:
      date - time at which to execute the specified Runnable
      period - the cycle period
      runnable - the Runnable to execute
      relative - if true, fixed rate scheduling else fixed delay scheduling
      Returns:
      opaque reference to the internal task
      Throws:
      IllegalArgumentException - if date or runnable is null, or period is <= 0
    • schedulePeriodicallyAfter

      public Object schedulePeriodicallyAfter(long delay, long period, Runnable runnable, boolean relative) throws IllegalArgumentException
      Causes the specified Runnable to be executed periodically in the background, starting after the specified delay.
      Parameters:
      delay - in milliseconds
      period - the cycle period
      runnable - the Runnable to execute.
      relative - if true, fixed rate scheduling else fixed delay scheduling
      Returns:
      opaque reference to the internal task
      Throws:
      IllegalArgumentException - if runnable is null or period is <= 0
    • shutdown

      public void shutdown()
      Shuts down this timer after the current task (if any) completes.

      After this call, the timer has permanently entered the shutdown state; attempting to schedule any new task or directly restart this timer will result in an IllegalStateException.

    • shutDown

      public void shutDown()
      for compatibility with previous version
    • shutdownImmediately

      public void shutdownImmediately()
      Shuts down this timer immediately, interrupting the wait state associated with the current head of the task queue or the wait state internal to the currently executing task, if any such state is currently in effect. After this call, the timer has permanently entered the shutdown state; attempting to schedule any new task or directly restart this timer will result in an IllegalStateException.

      Note: If the integrity of work performed by a scheduled task may be adversely affected by an unplanned interruption, it is the responsibility of the task's implementation to deal correctly with the possibility that this method is called while such work is in progress, for instance by catching the InterruptedException, completing the work, and then rethrowing the exception.

    • cancel

      public static void cancel(Object task)
      Causes the task referenced by the supplied argument to be cancelled. If the referenced task is currently executing, it will continue until finished but will not be rescheduled.
      Parameters:
      task - a task reference
    • isCancelled

      public static boolean isCancelled(Object task)
      Retrieves whether the specified argument references a cancelled task.
      Parameters:
      task - a task reference
      Returns:
      true if referenced task is cancelled
    • isFixedRate

      public static boolean isFixedRate(Object task)
      Retrieves whether the specified argument references a task scheduled periodically using fixed rate scheduling.
      Parameters:
      task - a task reference
      Returns:
      true if the task is scheduled at a fixed rate
    • isFixedDelay

      public static boolean isFixedDelay(Object task)
      Retrieves whether the specified argument references a task scheduled periodically using fixed delay scheduling.
      Parameters:
      task - a task reference
      Returns:
      true if the reference is scheduled using a fixed delay
    • isPeriodic

      public static boolean isPeriodic(Object task)
      Retrieves whether the specified argument references a task scheduled for periodic execution.
      Parameters:
      task - a task reference
      Returns:
      true if the task is scheduled for periodic execution
    • getLastScheduled

      public static Date getLastScheduled(Object task)
      Retrieves the last time the referenced task was executed, as a Date object. If the task has never been executed, null is returned.
      Parameters:
      task - a task reference
      Returns:
      the last time the referenced task was executed; null if never
    • setPeriod

      public static Object setPeriod(Object task, long period)
      Sets the periodicity of the designated task to a new value.

      If the designated task is cancelled or the new period is identical to the task's current period, then this invocation has essentially no effect and the submitted object is returned.

      Otherwise, if the new period is greater than the designated task's current period, then a simple assignment occurs and the submitted object is returned.

      If neither case holds, then the designated task is cancelled and a new, equivalent task with the new period is scheduled for immediate first execution and returned to the caller.

      Parameters:
      task - the task whose periodicity is to be set
      period - the new period
      Returns:
      a task reference, as per the rules stated above.
    • getNextScheduled

      public static Date getNextScheduled(Object task)
      Retrieves the next time the referenced task is due to be executed, as a Date object. If the referenced task is cancelled, null is returned.
      Parameters:
      task - a task reference
      Returns:
      the next time the referenced task is due to be executed