Oracle Fusion Middleware
Oracle WebLogic Server API Reference
12c Release 1 (12.1.1)

Part Number E24391-02

commonj.timers
Interface TimerManager


public interface TimerManager

Applications use a TimerManager to schedule TimerListeners. Each of the TimerManager schedule methods returns a Timer object. The returned Timer can then be queried and/or cancelled. Applications are required to implement the TimerListener interface and may optionally implement one or both of the CancelTimerListener and StopTimerListener interfaces. All Timers execute in the same JVM as the thread that created the Timer and are transient. If the JVM fails then all Timers will be lost.

TimerManagers are bound to a J2EE 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 J2EE 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 J2EE context) will be saved and propagated to the asynchronous methods that are executed. This J2EE context at minimum will contain the java:comp namespace and ClassLoader of the scheduler unless specified otherwise. Other J2EE 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:

Since:
1.0

Field Summary
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.
 
Method Summary
 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, Date time)
          Schedules a TimerListener to execute at a specified time.
 Timer schedule(TimerListener listener, Date firstTime, long period)
          Schedules a TimerListener to execute repeatedly using fixed-delay execution after the firstTime elapses.
 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 scheduleAtFixedRate(TimerListener listener, Date firstTime, long period)
          Schedules a TimerListener to execute repeatedly using fixed-rate 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.
 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.
 

Field Detail

IMMEDIATE

static final long IMMEDIATE
This constant can be used as a timeout for the waitForXXX methods. It will check the current state of the TimerManager and return immediately with the result.

Since:
1.1
See Also:
Constant Field Values

INDEFINITE

static final long INDEFINITE
This constant can be used as a timeout for either the waitForXXX methods. It will cause the waitForXXX methods to block indefinitely until the the wait is satisfied.

Since:
1.1
See Also:
Constant Field Values
Method Detail

suspend

void suspend()
Suspend the TimerManager.

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 TimerManager.isSuspended() and TimerManager.waitForSuspend(long) methods to determine the state of the suspend.

Throws:
IllegalStateException - if this TimerManager has been stopped.
Since:
1.0

isSuspending

boolean isSuspending()
                     throws IllegalStateException
Returns true if this TimerManager is in the process of or has completed suspending.

Returns:
true if this TimerManager has been suspended
Throws:
IllegalStateException - if this TimerManager has been stopped.
Since:
1.1

isSuspended

boolean isSuspended()
                    throws IllegalStateException
Returns true if all TimerListeners have completed following suspend.

Returns:
true if all TimerListeners have completed following suspend
Throws:
IllegalStateException - if this TimerManager has been stopped.
Since:
1.1

waitForSuspend

boolean waitForSuspend(long timeout_ms)
                       throws InterruptedException,
                              IllegalStateException,
                              IllegalArgumentException
Blocks until all TimerListeners have completed execution after a suspend request, or the timeout occurs, or the current thread is interrupted, whichever happens first.

Parameters:
timeout_ms - the maximum time to wait
Returns:
true if this TimerManager suspended and false if the timeout elapsed before the suspend completed
Throws:
InterruptedException - if interrupted while waiting
IllegalStateException - if this TimerManager has been stopped.
IllegalArgumentException - thrown if the timeout_ms is negative.
Since:
1.1

resume

void resume()
            throws IllegalStateException
Resume the TimerManager. All scheduled timers that have expired while suspended will execute immediately. All fixed-rate timers will execute one time, and then again at the next scheduled fixed-rate time.

Throws:
IllegalStateException - if this TimerManager has been stopped.
Since:
1.0

stop

void stop()
          throws IllegalStateException
Destroy the TimerManager. All Timers are stopped and all currently executing listeners are permitted to complete.

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.

Throws:
IllegalStateException - If this TimerManager was already stopped.
Since:
1.0

isStopped

boolean isStopped()
Returns true if all TimerListeners have completed following stop.

Returns:
true if all TimerListeners have completed following stop
Since:
1.1

isStopping

boolean isStopping()
Returns true if this TimerManager is stopping or has been stopped.

Returns:
true if this TimerManager is stopping or has been stopped
Since:
1.1

waitForStop

boolean waitForStop(long timeout_ms)
                    throws InterruptedException,
                           IllegalArgumentException
Blocks until all TimerListeners have completed execution after a stop request, or the timeout occurs, or the current thread is interrupted, whichever happens first.

Parameters:
timeout_ms - the maximum time to wait
Returns:
true if this TimerManager stopped and false if the timeout elapsed before the stop completed
Throws:
InterruptedException - if interrupted while waiting
IllegalArgumentException - thrown if the timeout_ms is negative.
Since:
1.1

schedule

Timer schedule(TimerListener listener,
               Date time)
               throws IllegalArgumentException,
                      IllegalStateException
Schedules a TimerListener to execute at a specified time. If the time is in the past, the TimerListener will execute immediately.

Parameters:
listener - the TimerListener implementation to invoke when the timer expires.
time - the time at which the timer will expire.
Returns:
the resulting Timer object.
Throws:
IllegalArgumentException - thrown when the listener or firstTime is null
IllegalStateException - thrown when the TimerManager has been stopped.
Since:
1.0

schedule

Timer schedule(TimerListener listener,
               long delay)
               throws IllegalArgumentException,
                      IllegalStateException
Schedules a TimerListener to execute once after the specified delay.

Parameters:
listener - the TimerListener implementation to invoke when the Timer expires.
delay - the number of milliseconds to wait before the Timer expires.
Returns:
the resulting Timer object.
Throws:
IllegalArgumentException - thrown when the listener is null or the delay is negative.
IllegalStateException - thrown when the TimerManager has been stopped.
Since:
1.0

schedule

Timer schedule(TimerListener listener,
               Date firstTime,
               long period)
               throws IllegalArgumentException,
                      IllegalStateException
Schedules a TimerListener to execute repeatedly using fixed-delay execution after the 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.

Parameters:
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.
Returns:
the resulting Timer object.
Throws:
IllegalArgumentException - thrown when the listener or firstTime is null or the period is negative.
IllegalStateException - thrown when the TimerManager has been stopped.
Since:
1.0

schedule

Timer schedule(TimerListener listener,
               long delay,
               long period)
               throws IllegalArgumentException,
                      IllegalStateException
Schedules a TimerListener to execute repeatedly using fixed-delay execution after the specified delay.

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.

Parameters:
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.
Returns:
the resulting Timer object.
Throws:
IllegalArgumentException - thrown when the listener is null or the period or delay is negative.
IllegalStateException - thrown when the TimerManager has been stopped.
Since:
1.0

scheduleAtFixedRate

Timer scheduleAtFixedRate(TimerListener listener,
                          Date firstTime,
                          long period)
                          throws IllegalArgumentException,
                                 IllegalStateException
Schedules a TimerListener to execute repeatedly using fixed-rate execution after the 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.

Parameters:
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.
Returns:
the resulting Timer object.
Throws:
IllegalArgumentException - thrown when the listener or firstTime is null or the period is negative.
IllegalStateException - thrown when the TimerManager has been stopped.
Since:
1.0

scheduleAtFixedRate

Timer scheduleAtFixedRate(TimerListener listener,
                          long delay,
                          long period)
                          throws IllegalArgumentException,
                                 IllegalStateException
Schedules a TimerListener to execute repeatedly using fixed-rate execution after the specified delay.

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.

Parameters:
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.
Returns:
the resulting Timer object.
Throws:
IllegalArgumentException - thrown when the listener is null or the period or delay is negative.
IllegalStateException - thrown when the TimerManager has been stopped.
Since:
1.0

Copyright 1996, 2011, Oracle and/or its affiliates. All rights reserved. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

Oracle Fusion Middleware
Oracle WebLogic Server API Reference
12c Release 1 (12.1.1)

Part Number E24391-02