How-To Develop a Message Driven Bean using EJB 3.0

Date: 10/18/05
Author: Debu Panda

Introduction
• Message Driven Bean example using EJB 3.0
• Sample EJB Client
• Prerequisites
• What you need to know
• Software requirements
• Notations
• Building the Application
• Running the Application
• Examine the Sample File Directories
• Configure the Environment
• Start the Server
• Generate, Compile and Deploy the Application
• Run the application
• Summary

Introduction

This example application demonstrates Oracle's support for the EJB 3.0 specification for a Message Driven Bean and dependency injection of EJBContext and creation of a Timer from the injected EJBContext.

EJB 3.0 greatly simplifies the development of EJBs, removing many complex development tasks. For an MDB, the bean class do not have to implement the javax.ejb.MessageDrivenBean interface and do not have to implement the lifecycle methods and you longer require a deployment descriptor to specify the message destination and factory information.

The MessageDrivenContext for the MDB can be achieved using dependency injection.

Message Driven Bean example using EJB 3.0

The following is the bean class for the MessageLogger MDB. Note that this is a pure Java class  and does not implement javax.ejb.MessageDrivenBean. 

@MessageDriven(
activationConfig = { 
	@ActivationConfigProperty(propertyName="connectionFactoryJndiName",propertyValue="jms/TopicConnectionFactory"),
	@ActivationConfigProperty(propertyName="destinationName",
			propertyValue="jms/demoTopic"), 
	@ActivationConfigProperty(propertyName="destinationType",propertyValue="javax.jms.Topic"),
	@ActivationConfigProperty(propertyName="messageSelector",propertyValue="RECIPIENT = 'MDB'") } ) 
public class MessageLogger implements TimedObject { 

@Resource javax.ejb.TimerService ts ; 
public void onMessage(Message message) 
{ 
		System.out.println("onMessage() - " + message); 
try 
{ 

	String subject = message.getStringProperty("subject"); 
	String inmessage = message.getStringProperty("message"); 
	Timer timer = ts.createTimer(30000, subject); 
} 

Note that the bean uses the @MessageDriven annotation to mark the bean as a Message Driven EJB. @ActivationConfig can be used to specify the various messaging system properties like the message destination, type, etc. You can override these properties by specifying these in the deployment descriptor.

The TimerService can be injected with Resource injection and it can be used to create a Timer.

Sample JMS Client

The Sample JMS client uses JMS 1.1 API to send a message to the destination on which the MDB is listening on. The MDB gets activated after the message arrives on the message destination and then creates the timer.

Prerequisites

What you need to know

In order to complete the example application, you should be familiar with the following:

EJB 3.0

For further information on EJB 3.0, see the following documents on OTN:

Link to other EJB 3.0 Howto's on OTN

EJB 3.0 Proposed Final Draft Specification from Sun Web Site

Software Requirements

This demonstration requires that the following software components are installed and configured correctly:

Oracle Application Server 10g 10.1.3

Sun's JDK version 1.5 or above, available here

Any HTML browser like Mozilla, Microsoft Internet Explorer, Netscape, etc.

Notations

%ORACLE_HOME%< - The directory where you installed Oracle's EJB 3.0 container.

%JAVA_HOME% - The directory where your JDK is installed

%HOWTO_HOME%

Building the Application

The Javadoc for this application is located in the %HOWTO_HOME%/doc/javadoc/ directory.

The configuration files are located in the %HOWTO_HOME%/etc directory, including deployment descriptor files such as application.xml.

Running the Application

To run the sample application on a standalone instance of Oracle Application Server 10g 10.1.3, follow these steps:

1. Examine the Sample File Directories

• build - temporary directory created during the build
• log - temporary directory holding build/deploy logs

• etc - all necessary files to package the application
• lib - holds the application archives that could be deployed
• doc - the How-to document and Javadoc's
  • javadoc - the javadoc of the different source files
  • how-to-ejb30-mdb.html - this How-to page
• src - the source of the demo
  • ejb - contains the sample mdb code
  • client - contains application client code

2. Configure the Environment

Ensure that the following environment variables are defined:

• %ORACLE_HOME% - The directory where you installed OC4J.
• %JAVA_HOME% - The directory where you installed the JDK.
• %PATH% - includes %ORACLE_HOME% /ant/bin

3. Starting OC4J instance

Start OC4J stand alone using the following command after you make the above changes.

 >%ORACLE_HOME%/bin/oc4j -start 

If you are using an OracleAS managed install, start using the following command after you make the above changes.

> %ORACLE_HOME%/opmn/bin/opmnctl startall

4. Generate, Compile, and Deploy the Application

Ant 1.6.2 is shipped with OC4J and you have to set your PATH environment variable to $ORACLE_HOME/ant/bin. 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 ant-oracle.xml file located in the %HOWTO_HOME% directory.

Edit ant-oracle.properties (in the demo directory) and ensure the following properties are set to the correct values, as indicated below for OC4J standalone:

• oc4j.host: host where OC4J is running (default localhost)
• oc4j.admin.port: RMI port number (default 23791)
• oc4j.admin.user: admin user name (default oc4jadmin)
• oc4j.admin.password: admin user password (default welcome)
• oc4j.binding.module: website name where deployed web modules are bound (default http-web-site)

If you are using OracleAS managed install then you have appropriately change the following properties beside changing oc4j.admin.user and oc4j.admin.password for your managed OC4J instance in OracleAS install.

• opmn.host: the hostname/IP where OracleAS is running (default localhost)
• opmn.port: OPMN request port (default 6003) for the OracleAS install
• oc4j.instance: admin user name (default oc4jadmin)

You have to uncomment appropriate deployer.uri in the ant-oracle.properties based on your environment i.e. a single instance OC4J or a clustered OC4J instance/group managed by OPMN.

You have to make changes in jndi.properties such as provider.url, principal and credential appropriate to your environment. If you are using OracleAS install, you have to use provider.url in the following format: opmn:ormi://localhost:6003:home/ejb30mdb.

>ant 

You should now have the newly created ejb30mdb.ear in your %HOWTO_HOME%/lib directory.

This command would also attempt to deploy the application if the build is successful. It will first test whether OC4J is running.

Note that you can also deploy the application separately . Ensure the %ORACLE_HOME% environment variable is defined, and from the %HOWTO_HOME% directory, type the command:

>ant deploy

5. Run the Application

Run the sample by providing the following command, including a name as the program argument:

>ant run 

Return to the console where you started OC4J and you will see output generated by the MDB.

Summary

In this document, you should have learned how to:

• Develop a Simple Message Driven Bean using EJB 3.0 and how to use dependency injection to inject EJBContext
• Deploy a Simple MDB in the Oracle Application Server 10g 10.1.3 container