MDB Using OracleAS JMS

The MDB can process incoming asynchronous requests using OracleAS JMS. When you use OracleAS JMS, this JMS provider is already available since it is bundled with OC4J. And all configuration for the JMS provider occurs within the OC4J XML files; thus, only steps three and four (as listed in "MDB Overview") are necessary.

Note:

The entire MDB example is available on OTN from the OC4J sample code page at http://www.oracle.com/technology/tech/java/oc4j/demos/ on the OTN Web site.

Figure 9-1 shows how a client sends an asynchronous request directly to the OracleAS JMS queue or topic that is located internally within OC4J. The MDB receives the message directly from OracleAS JMS.

Figure 9-1 Demonstration of an MDB Interacting with an OracleAS JMS Destination

Description of the illustration mdb2.gif

The following sections demonstrate an MDB that uses OracleAS JMS as the JMS provider.

Configure OracleAS JMS in the XML files
Create the OC4J-Specific Deployment Descriptor to Use OracleAS JMS
Deploying the MDB

Note:
A full description of how to use each JMS provider is available in the JMS chapter in the Oracle Application Server Containers for J2EE Services Guide.

Configure OracleAS JMS in the XML files

OracleAS JMS is automatically enabled. You only configure the JMS Destination objects used by the MDB. If your MDB accesses a database for inquiries and so on, then you can configure the DataSource used. See "JMS Destination Object Configuration" for the JMS configuration. For information on data source configuration, see the Data Source chapter in the Oracle Application Server Containers for J2EE Services Guide.

JMS Destination Object Configuration

Configure the topic or queue in the jms.xml file to which the client sends all messages that are destined for the MDB. The name, location, and connection factory for either Destination type must be specified.

The following jms.xml file configuration specifies a queue—named jms/Queue/rpTestQueue—that is used by the rpTestMdb example. The queue connection factory is defined as jms/Queue/myQCF. In addition, a topic is defined named jms/Topic/rpTestTopic, with a connection factory of jms/Topic/myTCF.

<?xml version="1.0" ?>
<!DOCTYPE jms-server PUBLIC "OracleAS JMS server" "http://xmlns.oracle.com/ias/dtds/jms-server.dtd">

<jms-server port="9128">
   <queue location="jms/Queue/rpTestQueue"> </queue>
   <queue-connection-factory location="jms/Queue/myQCF">
   </queue-connection-factory>

   <topic location="jms/Topic/rpTestTopic"> </topic>
   <topic-connection-factory location="jms/Topic/myTCF">
   </topic-connection-factory>

    <!-- path to the log-file where JMS-events/errors are stored -->
    <log>
        <file path="../log/jms.log" />
    </log>
</jms-server>

Create the OC4J-Specific Deployment Descriptor to Use OracleAS JMS

The OC4J-specific deployment descriptor configures the following:

Specify the Destination and connection factory JNDI locations to the MDB through the <message-driven-deployment> element in the orion-ejb-jar.xml file. See "Specify the Destination and Connection Factory" for full details.
Associate any logical names defined as resource references in the ejb-jar.xml file to the correct queue or topic, which, for OracleAS JMS, is defined in the jms.xml file. You could have several topics and queues defined in the jms.xml file. See "Map Any Resource References to JNDI Names" for full details on mapping the resource references in the orion-ejb-jar.xml file.

Since this example uses resource references in the ejb-jar.xml file, the orion-ejb-jar.xml file maps these logical names to the actual JNDI names of the connection factory and the JMS Destination object, which are defined in the jms.xml file. In this example, the MDB uses a queue that is defined in the jms.xml file as jms/Queue/rpTestQueue. The queue connection factory is defined in the jms.xml file as jms/Queue/myQCF.

Specify the Destination and Connection Factory

Map the Destination and connection factory JNDI locations to the MDB through the <message-driven-deployment> element in the orion-ejb-jar.xml file. The following is the orion-ejb-jar.xml deployment descriptor for the rpTestMdb example. It maps a JMS Queue to the rpTestMdb MDB, providing the following:

MDB name, as defined in the <ejb-name> in the EJB deployment descriptor, is specified in the name attribute.
JMS Destination, as defined in the jms.xml file, is specified in the destination-location attribute.
JMS Destination Connection Factory, as defined in the jms.xml file, is specified in the connection-factory-location attribute.
If this was a topic, then a durable topic name, which is user-defined, is specified in the subscription-name attribute.
Listener threads, as defined in the listener-threads attribute, is an optional parameter. The listener threads are spawned off when MDBs are deployed and are used to listen for incoming JMS messages on the topic or queue. These threads concurrently consume JMS messages. The default is one thread. Topics always have only one thread.

Once all of these are specified in the <message-driven-deployment> element, the container knows how to map the MDB to the correct JMS Destination.

<enterprise-beans>
  ...
  <message-driven-deployment name="rpTestMdb" 
     connection-factory-location="jms/Queue/myQCF"
     destination-location="jms/Queue/rpTestQueue" >
  </message-driven-deployment>
  ...
</enterprise-beans>

If you wanted to specify a topic, you must also include the subscription name, as follows:

<enterprise-beans>
  <message-driven-deployment name="rpTestMdb" 
      connection-factory-location="jms/Queue/myQCF"
      destination-location="jms/Queue/rpTestQueue" 
      subscription-name="MDBSUB" >
  ...
</enterprise-beans>

Note:

You cannot use logical names in these fields. You must specify the full JNDI syntax for both the connection factory and the Destination object.

Map Any Resource References to JNDI Names

When you define logical names as resource references for your connection factory and Destination object, you have to map these to the actual JNDI names.

Map the resource reference for the queue connection factory in the <resource-ref-mapping> element. In the rpTestMdb example, the logical name for the connection factory is jms/myQueueConnectionFactory. This must be mapped to the JNDI string of jms/Queue/myQCF, which is defined in the jms.xml file.
Map the resource reference for the Destination object in the <resource-env-ref-mapping> element. In the rpTestMdb example, the logical name for the queue is jms/persistentQueue. This is mapped to the JNDI string of jms/Queue/rpTestQueue, which is defined in the jms.xml file.

<resource-ref-mapping name="jms/myQueueConnectionFactory"
       location="jms/Queue/myQCF"/>
<resource-env-ref-mapping name="jms/persistentQueue"
       location="jms/Queue/rpTestQueue" />

Example 9-3 The orion-ejb-jar.xml file for the rpTestMdb Example

The following lists the complete orion-ejb-jar.xml file for the rpTestMdb example. It includes both the definition of the OracleAS JMS objects and the resource reference mappings.

<enterprise-beans>
  <message-driven-deployment name="testMdb" 
     connection-factory-location="jms/Queue/myQCF"
    destination-location="jms/Queue/rpTestQueue" listener-threads="1">

    <resource-ref-mapping name="jms/myQueueConnectionFactory"
       location="jms/Queue/myQCF"/>
	    <resource-env-ref-mapping name="jms/persistentQueue"
       location="jms/Queue/rpTestQueue" />
  </message-driven-deployment>
</enterprise-beans>
<assembly-descriptor>
  <default-method-access>
    <security-role-mapping name="&lt;default-ejb-caller-role&gt;"
                           impliesAll="true" />
  </default-method-access>
</assembly-descriptor>

Deploying the MDB

Archive your EJB into a JAR file. You deploy the MDB the same way as the session bean, which is detailed in Prepare the EJB Application for Assembly and "Deploy the Enterprise Application to OC4J".

Note:

Instructions on how a client sends a JMS message to the MDB is discussed in "Client Access of MDB".