|
- Single Action Timer
- Interval Timer
a) Single Action Timer
A single action timer (or a single interval timer) is a one which will expire only once (as opposed to interval timer, where multiple expirations are possible).
Accordingly EJB supports two different ways for constructing a single interval timer.
i) One is to create the timer in such a way that it will expire at a particular point of time which is specified as a Date
ii) The other possible way is make the timer to expire after certain period of time (say after 10 hours or 1 day) which is usually specified in milliseconds. After the timer expires, the enterprise bean will receive a kind of notification, i.e the container will call the ejbTimeout() method (or the method that is annotated with @Timeout annotation).
b) Interval Timer
Interval timer (or multiple action timer), as its name suggests will recur (or happen) at multiple intervals of time. That is, these kinds of timer will have multiple expirations at regular intervals of time.
Two different ways of constructing the Timers are available:
i) The first approach is to create a timer to have an initial expiration at some point of time (which is usually specified as a Date) and to have the subsequent expirations happen at a specified interval.
ii) The second approach is to construct the timer whose initial expiration will happen after an elapsed duration of time (in milliseconds) and to have the subsequent expirations happen after a specific interval. For every expirations of the Timer object, the container continues to call the ejbTimeout() method (or the method that is annotated with @Timeout annotation) until the bean explicitly calls the cancel() method.
Timer Services API
The Timer Services API is small and has only 4 interfaces packaged with it. It is expected that more API related to Timer Services will be added in the future EJB specification. The interfaces are:
- TimerService
- Timer
- TimedObject
- TimerHandle
a) TimerService
This interface provides support for creating timers (single-action or interval) as well as retrieving the existing timers (that are created by one or more enterprise beans) from the container. Enterprise beans can use this interface for creating single-action or interval timer objects.
i) For creating timers
- Single-action Timers
The following two methods are available in the TimerService API for creating a single action timer:
- Timer createTimer(long duration, Serializable info)
- Timer createTimer(Date expiration, Serializable info)
Using the first method, a single action timer can be made to expire after a specified duration of time. The second method will be useful if the timer is needed to expire at a particular point of time. The second argument in both the versions will be useful, if application specific information has to be passed to the Timer objects, else it can be safely ignored by passing null.
- Interval Timers
Following are the ways to create an interval based timer object.
- Timer createTimer(long initialDuration, long intervalDuration, Serializable info)
- Timer createTimer(Date initialExpiration, long intervalDuration, Serializable info)
Interval timers have options to specify the initial expiration in the form of milliseconds or as a Date object and the subsequent expirations can be expressed in milliseconds. In the first version, the initial expiration for the Timer object will happen after the initialDuration has elapsed and subsequent expirations will happen at the specified intervalDuration. The second version supports in specifying the initial time of expiration as a Date object and the rest of the information is the same as that of the first version. Similar to single action timers, these timers also allows the enterprise beans to pass application specific information.
ii) For iterating over the existing timers
Collection getTimers() – This method will return a collection of timers that were already created by other enterprise beans that may be in different parts of the system.
b) Time
This interface holds information about the timer objects that was previously created by enterprise beans.
- Serializable getInfo ()
Returns the application specific object that was passed previously by the enterprise beans while creating timer objects. The object must implement the Serializable interface.
-
Date getNextTimeout()
Returns the time (as a Date object) that tells when the next expiration is going to happen for this timer object.
-
long getTimeRemaining()
Returns the number of remaining milliseconds that is left before the next expiration happens for this timer.
-
TimerHandle getHandle()
Returns an instance of TimerHandle object which at a later time can be used to reconstruct the Timer object.
-
void cancel()
Cancels the timer object. After cancellation, enterprise beans that have already registered for getting time-based notification (through the ejbTimeout() method) will no longer receive events.
c) TimedObject
Enterprise beans can implement this interface to receive time-based notifications (or callbacks) on Timer objects. The ejbTimeout() method will be invoked by the container whenever the timer expires.
For a single action timer, the ejbTimeout() will be called only once, whereas for an interval timer, this callback method may be called multiple times.
void ejbTimeout(java.ejb.Timer timer)
This method is called by the EJB Container when the timer object has expired.
There are two possible ways for implementing a call back method:
-
One way is to make the enterprise bean implement the TimedObject interface and to give an implementation for the ejbTimeout(Timer timer) method. For example,
@Stateless
@Remote
class MyBeanImpl implements MyBean, TimedObject{
Public void ejbTimedout(Timer timer){
.
.
}
}
-
The other way is to annotate a method that is defined within the enterprise bean class with the @Timeout annotation. In this case, there is no need for the enterprise bean to implement the TimedOut interface. The return type of this method must be void and it should accept only one argument of type Timer.
@Stateless
@Remote
class MyBeanImpl implements MyBean{
@Timeout
public void myTimedOutMethod(Timer timer){
....
}
}
d) TimerHandle
This interface is implemented by the container so that enterprise beans at a later point can use this handle to reconstruct the timer object. TimerHandle extends the Serializable interface. So, the clients may serialize the handle. Because of this, TimerHandle are local objects, hence it is illegal to pass this object as an argument to remote interfaces.
Timer getTimer()
Obtains a reference to the Timer object. |
