Module org.hsqldb
Package org.hsqldb.lib

Class 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