commonj.timers
Interface TimerManager


public interface TimerManager

The TimerManager is used to manager a set of logical timers. All Timer objects created with this TimerManager can be centrally administered by using the suspend, resume and stop methods.

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 which can be destroyed independently of all other TimerManagers. Components should cache the TimerManager rather than look it up every time.

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.

Each Timer must implement the TimerListener interface or one of its derivatives.

Recurring timers are executed serially. This means that if a timer is repeating every .5 seconds and while processing the last timer fired then the new one is delayed until the old one finishes.

TimerListeners for different Timer instance may be executed concurrently depending on implementation.


Method Summary
 void resume()
          Resume the TimerManager.
 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.
 Timer schedule(TimerListener listener, long delay)
          See schedule(commonj.timers.TimerListener, java.util.Date, long) for a description of this methods operation.
 Timer schedule(TimerListener listener, long delay, long period)
          See schedule(commonj.timers.TimerListener, java.util.Date, long) for a description of this methods operation.
 Timer scheduleAtFixedRate(TimerListener listener, java.util.Date firstTime, long period)
          See schedule(commonj.timers.TimerListener, java.util.Date, long) for a description of this methods operation.
 Timer scheduleAtFixedRate(TimerListener listener, long delay, long period)
          See schedule(commonj.timers.TimerListener, java.util.Date, long) for a description of this methods operation.
 void stop()
          Destroy the timer manager.
 void suspend()
          Suspend the TimerManager.
 

Method Detail

suspend

public void suspend()
Suspend the TimerManager. All currently executing listeners fired methods are permitted to complete and the caller is blocked until they do complete. Execution of listener fired methods for timers that expire while the timer manager is suspended is deferred until the TimerManager is resumed.

Throws:
java.lang.IllegalStateException - If this TimerManager was already stopped.

resume

public void resume()
Resume the TimerManager. All scheduled TimerListener listeners that have expired while suspended will executed immediately.

Throws:
java.lang.IllegalStateException - If this TimerManager was already stopped.

stop

public void stop()
Destroy the timer manager. All currently executing TimerListeners are permitted to complete. The caller is blocked until all in-progress TimerListener.timerExpired and StopTimerListener.timerStop listener methods have completed.

Once the a timer manager has been stopped, it can never be re-started. Attempts to schedule a Timer, and resume or suspend the TimerManager will result in a thrown IllegalStateException.

Throws:
java.lang.IllegalStateException - If this TimerManager was already stopped.

schedule

public Timer schedule(TimerListener listener,
                      java.util.Date time)
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:
java.lang.IllegalArgumentException
java.lang.IllegalStateException - If this TimerManager is stopped.

schedule

public Timer schedule(TimerListener listener,
                      java.util.Date firstTime,
                      long period)
Schedules a TimerListener to execute repeatedly. If the firstTime parameter is specified, the Timer will not expire until the firstTime elapses.

Subsequent executions take place at approximate intervals as specified by the delay argument. When using fixed-rate execution, each expiration time is calculated relative to the actual execution time of the previous execution. If an execution is delayed for any reason (such as garbage collection 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-rate 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.

Parameters:
listener - the TimerListener implementation to invoke when the Timer expires.
firstTime - the time at which the first timer will expire.
period - the number of milliseconds between repeating expiration intervals.
Returns:
the resulting Timer object.
Throws:
java.lang.IllegalArgumentException
java.lang.IllegalStateException - If this TimerManager is stopped.

schedule

public Timer schedule(TimerListener listener,
                      long delay)
See schedule(commonj.timers.TimerListener, java.util.Date, long) for a description of this methods operation.

Parameters:
listener - the TimerListener implementation to invoke when the Timer expires.
delay - the number of milliseconds to wait before the first Timer expires.
Returns:
the resulting Timer object.
Throws:
java.lang.IllegalArgumentException
java.lang.IllegalStateException - If this TimerManager is stopped.

schedule

public Timer schedule(TimerListener listener,
                      long delay,
                      long period)
See schedule(commonj.timers.TimerListener, java.util.Date, long) for a description of this methods operation.

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:
java.lang.IllegalArgumentException
java.lang.IllegalStateException - If this TimerManager is stopped.

scheduleAtFixedRate

public Timer scheduleAtFixedRate(TimerListener listener,
                                 java.util.Date firstTime,
                                 long period)
See schedule(commonj.timers.TimerListener, java.util.Date, long) for a description of this methods operation.

Parameters:
listener - the TimerListener implementation to invoke when the Timer expires.
firstTime - the time at which the first timer will expire.
period - the number of milliseconds between repeating expiration intervals.
Returns:
the resulting Timer object.
Throws:
java.lang.IllegalArgumentException
java.lang.IllegalStateException - If this TimerManager is stopped.

scheduleAtFixedRate

public Timer scheduleAtFixedRate(TimerListener listener,
                                 long delay,
                                 long period)
See schedule(commonj.timers.TimerListener, java.util.Date, long) for a description of this methods operation.

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:
java.lang.IllegalArgumentException
java.lang.IllegalStateException - If this TimerManager is stopped.


Copyright BEA Systems, Inc. and International Business Machines Corp 2003. All rights reserved.