Module org.hsqldb
Package org.hsqldb.lib

## Class HsqlTimer

- java.lang.Object
- - org.hsqldb.lib.HsqlTimer

- All Implemented Interfaces:
    `java.util.Comparator`, `ThreadFactory`

      public final class HsqlTimer
      extends java.lang.Object
      implements java.util.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
    --- | ---
    `HsqlTimer()` | Constructs a new HsqlTimer using the default thread factory implementation.
    `HsqlTimer​(ThreadFactory threadFactory)` | Constructs a new HsqlTimer.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static void` | `cancel​(java.lang.Object task)` | Causes the task referenced by the supplied argument to be cancelled.
    `int` | `compare​(java.lang.Object a, java.lang.Object b)` | Required to back the priority queue for scheduled tasks.
    `static java.util.Date` | `getLastScheduled​(java.lang.Object task)` | Retrieves the last time the referenced task was executed, as a Date object.
    `static java.util.Date` | `getNextScheduled​(java.lang.Object task)` | Retrieves the next time the referenced task is due to be executed, as a Date object.
    `java.lang.Thread` | `getThread()` | Retrieves the background execution thread.
    `static boolean` | `isCancelled​(java.lang.Object task)` | Retrieves whether the specified argument references a cancelled task.
    `static boolean` | `isFixedDelay​(java.lang.Object task)` | Retrieves whether the specified argument references a task scheduled periodically using fixed delay scheduling.
    `static boolean` | `isFixedRate​(java.lang.Object task)` | Retrieves whether the specified argument references a task scheduled periodically using fixed rate scheduling.
    `static boolean` | `isPeriodic​(java.lang.Object task)` | Retrieves whether the specified argument references a task scheduled for periodic execution.
    `java.lang.Thread` | `newThread​(java.lang.Runnable runnable)` | Default ThreadFactory implementation.
    `void` | `restart()` | (Re)starts background processing of the task queue.
    `java.lang.Object` | `scheduleAfter​(long delay, java.lang.Runnable runnable)` | Causes the specified Runnable to be executed once in the background after the specified delay.
    `java.lang.Object` | `scheduleAt​(java.util.Date date, java.lang.Runnable runnable)` | Causes the specified Runnable to be executed once in the background at the specified time.
    `java.lang.Object` | `schedulePeriodicallyAfter​(long delay, long period, java.lang.Runnable runnable, boolean relative)` | Causes the specified Runnable to be executed periodically in the background, starting after the specified delay.
    `java.lang.Object` | `schedulePeriodicallyAt​(java.util.Date date, long period, java.lang.Runnable runnable, boolean relative)` | Causes the specified Runnable to be executed periodically in the background, starting at the specified time.
    `static java.lang.Object` | `setPeriod​(java.lang.Object task, long period)` | Sets the periodicity of the designated task to a new value.
    `void` | `shutdown()` | Shuts down this timer after the current task (if any) completes.
    `void` | `shutDown()` | for compatibility with previous version
    `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.

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

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

    - ### Methods inherited from interface java.util.Comparator

      `equals, reversed, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong`

- - ### Constructor Detail

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

    - #### compare

          public int compare​(java.lang.Object a,
                             java.lang.Object b)

      Required to back the priority queue for scheduled tasks.
      Specified by:
        `compare` in interface `java.util.Comparator`
      Parameters:
        `a` - the first Task
        `b` - the second Task
      Returns:
        `0 if equal, < 0 if a < b, > 0 if a > b`

    - #### newThread

          public java.lang.Thread newThread​(java.lang.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 java.lang.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 java.lang.IllegalStateException

      (Re)starts background processing of the task queue.
      Throws:
        `java.lang.IllegalStateException` - if this timer is shut down.
      See Also:
        `shutdown()`, `shutdownImmediately()`

    - #### scheduleAfter

          public java.lang.Object scheduleAfter​(long delay,
                                                java.lang.Runnable runnable)
                                         throws java.lang.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:
        `java.lang.IllegalArgumentException` - if runnable is null

    - #### scheduleAt

          public java.lang.Object scheduleAt​(java.util.Date date,
                                             java.lang.Runnable runnable)
                                      throws java.lang.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:
        `java.lang.IllegalArgumentException` - if date or runnable is null

    - #### schedulePeriodicallyAt

          public java.lang.Object schedulePeriodicallyAt​(java.util.Date date,
                                                         long period,
                                                         java.lang.Runnable runnable,
                                                         boolean relative)
                                                  throws java.lang.IllegalArgumentException

      Causes the specified Runnable to be executed periodically in the background, starting at the specified time.
      Parameters:
        `period` - the cycle period
        `relative` - if true, fixed rate scheduling else fixed delay scheduling
        `date` - time at which to execute the specified Runnable
        `runnable` - the Runnable to execute
      Returns:
        opaque reference to the internal task
      Throws:
        `java.lang.IllegalArgumentException` - if date or runnable is null, or period is `<= 0`

    - #### schedulePeriodicallyAfter

          public java.lang.Object schedulePeriodicallyAfter​(long delay,
                                                            long period,
                                                            java.lang.Runnable runnable,
                                                            boolean relative)
                                                     throws java.lang.IllegalArgumentException

      Causes the specified Runnable to be executed periodically in the background, starting after the specified delay.
      Parameters:
        `period` - the cycle period
        `relative` - if true, fixed rate scheduling else fixed delay scheduling
        `delay` - in milliseconds
        `runnable` - the Runnable to execute.
      Returns:
        opaque reference to the internal task
      Throws:
        `java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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 java.util.Date getLastScheduled​(java.lang.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 java.lang.Object setPeriod​(java.lang.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 java.util.Date getNextScheduled​(java.lang.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