Oracle Application Server Containers for J2EE 10g (10.0.3)

How-To: Use a container-managed Timer service in EJB

• Understand what is a Timer service
• Deploy an application containing CMP entity bean that uses a container-managed Timer service
• Test your deployed EJBs that use a Timer service

Software Requirements

• OC4J 10.0.3.0.0 Developer Preview is installed, available from OTN
• Jakarta Ant, to build the application example, available here
• Sun's JDK 1.4_01 or above, available here

Notation

• %OC4J_HOME% - The directory you installed OC4J too.
• %J2EE_HOME% - The directory where the oc4j.jar file exists within OC4J. This is typically 2 directories under %OC4J_HOME%. For example, if you installed OC4J to c:\ then %J2EE_HOME% would be c:\j2ee\home
• %JAVA_HOME% - The directory where your JDK is installed

Introduction

The EJB 2.1 specification introduced a new feature that allows EJBs a coarse-grained, transactional, time-based event notifications. The timer service can be used to enable EJBs to model and manage higher-level business logic. OC4J supports timers with both entity beans and statelesss sessions. In this example we will demonstrate use of timer with a CMP entity bean. OC4J supports timers for CMP entity beans either using the native Persistence Manager or using the Toplink CMP engine. This sample demonstrates the use timer with CMP entity beans using the Native Persistence Manager.

For example, the timer service can be used do one of the following:

• Run a report after every 8 hours
• Cleanup a temporary table after a specified interval of time
  

In order to use a container-managed Timer service you have to do the following:

• The Entity bean class must implement javax.ejb.TimedObject
• Create a method in the Entity bean class to invoke and create the timer object. Expose the method in the remote/local interface of the EJB. This method will be called by the client to
• Implement the ejbTimeOut() method to perform the business logic when the timer is expired
  

The EJBs

This sample uses EmployeeBean which is CMP entity bean that uses the container-managed Timer service.

Following is code snippet from EmployeeBean.java.

....

public abstract class EmployeeBean implements EntityBean, TimedObject
{

...

public void initializeTimer(long timeout, String info) throws RemoteException
{
try {
TimerService ts = ctx.getTimerService();
ts.createTimer(timeout, info);
System.out.println("Timer created at " + System.currentTimeMillis() +
" with a timeout: " + timeout + " and with info: " + info);
} catch (Exception e) {
}
return;
}

...

public void ejbTimeout(Timer timer)
{
System.out.println("ejbTimeout() called at: " + System.currentTimeMillis() +
" with info: " + timer.getInfo());
return;
}
}

 

Expose the initializeTimer method in the remote interface of entity bean; Employee.java.

public interface Employee extends EJBObject
{
...
public void initializeTimer(long timeout, String info) throws RemoteException;
}

An Example

The example contains an EJB, and one JSP. EmployeeBean uses the EJB Timer Service. This example is based on the EMP table in the SCOTT schema.

• src/ - contains all Java source code for the example.
• sql/
• tab.sql - Script to create EMPPIC table and constraints
• ejb/cmpapp
• EmployeeHome.java - Employee EJB home
• EmployeeBean.java - Employee EJB bean class
• Employee.java - Employee remote interface.
• web/ 
• index.html - welcome file for the demo
• create.jsp - a JSP that creates the Employee bean and registers the Timer
  
• etc/
• ejb-jar.xml - deployment descriptor for entity bean
• orion-ejb-jar.xml - defines the mapping of entity bean to the table
• application.xml - J2EE application deployment descriptor
  
• doc/
• how-to-ejb-timer.html - This document.
• build.xml - An Ant build file.
• common.xml - Used by build.xml.

Configuring your environment

We have provided a build script for building the application using Ant. Alternatively you can use the pre-bulit enterprise archive file  ejbtimer-app.ear located in the lib directory. This example assumes the default password for your application to be welcome. If you have a different password, please modify the password in the ant build script i.e. build.xml as follows:

<property name="deploy.password" value="ToYourPassword" />

Using Ant and admin.jar

1. Ensure Ant 1.4.x or above is installed on your machine and configured correctly.
   
   
2. Set JAVA_HOME and OC4J_HOME environment variables.  Note: On some operating systems Ant does not currently support the use of environment variables,  if this is the case for your operating system,  please modify the common.xml file located in the root example directory.
   
   
3. From the example application root directory [the directory where the build.xml file is located] execute the following command:  

   ant

4. Your should now have a newly created ejbtimer-app.ear file in your <example_home >/lib directory .
   
   
   
5. Deploy this J2EE application to a running instance of OC4J 10.0.3 by executing the following commands from the J2EE_HOME directory. This assumes the default password for OC4J to be welcome.

   ant deploy-usingadmin.jar
                               

You should be now ready to run this demo application.

Running the application

1. Test the application by accessing the web app at the URL http://<hostname>:8888/ejbtimer/
   
   
2. After the welcome page is displayed you can enter the employee information and timer information and and click on the Submit button and you will see the Employee record and timer successfully processed.
3. Now look at the OC4J console that the EJB timer be successfully created and ejbTimeout method be invoked after the timer was expired.
   
   

Summary

In this document you should have:

• Understood what is Timer service
• Learnt to utilize Timer service in EJB