org.hsqldb.lib
Class HsqlTimer

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

All Implemented Interfaces:

ObjectComparator

public class HsqlTimer

extends Object

implements ObjectComparator

Provides facility for threads 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. This class is a JDK 1.1 compatible implementation required by HSQLDB because the java.util.Timer class is available only in JDK 1.3+.

Since:

1.7.2

Version:

1.7.2

Author:

boucherb@users.sourceforge.net

Nested Class Summary

protected class	HsqlTimer.Task A wrapper class used to schedule a Runnable object for execution by the enclosing HsqlTimer's TaskRunner in a background thread.
protected class	HsqlTimer.TaskQueue Extends HsqlArrayHeap to allow all pending tasks to be cancelled when the queue is cleared.
protected class	HsqlTimer.TaskRunner The Runnable that the background thread uses to execute scheduled tasks.

Field Summary

protected HsqlTimer.TaskQueue	taskQueue The priority queue for the scheduled tasks.
protected HsqlTimer.TaskRunner	taskRunner The inner runnable that executes tasks in the background thread.
protected Thread	taskRunnerThread The background thread.
protected ThreadFactory	threadFactory The factory that procduces the background threads.

Constructor Summary

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

HsqlTimer(ThreadFactory tf)
Constructs a new HsqlTimer using the specified thread factory implementation.

Method Summary

protected HsqlTimer.Task	addTask(long n, Runnable r, long p, boolean b) Adds to the task queue a new Task object encapsulating the supplied Runnable and scheduling arguments.
static void	cancel(Object task) Causes the task referenced by the supplied argument to be cancelled.
protected void	clearThread() Sets the background thread to null.
int	compare(Object a, Object b) ObjectComparator implemtation required to back priority queue for scheduled tasks.
static Date	getLastScheduled(Object task) Retrieves the last time the referenced task was executed, as a Date object.
static Date	getNextScheduled(Object task) Retrieves the next time the referenced task is due to be executed, as a Date object.
Thread	getThread() Retrieves the background thread that is currently being used to execute submitted tasks.
static boolean	isCancelled(Object task) Retreives whether the specified argument references a cancelled task.
static boolean	isFixedDelay(Object task) Retreives whether the specified argument references a task scheduled periodically using fixed delay scheduling.
static boolean	isFixedRate(Object task) Retreives whether the specified argument references a task scheduled periodically using fixed rate scheduling.
static boolean	isPeriodic(Object task) Retreives whether the specified argument references a task scheduled for periodic execution.
protected HsqlTimer.Task	nextTask() Retrieves the next task to execute, or null if the background thread is interrupted.
void	restart() (Re)starts background processing of the task queue.
Object	scheduleAfter(long delay, Runnable r) Causes the specified Runnable to be executed once in the background after the specified delay.
Object	scheduleAt(Date date, Runnable r) Causes the specified Runnable to be executed once in the background at the specified time.
Object	schedulePeriodicallyAfter(long delay, long p, Runnable r, boolean relative) Causes the specified Runnable to be executed periodically in the background, starting after the specified delay.
Object	schedulePeriodicallyAt(Date date, long p, Runnable r, boolean relative) Causes the specified Runnable to be executed periodically in the background, starting at the specified time.
void	shutDown() Causes all pending tasks to be cancelled and then stops background processing.

Methods inherited from class java.lang.Object

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

Field Detail

taskQueue

protected final HsqlTimer.TaskQueue taskQueue

The priority queue for the scheduled tasks.

taskRunner

protected final HsqlTimer.TaskRunner taskRunner

The inner runnable that executes tasks in the background thread.

taskRunnerThread

protected Thread taskRunnerThread

The background thread.

threadFactory

protected ThreadFactory threadFactory

The factory that procduces the background threads.

Constructor Detail

HsqlTimer

public HsqlTimer()

Constructs a new HsqlTimer using the default thread factory implementation.

HsqlTimer

public HsqlTimer(ThreadFactory tf)

Constructs a new HsqlTimer using the specified thread factory implementation.

Parameters:

tf - the ThreadFactory used to produce the background threads. If null, the implementation supplied by HsqlThreadFactory will be used.

Method Detail

compare

public int compare(Object a,
                   Object b)

ObjectComparator implemtation required to back priority queue for scheduled tasks.

Specified by:

compare in interface ObjectComparator

Parameters:

a - the first Task

b - the second Task

Returns:

0 if equal, < 0 if a < b, > 0 if a > b

getThread

public Thread getThread()

Retrieves the background thread that is currently being used to execute submitted tasks. null is returned if there is no such thread.

Returns:

the current background thread or null

restart

public void restart()

(Re)starts background processing of the task queue.

scheduleAfter

public Object scheduleAfter(long delay,
                            Runnable r)

Causes the specified Runnable to be executed once in the background after the specified delay.

Parameters:

delay - in milliseconds

r - the Runnable to execute.

Returns:

opaque reference to the internal task

scheduleAt

public Object scheduleAt(Date date,
                         Runnable r)

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

r - the Runnable to execute.

Returns:

opaque reference to the internal task

schedulePeriodicallyAt

public Object schedulePeriodicallyAt(Date date,
                                     long p,
                                     Runnable r,
                                     boolean relative)

Causes the specified Runnable to be executed periodically in the background, starting at the specified time.

Parameters:

p - the cycle period

relative - if true, fixed rate sheduling else fixed period scheduling

date - time at which to execute the specified Runnable

r - the Runnable to execute

Returns:

opaque reference to the internal task

schedulePeriodicallyAfter

public Object schedulePeriodicallyAfter(long delay,
                                        long p,
                                        Runnable r,
                                        boolean relative)

Causes the specified Runnable to be executed periodically in the background, starting after the specified delay.

Parameters:

p - the cycle period

relative - if true, fixed rate sheduling else fixed period scheduling

delay - in milliseconds

r - the Runnable to execute.

Returns:

opaque reference to the internal task

shutDown

public void shutDown()

Causes all pending tasks to be cancelled and then stops background processing.

cancel

public static void cancel(Object task)
                   throws ClassCastException

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

Throws:

ClassCastException - if the task argument cannot be cast to the type of reference returned by a scheduleXXX method invocation.

isCancelled

public static boolean isCancelled(Object task)
                           throws ClassCastException

Retreives whether the specified argument references a cancelled task.

Parameters:

task - a task reference

Returns:

true if referenced task is cancelled

Throws:

ClassCastException - if the task argument cannot be cast to the type of reference returned by a scheduleXXX method invocation.

isFixedRate

public static boolean isFixedRate(Object task)
                           throws ClassCastException

Retreives 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

Throws:

ClassCastException - if the task argument cannot be cast to the type of reference returned by a scheduleXXX method invocation.

isFixedDelay

public static boolean isFixedDelay(Object task)
                            throws ClassCastException

Retreives whether the specified argument references a task scheduled periodically using fixed delay scheduling.

Parameters:

task - a task reference

Returns:

if the task is scheduled using a fixed rate

Throws:

ClassCastException - if the task argument cannot be cast to the type of reference returned by a scheduleXXX method invocation.

isPeriodic

public static boolean isPeriodic(Object task)
                          throws ClassCastException

Retreives whether the specified argument references a task scheduled for periodic execution.

Parameters:

task - a task reference

Returns:

true ifthe task is scheduled for periodic execution

Throws:

ClassCastException - if the task argument cannot be cast to the type of reference returned by a scheduleXXX method invocation.

getLastScheduled

public static Date getLastScheduled(Object task)
                             throws ClassCastException

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

Throws:

ClassCastException - if the task argument cannot be cast to the type of reference returned by a scheduleXXX method invocation.

getNextScheduled

public static Date getNextScheduled(Object task)
                             throws ClassCastException

Retrieves the next time the referenced task is due to be executed, as a Date object. If the task has been cancelled, null is returned.

Parameters:

task - a task reference

Returns:

the next time the referenced task is due to be executed

Throws:

ClassCastException - if the task argument cannot be cast to the type of reference returned by a scheduleXXX method invocation.

addTask

protected HsqlTimer.Task addTask(long n,
                                 Runnable r,
                                 long p,
                                 boolean b)

Adds to the task queue a new Task object encapsulating the supplied Runnable and scheduling arguments.

Parameters:

n - the time of the first execution

r - the Runnable to execute

p - the periodicity

b - if true, use fixed rate else use fixed period

Returns:

a reference to the scheduled task

clearThread

protected void clearThread()

Sets the background thread to null.

nextTask

protected HsqlTimer.Task nextTask()

Retrieves the next task to execute, or null if the background thread is interrupted.

Returns:

the next task to execute, or null