javax.ejb.TimerHandle

The TimerHandle provides a serializable handle to a specific timer. There is a restriction that states that the TimerHandle cannot be exposed though a remote interface (including a web service endpoint). The container provider is responsible for implementing this interface.

Timer getTimer()

This method gives the bean instance access to a timer object from the TimerHandle, which may have been serialized. The timer object can then be queried according to the APIs in the timer interface described below.

javax.ejb.Timer

The timer interface represents the registration of a timer notification in the system. It provides the ability to query the timer as well as to cancel an upcoming notification. The container provider is responsible for implementing this interface.

void cancel()

This method cancels the timer if it is called before the expiration time, which means that the container will not invoke the ejbTimeout() method of the associated bean implementing the TimedObject interface. If the cancel invocation is made within a transaction, and the transaction fails to commit, then the timer is not canceled. Further invocations on a timer that has already been canceled yield a javax.ejb.NoSuchObjectLocalException.

long getTimeRemaining()

This method returns the time remaining in milliseconds before the timer will invoke the associated bean implementing the TimedObject interface. This method is used with interval-based timers.

java.util.Date getNextTimeout()

For expiration-based timers, this method is used to determine when the next timeout period is scheduled to occur for the timer.

javax.ejb.TimerHandle getHandle()

This method returns a serializable handle to a timer. The interface of the TimerHandle is described above.

java.io.Serializable getInfo()

This method can be used to return information about the timer. The parameter can be any serializable object that was used in the aforementioned createTimer() method. The bean can use the getInfo() method of the passed timer object to recognize any of these domain-specific parameters and conditionally execute timer logic according to the value of the getInfo() method.

Example Payroll

To illustrate the fundamental concepts of the timer service capabilities, we will now look at a practical example of how the timer service can be employed to tackle a common timer-based application. Payroll within an enterprise is a commonly executed business operation. In this example, we will look at conducting our payroll every month and use the EJB 2.1 timer service for this purpose.

The code in this example will focus on the implementation and registration of timers, rather than on the intricacies of the federal tax laws. We will define a simple stateless session bean with a single exposed business method, processPayroll(). First, we define the remote interface of the EJB component in Listing 10-10.

Listing 10-10: Remote interface of the Payroll EJB.

 package ejb.payroll; import java.rmi.RemoteException; import javax.ejb.EJBObject; public interface Payroll extends EJBObject {     public void processPayroll() throws RemoteException; } 

The home interface for the Payroll EJB is also very simple. Being a stateless session bean means that we have only a single create() method with no parameters (Listing 10-11).

Listing 10-11: Home interface of the Payroll EJB.

 package ejb.payroll; import java.rmi.RemoteException; import javax.ejb.CreateException; import javax.ejb.EJBHome; public interface PayrollHome extends EJBHome {     public Payroll create()         throws RemoteException, CreateException; } 

Many examples that you will see create the timers in the ejbCreate method of an EJB. This is perhaps a bad practice. For example, with stateless session beans, the developer has no standard way to control how many instances of the bean are created in the method-ready pool. If the code to create the timer is in the ejbCreate method of that specific bean, then it may be executed multiple times, resulting in multiple timers being registered and later notified. Listing 10-12 shows the bean implementation of the Payroll EJB.

Listing 10-12: Bean implementation of the Payroll EJB.

 package ejb.payroll; import javax.ejb.CreateException; import javax.ejb.EJBException; import javax.ejb.SessionBean; import javax.ejb.SessionContext; import javax.ejb.TimedObject; import javax.ejb.Timer; import javax.ejb.TimerService; import javax.naming.Context; import javax.naming.InitialContext; import javax.naming.NamingException; import javax.sql.DataSource; public class PayrollBean implements SessionBean, TimedObject {     private SessionContext beanCtx = null;     public void ejbCreate()         throws CreateException     {     }     public void ejbRemove() {     }     public void processPayroll() {         System.out.println("PayrollBean-processPayroll");       //process the payroll       //...       //...       //reregister payroll for next month       registerPayroll();     }     private void registerPayroll() {         System.out.println("PayrollBean-registerPayroll");         TimerService timerService = beanCtx.getTimerService(); //Create a new Calendar and increment one month and reregister the invocation        java.util.Calendar calendar = new java.util.GregorianCalendar();        calendar.setTime(new java.util.Date(System.currentTimeMillis()));        calendar.add(calendar.MONTH, 1);        Timer timer = timerService.createTimer(calendar.getTime(),               "Monthly Payroll");     }    public void ejbTimeout(Timer timer) {        processPayroll();     }     public void ejbPassivate() { }     public void ejbActivate() { }     public void setSessionContext(SessionContext ctx) {         this.beanCtx = ctx;     } } 

The Payroll EJB component has a single private method that can create a new timer. Each time that the method processPayroll is invoked, a new timer registration is created using the private registerPayroll. It should be noted that the transactional attributes defined on the processPayroll method will affect the behavior of the timer service. If the transaction is rolled back, then the timer registration is revoked.

For our deployment descriptor settings, we have set the transactional attributes of the Payroll EJB to be required and the ejbTimeout method to be RequiresNew (Listing 10-13), so that any failed ejbTimeout invocations are automatically tried again by the container.

Listing 10-13: Deployment descriptor of the Payroll EJB.

 <?xml version="1.0" ?> <ejb-jar version="2.1" xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd">   <description>     Deployment Descriptor for Session-Bean Payroll.   </description>   <enterprise-beans>     <session>       <ejb-name>Payroll</ejb-name>       <home>ejb.payroll.PayrollHome</home>       <remote>ejb.payroll.Payroll</remote>       <ejb-class>ejb.payroll.PayrollBean</ejb-class>       <session-type>Stateless</session-type>       <transaction-type>Container</transaction-type>       <security-identity>       <run-as>         <role-name>accounts</role-name>        </run-as>       </security-identity>     </session>   </enterprise-beans>   <assembly-descriptor>     <security-role>        <role-name>accounts</role-name>     </security-role>     <container-transaction>       <method>         <ejb-name>Payroll</ejb-name>         <method-name>*</method-name>       </method>       <trans-attribute>Required</trans-attribute>     </container-transaction>     <container-transaction>       <method>         <ejb-name>Payroll</ejb-name>         <method-name>ejbTimeout</method-name>         <method-params>           <method-param>javax.ejb.Timer</method-param>         </method-params>       </method>       <trans-attribute>RequiresNew</trans-attribute>     </container-transaction>   </assembly-descriptor> </ejb-jar> 

The deployment descriptor also shows the setting of the security role that the container will use for timer invocations. A future version of the specification may add the ability to configure timers directly in the deployment descriptor.