Using a JMS Provider with MDBs via the J2EE Connector Architecture
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. 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
- EJB 2.1 specification
- J2EE Connector Architecture (JCA) 1.5 specification
- Applying Enterprise Java Beans, Second Edition by Vlada Matena, Sanjeev Krishnan, Linda DeMichiel, and Beth Stearns, published by Addison-Wesley.
Debu Panda
is a Senior Principal Product Manager of the Oracle Application Server development team.
Return to ONJava.com.