Overview | Package | Class | Use | Tree | Deprecated | Index | Help
|  | BEA Systems, Inc.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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:

- fixed-rate - 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.
  If a fixed-rate execution is delayed for any reason (such as garbage collection, suspension, or other background activity), the late TimerListener will execute one time immediately, and then again at the next scheduled fixed-rate time.
  For example, if a fixed-rate 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 will run once immedately, and each execution thereafter will be on the hour.

- fixed-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.
  If a fixed-delay execution is delayed for any reason (such as garbage collection, suspension, or other background activity), subsequent executions will be delayed as well. In the long run, the frequency of execution will generally be slightly lower than the reciprocal of the specified period (assuming the system clock underlying Object.wait(long) is accurate). Fixed-delay execution is appropriate for recurring activities that require "smoothness". In other words, it is appropriate for activities where it is more important to keep the frequency accurate in the short run than in the long run. This includes most animation tasks, such as blinking a cursor at regular intervals. It also includes tasks wherein regular activity is performed in response to human input, such as automatically repeating a character as long as a key is held down.

  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.

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Documentation is available at http://e-docs.bea.com/wls/docs92 Copyright 2006 BEA Systems Inc.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD