Download FAQ History

API Search Feedback

Using the Timer Service

Applications that model business work flows often rely on timed notifications. The timer service of the enterprise bean container enables you to schedule timed notifications for all types of enterprise beans except for stateful session beans. You can schedule a timed notification to occur at a specific time, after a duration of time, or at timed intervals. For example, you could set timers to go off at 10:30 AM on May 23, in 30 days, or every 12 hours.

When a timer expires (goes off), the container calls the ejbTimeout method of the bean's implementation class. The ejbTimeout method contains the business logic that handles the timed event. Because ejbTimeout is defined by the javax.ejb.TimedObject interface, the bean class must implement TimedObject.

There are four interfaces in the javax.ejb package that are related to timers:

TimedObject
Timer
TimerHandle
TimerService

Creating Timers

To create a timer, the bean invokes one of the createTimer methods of the TimerService interface. (For details on the method signatures, see the TimerService API documentation.) When the bean invokes createTimer, the timer service begins to count down the timer duration.

The bean described in The TimerSessionBean Example creates a timer as follows:

TimerService timerService = context.getTimerService();
Timer timer = timerService.createTimer(intervalDuration,
  "created timer"); 

In the TimerSessionBean example, createTimer is invoked in a business method, which is called by a client. An entity bean can also create a timer in a business method. If you want to create a timer for each instance of an entity bean, you can code the createTimer call in the bean's ejbCreate method.

Timers are persistent. If the server is shut down (or even crashes), timers are saved and will become active again when the server is restarted. If a timer expires while the server is down, the container will call ejbTimeout when the server is restarted.

A timer for an entity bean is associated with the bean's identity--that is, with a particular instance of the bean. If an entity bean sets a timer in ejbCreate, for example, each bean instance will have its own timer. In contrast, stateless session and message-driven beans do not have unique timers for each instance.

The Date and long parameters of the createTimer methods represent time with the resolution of milliseconds. However, because the timer service is not intended for real-time applications, a callback to ejbTimeout might not occur with millisecond precision. The timer service is for business applications, which typically measure time in hours, days, or longer durations.

Canceling and Saving Timers

Timers can be canceled by the following events:

When a single-event timer expires, the EJB container calls ejbTimeout and then cancels the timer.
When an entity bean instance is removed, the container cancels the timers associated with the instance.
When the bean invokes the cancel method of the Timer interface, the container cancels the timer.

If a method is invoked on a canceled timer, the container throws the javax.ejb.NoSuchObjectLocalException.

To save a Timer object for future reference, invoke its getHandle method and store the TimerHandle object in a database. (A TimerHandle object is serializable.) To reinstantiate the Timer object, retrieve the handle from the database and invoke getTimer on the handle. A TimerHandle object cannot be passed as an argument of a method defined in a remote or Web service interface. In other words, remote clients and Web service clients cannot access a bean's TimerHandle object. Local clients, however, do not have this restriction.

Getting Timer Information

In addition to defining the cancel and getHandle methods, the Timer interface defines methods for obtaining information about timers:

public long getTimeRemaining();
public java.util.Date getNextTimeout();
public java.io.Serializable getInfo(); 

The getInfo method returns the object that was the last parameter of the createTimer invocation. For example, in the createTimer code snippet of the preceding section, this information parameter is a String object with the value created timer.

To retrieve all of a bean's active timers, call the getTimers method of the TimerService interface. The getTimers method returns a collection of Timer objects.

Transactions and Timers

An enterprise bean usually creates a timer within a transaction. If this transaction is rolled back, the timer creation is also rolled back. Similarly, if a bean cancels a timer within a transaction that gets rolled back, the timer cancellation is rolled back. In this case, the timer's duration is reset as if the cancellation had never occurred.

In beans that use container-managed transactions, the ejbTimeout method usually has the RequiresNew transaction attribute to preserve transaction integrity. With this attribute, the EJB container begins the new transaction before calling ejbTimeout. If the transaction is rolled back, the container will try to call ejbTimeout at least one more time.

The TimerSessionBean Example

The source code for this example is in the <INSTALL>/j2eetutorial14/examples/ejb/timersession/src/ directory.

TimerSessionBean is a stateless session bean that shows how to set a timer. The implementation class for TimerSessionBean is called TimerSessionBean. In the source code listing of TimerSessionBean that follows, note the myCreateTimer and ejbTimeout methods. Because it's a business method, myCreateTimer is defined in the bean's remote interface (TimerSession) and can be invoked by the client. In this example, the client invokes myCreateTimer with an interval duration of 30,000 milliseconds. The myCreateTimer method fetches a TimerService object from the bean's SessionContext. Then it creates a new timer by invoking the createTimer method of TimerService. Now that the timer is set, the EJB container will invoke the ejbTimer method of TimerSessionBean when the timer expires--in about 30 seconds. Here's the source code for the TimerSessionBean class:

import javax.ejb.*;

public class TimerSessionBean implements SessionBean,
    TimedObject {

    private SessionContext context;

    public TimerHandle myCreateTimer(long intervalDuration) {

        System.out.println
            ("TimerSessionBean: start createTimer ");
        TimerService timerService = 
            context.getTimerService();
        Timer timer = 
            timerService.createTimer(intervalDuration, 
          "created timer");
}

    public void ejbTimeout(Timer timer) {
  
        System.out.println("TimerSessionBean: ejbTimeout ");
    }

    public void setSessionContext(SessionContext sc) {
        System.out.println("TimerSessionBean:
            setSessionContext");
        context = sc;
     }

     public void ejbCreate() {
        System.out.println("TimerSessionBean: ejbCreate");
     }

     public TimerSessionBean() {}
     public void ejbRemove() {}
     public void ejbActivate() {}
     public void ejbPassivate() {}

}  

Building TimerSessionBean

In a terminal window, go to the <INSTALL>/j2eetutorial14/examples/ejb/timersession/ directory. To build TimerSessionBean, type the following command:

asant build 

Use deploytool to package and deploy this example.

Creating the Application

In this section, you'll create a J2EE application named TimerSessionApp, storing it in the file TimerSessionApp.ear.

In deploytool, select FileNewApplication.
Click Browse.
In the file chooser, navigate to <INSTALL>/j2eetutorial14/examples/ejb/timersession/.
In the File Name field, enter TimerSessionApp.ear.
Click New Application.
Click OK.
Verify that the TimerSessonApp.ear file resides in <INSTALL>/j2eetutorial14/examples/ejb/timersession/.

Packaging the Enterprise Bean

Start the Edit Enterprise Bean wizard by selecting FileNewEnterprise JavaBean. The wizard displays the following dialog boxes.

In the Introduction dialog box:
Read the explanatory text for an overview of the wizard's features.
Click Next.
In the EJB JAR dialog box:
Select the button labeled Create New JAR Module in Application.
In the combo box below this button, select TimerSessionApp.
In the JAR Display Name field, enter TimerSessionJAR.
Click Edit Contents.
In the tree under Available Files, locate the <INSTALL>/j2eetutorial14/examples/ejb/timersession/build/ directory.
Select these classes: TimerSession.class, TimerSessionBean.class, and TimerSessionHome.class.
Click Add.
Click OK.
Click Next.
In the General dialog box:
In the Enterprise Bean Class combo box, select TimerSessionBean.
In the Enterprise Bean Name field, enter TimerSessionBean.
Under Bean Type, select Stateless Session.
In the Remote Interfaces section, select TimerSessionHome for the Remote Home Interface, and TimerSession for the Remote Interface.
Click Next.
In the Expose as Web Service Endpoint dialog box:
Select No for Expose Bean as Web Service Endpoint.
Click Next.
Click Finish.

Compiling the Application Client

The application client files are compiled at the same time as the enterprise bean files.

Packaging the Application Client

To package an application client component, you run the New Application Client wizard of deploytool. During this process the wizard performs the following tasks.

Creates the application client's deployment descriptor
Puts the deployment descriptor and client files into a JAR file
Adds the JAR file to the application's TimerSessionApp.ear file

To start the New Application Client wizard, select FileNewApplication Client. The wizard displays the following dialog boxes.

Introduction dialog box
Read the explanatory text for an overview of the wizard's features.
Click Next.
JAR File Contents dialog box
Select the button labeled Create New AppClient Module in Application.
In the combo box below this button, select TimerSessionApp.
In the AppClient Display Name field, enter TimerSessionClient.
Click Edit Contents.
In the tree under Available Files, locate the <INSTALL>/j2eetutorial14/examples/ejb/timersession/build directory.
Select the TimerSessionClient.class file.
Click Add.
Click OK.
Click Next.
General dialog box
In the Main Class combo box, select TimerSessionClient.
Click Next.
Click Finish.

Specifying the Application Client's Enterprise Bean Reference

When it invokes the lookup method, the TimerSessionClient refers to the home of an enterprise bean:

Object objref =
  initial.lookup("java:comp/env/ejb/SimpleTimerSession"); 

You specify this reference as follows.

In the tree, select TimerSessionClient.
Select the EJB Ref's tab.
Click Add.
In the Coded Name field, enter ejb/SimpleTimerSession.
In the EJB Type field, select Session.
In the Interfaces field, select Remote.
In the Home Interface field, enter TimerSessionHome.
In the Local/Remote Interface field, enter TimerSession.
In the JNDI Name field, select TimerSessionBean.
Click OK.

Deploying the Enterprise Application

Now that the J2EE application contains the components, it is ready for deployment.

Select TimerSessionApp.
Select ToolsDeploy.
Under Connection Settings, enter the user name and password for the Application Server.
Under Application Client Stub Directory, check Return Client Jar.
In the field below the checkbox, enter <INSTALL>/j2eetutorial14/examples/ejb/timersession/.
Click OK.
In the Distribute Module dialog box, click Close when the deployment completes.
Verify the deployment.
In the tree, expand the Servers node and select the host that is running the Application Server.
In the Deployed Objects table, make sure that TimerSessionApp is listed and that its status is Running.
Verify that TimerSessionAppClient.jar is in <INSTALL>/j2eetutorial14/examples/ejb/timersession/.

Running the Application Client

To run the application client, perform the following steps.

In a terminal window, go to the <INSTALL>/j2eetutorial14/
examples/ejb/timersession/ directory.
Type the following command:

appclient -client TimerSessionAppClient.jar

In the terminal window, the client displays these lines:

Creating a timer with an interval duration of 30000 ms.

The output from the timer is sent to the server.log file located in the <J2EE_HOME>/domains/domain1/server/logs/ directory.

View the output in the Admin Console:

Open the Admin Console by opening a Web browser window to

http://localhost:4848/asadmin/admingui

Click the Logging tab.
Click Open Log Viewer.
At the top of the page, you'll see these four lines in the Message column:

ejbTimeout
start createTimer
ejbCreate
setSessionContext

Alternatively, you can look at the log file directly. After about 30 seconds, open server.log in a text editor and you will see the following lines:

TimerSessionBean: setSessionContext
TimerSessionBean: ejbCreate
TimerSessionBean: start createTimer
TimerSessionBean: ejbTimeout  

Download FAQ History

API Search Feedback

All of the material in The J2EE(TM) 1.4 Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.