ONJava.com -- The Independent Source for Enterprise Java
oreilly.comSafari Books Online.Conferences.

advertisement

AddThis Social Bookmark Button

Using a JMS Provider with MDBs via the J2EE Connector Architecture
Pages: 1, 2

J2EE Connector Architecture

The J2EE Connector Architecture allows for the integration of application servers with Enterprise Information Systems (EIS) and legacy systems in a standardized manner. Just as JDBC allows connectivity between J2EE applications and databases, JCA allows connectivity between J2EE applications and legacy data in EIS in a standardized manner. A JCA resource adapter (RA) is built to connect and manipulate a particular EIS, just as a JDBC driver provides the ability to connect to a database. For example, Oracle Corporation has built a generic RA for OC4J that integrates many JMS providers such as Websphere MQ, Tibco, and OracleAS JMS. For more information about the JCA, please see the ONJava article "J2EE Connector Architecture," by Anthony Lai, Jyostna Laxminarayan and Lars Ewe.



JCA introduces two new contracts that allow pluggability of JMS providers with J2EE containers in a standardized fashion.

The Message Inflow contract between a J2EE container and a resource adapter allows delivery of asynchronous messages from the EIS to message endpoints located in the application's server, through the resource adapter interface. A message endpoint is essentially an MDB deployed in a J2EE container to listen via the JCA, and is available after the deployment of an application.

The Transaction Inflow contract between a J2EE container and a resource adapter allows the resource adapter to propagate transactions initiated by the EIS to the application server. This also provides the ability for transaction recovery whenever required, thus allowing MDBs, and other components via MDBs, to participate in distributed transactions that may involve a messaging provider used with the JCA RA.

JMS via Resource Adapter

The use of JMS providers is very common in J2EE applications. In this section, I will discuss the use of JMS providers via the resource adapter. Using MDBs with the resource adapter interface or a proprietary message provider interface does not require any code changes in the MDB. If you are planning to migrate your existing MDB applications to use a JMS provider via the resource adapter, you have to make some changes in the deployment descriptor (e.g., ejb-jar.xml). Figure 2 depicts an overview diagram of how an MDB works with a JMS provider with a resource adapter.

Figure 2
Figure 2. MDB using JMS provider with a JCA resource adapter

The following steps are required to configure an MDB to use a JMS provider with a resource adapter:

  • Make changes in the EJB deployment descriptor to use the resource adapter.
  • Deploy and configure the resource adapter in the container.
  • Configure the message destinations in the JMS provider.

I will use the simpleMdb example, presented above, to illustrate these steps.

MDB Deployment Descriptor

An MDB that is configured to listen on a message endpoint of a resource adapter requires the activation-config properties to be set in the deployment descriptor. The activation-config properties are a set of name-value pairs that are passed to the resource adapter when the MDB is deployed. The properties are defined according to the messaging provider used. However, the EJB 2.1 specification has defined the following standard properties:

  • acknowledgeMode : How the container acknowledges the delivery of the message. The two allowed values are Auto-acknowledge and Dups-ok-acknowledge. If Auto-acknowledge is selected, the EJB container sends an acknowledgement as soon as a message is received by an MDB. For Dups-ok-acknowledge mode, the container lazily sends the acknowledgement to the JMS provider.

  • messageSelector : An expression to filter messages for the MDB. If you wish to restrict the messages that a JMS message-driven bean receives, the bean provider can specify the value of the message selector using the activation-config-property deployment descriptor, as follows:

    <activation-config-property>
        <activation-config-property-name>
            MessageSelector
        </activation-config-property-name>
        <activation-config-property-value>
            RECIPIENT='MDB'
        </activation-config-property-value>
    </activation-config-property>
    
  • destinationType : The destination type for the MDB (i.e., queue or topic), as follows:

    <activation-config>
        <activation-config-property>
        <activation-config-property-name> 
            DestinationType
        </activation-config-property-name>
        <activation-config-property-value>
            javax.jms.Queue
        </activation-config-property-value>
    </activation-config-property>
    
  • subscriptionDurability : Specifies whether the subscription is Durable or NonDurable when the topic destination is selected.

If we decide to use the simpleMdb using Websphere MQ with a JCA-RA, then the deployment descriptor (ejb-jar.xml ) of the MDB will be as follows:

<messaging-type>javax.jms.MessageListener</messaging-type>
<transaction-type>Container</transaction-type>
<activation-config>
    <activation-config-property>
        <activation-config-property-name>
            DestinationType
        </activation-config-property-name>
        <activation-config-property-value>
            javax.jms.Queue
        </activation-config-property-value>
    </activation-config-property> 
    
    <activation-config-property>
        <activation-config-property-name>
            DestinationName
        </activation-config-property-name>
        <activation-config-property-value>
            java:comp/resource/MQSeries/MQQ
        </activation-config-property-value>
    </activation-config-property> 
    
    <activation-config-property>
        <activation-config-property-name>
            MessageSelector
        </activation-config-property-name>
        <activation-config-property-value>
            RECIPIENT='MDB'
        </activation-config-property-value>
    </activation-config-property> 
    
    <activation-config-property>
        <activation-config-property-name>
            ConnectionFactoryJndiName
        </activation-config-property-name>
        <activation-config-property-value>
            java:comp/resource/MQSeries/MQXAQCF
        </activation-config-property-value>
    </activation-config-property>
</activation-config>

If you look carefully at the deployment descriptor, you will find that the destination type and name on which the MDB will listen has already been specified as activation-config property and eliminates the basic need for the vendor deployment descriptor. However, the activation config properties can be overridden by the deployer in the vendor-specific deployment descriptor.

In the vendor deployment descriptor for the MDB, you have to specify the name of the resource adapter being used. In addition, you can specify additional config properties that were not specified in the ejb-jar.xml file. For example, if you are using OC4J, the vendor-specific deployment descriptor (e.g., orion-ejb-jar.xml) has the following contents:

<message-driven-deployment name="simpleMdb" 
     resource-adapter="mqjms">
    ...
</message-driven-deployment>

Configuring the Application Server

You may have to do some configuration tasks in your application server if you decide to use a third-party JMS provider. For example, if you decide to use Websphere MQ with OC4J, several Websphere-MQ-specific libraries need to be available to OC4J.

Deploy the Resource Adapter

For MDBs to work with a JMS provider via a JCA resource adapter, the resource adapter needs to be deployed in the application server. You can deploy your resource adapter in two ways: standalone or embedded. A standalone or global resource adapter in your application server can be used by any applications deployed in the application server. An embedded resource adapter, packaged within an enterprise application archive (EAR), is available only to the J2EE application with which it is packaged.

The deployment descriptor (ra.xml) and vendor-specific deployment descriptors (e.g., oc4j-ra.xml in OC4J) of the resource adapter for the JMS provider define the properties of the resource provider and the resource. However, the details of these are beyond the scope of this article.

Configure the JMS Provider

You have to create the necessary JMS objects in the JMS provider, such as a queue or topic that will be used by the MDB and other related tasks for your JMS provider.

For example, if you are using Websphere MQ with OC4J, you have to do the following:

  • Configure and start the MQ queue manager.
  • Create the queue bindings for the JMS connection factories and destinations.

A fully functional example of MDBs using JCA RA can be downloaded from the Oracle Technology Network. This example uses an embedded resource adapter and demonstrates the use of MDBs with Websphere MQ as the JMS provider.

Best Practices for MDBs

The following approaches and suggestions should be used during the development and deployment of MDBs:

  • Consider using a session bean method for implementing and calling from onMesage()when business logic is complex.

  • Avoid associating more than one MDB with the same JMS queue, because JMS does not define how messages are distributed between the queue receivers.

  • Specify durability when using a topic with your MDB.

  • If you want your MDB to be transactional, specify the transaction attribute to be Required . Only Required and NotSupported are allowed for container-managed transactions in MDB.

  • Use the MessageSelector to filter out unwanted messages, leading to performance improvement.

  • Specify acknowledgeMode when you use bean-managed transactions for your MDB. If you select Dups-ok-acknowledge, your MDBs must be able to handle duplicate messages correctly.

  • When deciding on which flavor of connection-factories to use for lookup, you should use XA connection factories if your application components need to participate in a global transaction. Otherwise, use non-XA connection factories for better performance.

  • To enable parallel processing of messages, define a value for activation-config-property named receiverThreads under the section where other properties are defined in ejb-jar.xml, e.g.:

    <activation-config-property>
      <activation-config-property-name>receiverThreads</activation-config-property-name>
      <activation-config-property-value>5</activation-config-property-value>
    </activation-config-property>

Conclusion

This article provided a brief discussion on the enhancements made in J2EE 1.4 to provide pluggability of messaging providers and discussed the steps required to use a JMS provider with a resource adapter. This functionality is already available in several J2EE-1.4-compatible application servers such as OC4J 10.0.3 and IBM Websphere 6.0. You can start building your MDB using this feature to make your application easily portable.

References and Further Reading

Debu Panda is a Senior Principal Product Manager of the Oracle Application Server development team.


Return to ONJava.com.