Sun Java System Application Server 

Samples Index

The Timer Service Sample Application

The Timer Service sample application demonstrates how to schedule timed notifications for all types of enterprise beans except stateful session beans. The ability to handle timed notifications is often important for applications that model business workflows. 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.

Overview of EJB Timers

When a timer expires (goes off), the Enterprise JavaBeans (EJB) 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.

Four interfaces in the javax.ejb package are related to timers:

You must start the relational database before starting the application.

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 creates a timer as follows: 

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

In the TimerSessionEJB 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 could 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.

Cancelling and Saving Timers

Timers may cancelled by the following events:

If a method is invoked on a cancelled 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 re-instantiate 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 also 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 with container-managed transactions, the ejbTimeout method usually has the RequiresNew transaction attribute. 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 TimerSessionEJB Example

TimerSessionEJB is a stateless session bean that shows how to set a timer. The implementation class for TimerSessionEJB 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 may be invoked by the client. In this example, the client invokes myCreateTimer with an interval duration of 30000 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.

Setting Up the Environment

Before you deploy or run the application, you must ensure that a database resource has been configured for Application Server. The included asant deployment script automatically performs this step for you. But if you are using another deployment mechanism, you must perform it manually.

You can use any JDBC-compliant relational database server, but specific instructions are provided for the following:

Building, Deploying, and Running the Application

The general instructions for building, deploying, and running sample applications are provided in Building, Deploying, and Running Sample Applications. In reading this document, use the following application-specific variables for this application:

Follow this general procedure:

  1. Build the Application. The build file, build.xml, is in the app_dir directory, specifically, install_dir/samples/ejb/misc/apps/timersession.
  2. Deploy the Application. The EAR file is app_dir/timersession.ear.
  3. Run the application. Follow the instructions in the next section.

Running the Application Client

To run the application client, set your current directory to app_dir directory, install_dir/samples/ejb/misc/apps/timersession. Then type the following command: 

install_dir/bin/appclient -client timersessionClient.jar
-xml domain_root_dir/domain_name/config/sun-acc.xml

For example, to run the client in domain "domain1", enter this command: 

install_dir/bin/appclient -client timersessionClient.jar
-xml install_dir/domains/domain1/config/sun-acc.xml

In the terminal window, the client displays: 

Creating a timer with an interval duration of 30000 ms.

The output from the timer is sent to domain_root_dir/domain_name/server/logs/server.log. After about 30 seconds, view server.log and you will see the following lines: 

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

Troubleshooting

If you get a java.rmi.RemoteException that states the message EJB Timer service is not available, the database server is either not running or was not started before Application Server.

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.