- All Implemented Interfaces:
Comparator
,ThreadFactory
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
ConstructorsConstructorDescriptionConstructs a new HsqlTimer using the default thread factory implementation.HsqlTimer
(ThreadFactory threadFactory) Constructs a new HsqlTimer. -
Method Summary
Modifier and TypeMethodDescriptionstatic void
Causes the task referenced by the supplied argument to be cancelled.int
Required to back the 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.Retrieves the background execution thread.static boolean
isCancelled
(Object task) Retrieves whether the specified argument references a cancelled task.static boolean
isFixedDelay
(Object task) Retrieves whether the specified argument references a task scheduled periodically using fixed delay scheduling.static boolean
isFixedRate
(Object task) Retrieves whether the specified argument references a task scheduled periodically using fixed rate scheduling.static boolean
isPeriodic
(Object task) Retrieves whether the specified argument references a task scheduled for periodic execution.Default ThreadFactory implementation.void
restart()
(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
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 versionvoid
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 Details
-
HsqlTimer
public HsqlTimer()Constructs a new HsqlTimer using the default thread factory implementation. -
HsqlTimer
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
Required to back the priority queue for scheduled tasks.- Specified by:
compare
in interfaceComparator
- Parameters:
a
- the first Taskb
- the second Task- Returns:
0 if equal, < 0 if a < b, > 0 if a > b
-
newThread
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 interfaceThreadFactory
- Parameters:
runnable
- used to construct the new Thread.- Returns:
- a new Thread constructed from the designated runnable.
-
getThread
Retrieves the background execution thread.null is returned if there is no such thread.
- Returns:
- the current background thread (may be null)
-
restart
(Re)starts background processing of the task queue.- Throws:
IllegalStateException
- if this timer is shut down.- See Also:
-
scheduleAfter
Causes the specified Runnable to be executed once in the background after the specified delay.- Parameters:
delay
- in millisecondsrunnable
- the Runnable to execute.- Returns:
- opaque reference to the internal task
- Throws:
IllegalArgumentException
- if runnable is null
-
scheduleAt
Causes the specified Runnable to be executed once in the background at the specified time.- Parameters:
date
- time at which to execute the specified Runnablerunnable
- 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 Runnableperiod
- the cycle periodrunnable
- the Runnable to executerelative
- 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 millisecondsperiod
- the cycle periodrunnable
- 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
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
Retrieves whether the specified argument references a cancelled task.- Parameters:
task
- a task reference- Returns:
- true if referenced task is cancelled
-
isFixedRate
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
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
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
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
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 setperiod
- the new period- Returns:
- a task reference, as per the rules stated above.
-
getNextScheduled
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
-