public interface TimerManager
TimerManagers are bound to a Java EE component using a resource-reference, similar to a WorkManager or DataSource. Each lookup returns a new logical TimerManager who's lifecycle can be managed independently of all other TimerManagers. Components should cache the TimerManager rather than look it up every time.
All TimerManagers are bound to the lifecycle of the application that looks it up. When the application state changes, all TimerManagers associated with that application will be stopped, suspended or resumed, depending on the capabilities of the application server. TimerManagers are configured by the server administrator. The vendor specific systems management console allows the administrator to create one or more TimerManagers and associate a JNDI name with each one. The administrator may specify implementation specific information such as the maximum number of concurrent timers or thread priorities for each TimerManager. An application that requires a TimerManager should declare a resource-ref in the EJB or webapp that needs the TimerManager. The vendor descriptor editor or Java EE IDE can be used to bind this resource-ref to a physical TimerManager at deploy or development time. An EJB or servlet can then get a reference to a TimerManager by looking up the resource-ref name in JNDI and then casting it. For example, if the resource-ref was called tm/TimerManager:
<resource-ref> <res-ref-name>tm/TimerManager</res-ref-name> <res-type>commonj.timers.TimerManager</res-type> <res-auth>Container</res-auth> <res-sharing-scope>Unshareable</res-sharing-scope> </resource-ref>The res-auth is ignored in this version of the specification. The sharing scope must be set to unshareable. If this is specified as shareable then a vendor specific action will occur. The Java code to look this up would look like:
InitialContext ic = new InitialContext(); TimerManager tm = (TimerManager)ic.lookup("java:comp/env/tm/TimerManager");The EJB or servlet can then use the TimerManager as it needs to.
Recurring timers will execute their TimerListener multiple times. Invocations of the TimerListener are executed serially. That is, if a timer is scheduled to repeat every 5 seconds and a previous execution is still running, then the subsequent execution is delayed until the currently running execution completes.
A TimerListener scheduled multiple times, resulting in the return of multiple Timer instances, may execute concurrently depending on implementation. Proper thread safety techniques need to be employed.
When a TimerListener is scheduled, the declared context that is present on the thread (the Java EE context) will be saved and propagated to the asynchronous methods that are executed. This Java EE context at minimum will contain the java:comp namespace and ClassLoader of the scheduler unless specified otherwise. Other Java EE contexts such as security or a transactional context may be optionally added by the application server vendor. Global transactions are always available using the java:comp/UserTransaction JNDI name and are used in the same fashion as they are used in servlets and bean-managed transaction Enterprise Java Beans.
Two types of repeating timers are available:
For example, if a fixed-delay timer was to execute every hour on the hour and missed 5 executions because the TimerManager was suspended for over 5 hours, when the TimerManager is resumed, the TimerListener would execute immediately and the next execution would occur one hour after the completion of the TimerListener.
Modifier and Type | Field | Description |
---|---|---|
static long |
IMMEDIATE |
This constant can be used as a timeout for the waitForXXX methods.
|
static long |
INDEFINITE |
This constant can be used as a timeout for either the waitForXXX methods.
|
Modifier and Type | Method | Description |
---|---|---|
boolean |
isStopped() |
Returns true if all TimerListeners have completed following stop.
|
boolean |
isStopping() |
Returns true if this TimerManager is stopping or has been stopped.
|
boolean |
isSuspended() |
Returns true if all TimerListeners have completed following suspend.
|
boolean |
isSuspending() |
Returns true if this TimerManager is in the process
of or has completed suspending.
|
void |
resume() |
Resume the TimerManager.
|
Timer |
schedule(TimerListener listener,
long delay) |
Schedules a TimerListener to execute once after the specified delay.
|
Timer |
schedule(TimerListener listener,
long delay,
long period) |
Schedules a TimerListener to execute repeatedly using fixed-delay
execution after the specified delay.
|
Timer |
schedule(TimerListener listener,
java.util.Date time) |
Schedules a TimerListener to execute at a specified time.
|
Timer |
schedule(TimerListener listener,
java.util.Date firstTime,
long period) |
Schedules a TimerListener to execute repeatedly using fixed-delay
execution after the
firstTime elapses. |
Timer |
scheduleAtFixedRate(TimerListener listener,
long delay,
long period) |
Schedules a TimerListener to execute repeatedly using fixed-rate
execution after the specified delay.
|
Timer |
scheduleAtFixedRate(TimerListener listener,
java.util.Date firstTime,
long period) |
Schedules a TimerListener to execute repeatedly using fixed-rate
execution after the
firstTime elapses. |
void |
stop() |
Destroy the TimerManager.
|
void |
suspend() |
Suspend the TimerManager.
|
boolean |
waitForStop(long timeout_ms) |
Blocks until all TimerListeners have completed execution after a stop
request, or the timeout occurs, or the current thread is
interrupted, whichever happens first.
|
boolean |
waitForSuspend(long timeout_ms) |
Blocks until all TimerListeners have completed execution after a suspend
request, or the timeout occurs, or the current thread is
interrupted, whichever happens first.
|
static final long IMMEDIATE
static final long INDEFINITE
void suspend()
Execution of listeners for timers that expire while the TimerManager is suspended is deferred until the TimerManager is resumed.
This method will return immediately. Use the
isSuspended()
and waitForSuspend(long)
methods to determine the state of the suspend.
java.lang.IllegalStateException
- if this TimerManager has been stopped.boolean isSuspending() throws java.lang.IllegalStateException
java.lang.IllegalStateException
- if this TimerManager has been stopped.boolean isSuspended() throws java.lang.IllegalStateException
java.lang.IllegalStateException
- if this TimerManager has been stopped.boolean waitForSuspend(long timeout_ms) throws java.lang.InterruptedException, java.lang.IllegalStateException, java.lang.IllegalArgumentException
timeout_ms
- the maximum time to waitjava.lang.InterruptedException
- if interrupted while waitingjava.lang.IllegalStateException
- if this TimerManager has been stopped.java.lang.IllegalArgumentException
- thrown if the timeout_ms is negative.void resume() throws java.lang.IllegalStateException
java.lang.IllegalStateException
- if this TimerManager has been stopped.void stop() throws java.lang.IllegalStateException
StopTimerListener.stopTimer
events will be
called serially with any TimerListener.timerExpired
methods. They will not execute concurrently. If a TimerListener
is executing, the stopTimer
method will be called after the
timerExpired
method has completed.
CancelTimerListener.timerCancel
events do not execute
as a result of this method
Once the a timer manager has been stopped, it can never be re-started. Attempts to schedule a TimerListener, and resume or suspend the TimerManager will result in a thrown IllegalStateException.
java.lang.IllegalStateException
- If this TimerManager was already stopped.boolean isStopped()
boolean isStopping()
boolean waitForStop(long timeout_ms) throws java.lang.InterruptedException, java.lang.IllegalArgumentException
timeout_ms
- the maximum time to waitjava.lang.InterruptedException
- if interrupted while waitingjava.lang.IllegalArgumentException
- thrown if the timeout_ms is negative.Timer schedule(TimerListener listener, java.util.Date time) throws java.lang.IllegalArgumentException, java.lang.IllegalStateException
listener
- the TimerListener implementation to invoke when the timer expires.time
- the time at which the timer will expire.java.lang.IllegalArgumentException
- thrown when the listener or firstTime is nulljava.lang.IllegalStateException
- thrown when the TimerManager has been stopped.Timer schedule(TimerListener listener, long delay) throws java.lang.IllegalArgumentException, java.lang.IllegalStateException
listener
- the TimerListener implementation to invoke when the Timer expires.delay
- the number of milliseconds to wait before the Timer expires.java.lang.IllegalArgumentException
- thrown when the listener is null or the delay is negative.java.lang.IllegalStateException
- thrown when the TimerManager has been stopped.Timer schedule(TimerListener listener, java.util.Date firstTime, long period) throws java.lang.IllegalArgumentException, java.lang.IllegalStateException
firstTime
elapses.TimerListeners are executed at a constant delay based on the actual execution time. Each subsequent execution time is based off of the period and the end time of the previous execution. The period is the delay in between TimerListener executions.
listener
- the TimerListener implementation to invoke when the Timer expires.firstTime
- the time at which the first TimerListener will execute.period
- the number of milliseconds between repeating expiration intervals.java.lang.IllegalArgumentException
- thrown when the listener or firstTime is null or the period is negative.java.lang.IllegalStateException
- thrown when the TimerManager has been stopped.Timer schedule(TimerListener listener, long delay, long period) throws java.lang.IllegalArgumentException, java.lang.IllegalStateException
TimerListeners are executed at a constant delay based on the actual execution time. Each subsequent execution time is based off of the period and the end time of the previous execution. The period is the delay in between TimerListener executions.
listener
- the TimerListener implementation to invoke when the Timer expires.delay
- the number of milliseconds to wait before the first Timer expires.period
- the number of milliseconds between repeating expiration intervals.java.lang.IllegalArgumentException
- thrown when the listener is null or the period or delay is negative.java.lang.IllegalStateException
- thrown when the TimerManager has been stopped.Timer scheduleAtFixedRate(TimerListener listener, java.util.Date firstTime, long period) throws java.lang.IllegalArgumentException, java.lang.IllegalStateException
firstTime
elapses.TimerListeners are executed at a constant rate based on the initial scheduled execution time. Each subsequent execution time is based off of the period and the first execution time. This is appropriate for recurring activities that are sensitive to absolute time, such as ringing a chime every hour on the hour. It is also appropriate for recurring activities where the total time to perform a fixed number of executions is important, such as a countdown timer that ticks once every second for ten seconds.
listener
- the TimerListener implementation to invoke when the Timer expires.firstTime
- the time at which the first timer will execute.period
- the number of milliseconds between repeating expiration intervals.java.lang.IllegalArgumentException
- thrown when the listener or firstTime is null or the period is negative.java.lang.IllegalStateException
- thrown when the TimerManager has been stopped.Timer scheduleAtFixedRate(TimerListener listener, long delay, long period) throws java.lang.IllegalArgumentException, java.lang.IllegalStateException
TimerListeners are executed at a constant rate based on the initial scheduled execution time. Each subsequent execution time is based off of the period and the first execution time. This is appropriate for recurring activities that are sensitive to absolute time, such as ringing a chime every hour on the hour. It is also appropriate for recurring activities where the total time to perform a fixed number of executions is important, such as a countdown timer that ticks once every second for ten seconds.
listener
- the TimerListener implementation to invoke when the Timer expires.delay
- the number of milliseconds to wait before the first Timer expires.period
- the number of milliseconds between repeating expiration intervals.java.lang.IllegalArgumentException
- thrown when the listener is null or the period or delay is negative.java.lang.IllegalStateException
- thrown when the TimerManager has been stopped.