Use this task to develop an enterprise application to use a message-driven
bean. The message-driven bean is invoked by a J2C activation specification
or a JMS listener when a message arrives on the input destination that the
listener is monitoring.
About this task
You are recommended to develop the message-driven bean to delegate
the business processing of incoming messages to another enterprise bean, to
provide clear separation of message handling and business processing. This
also enables the business processing to be invoked by either the arrival of
incoming messages or, for example, from a WebSphere J2EE client. Responses
can be handled by another enterprise bean acting as a sender bean, or handled
in the message-driven bean.
You develop an enterprise application to
use a message-driven bean like any other enterprise bean, except that a message-driven
bean does not have a home interface or a remote interface.
For more
information about writing the message-driven bean class, see Creating
a message-driven bean in the Rational Application Developer help bookshelf.
To
develop an enterprise application to use a message-driven bean, complete the
following steps:
Procedure
- Create the Enterprise Application project.
- Create the message-driven bean class.
You can use
the New Enterprise Bean wizard of Rational Application Developer to create
an enterprise bean with a bean type of Message-driven bean. The wizard creates
appropriate methods for the type of bean.
By convention, the message
bean class is named
nameBean, where
name is the name you assign
to the message bean; for example:
public class MyJMSppMDBBean implements MessageDrivenBean, javax.jms.MessageListener
All message-driven beans must implement the MessageDrivenBean interface.
For JMS messaging, a message-driven bean must also implement the message listener
interface, javax.jms.MessageListener. Other JCA-compliant Resource Adapters
may provide their own message listener interface that needs to be implemented.
A
message-driven bean can be registered with the EJB timer service for time-based
event notifications if it also implements the javax.ejb.TimedObject interface
and the timer callback method void ejbTimeout(Timer). At the scheduled time,
the container invokes the message-driven bean’s ejbTimeout method.
The
message-driven bean class must define and implement the following methods:
- onMessage(message), which must meet the following requirements:
- The method must have a single argument of type javax.jms.Message.
- The throws clause must not define any application exceptions.
- If the message-driven
bean is configured to use bean-managed transactions, it must call the javax.transaction.UserTransaction
interface to scope the transactions. Because these calls occur inside the
onMessage() method, the transaction scope does not include the initial message
receipt. For more information, see Message-driven beans - transaction support.
To handle the message within the onMessage() method (for example,
to pass the message on to another enterprise bean), you use standard JMS.
(This is known as bean-managed messaging.)
If you are using a JCA-compliant
Resource Adapter with a different message listener interface, another method
besides onMessage() may be needed. For information about the message listener
interface needed, see the documentation that was provided with your JCA Resource
Adapter.
- ejbCreate()
You must define and implement an ejbCreate method for each
way in which you want a new instance of an enterprise bean to be created.
- ejbRemove()
This method is invoked by the container when a client invokes
the remove method inherited by the enterprise bean's home interface from the
javax.ejb.EJBHome interface. This method must contain any code that you want
to execute before an enterprise bean instance is removed from the container
(and the associated data is removed from the data source).
- ejbTimeout(Timer)
This method is needed only to support notifications
from the timer service, and contains the business logic that handles time
events received.
For example, the following code extract shows how to access the
text and the JMS MessageID, from a JMS message of type TextMessage:
Figure 1. Code example: The onMessage() method of a message bean.
This
figure shows a code extract for a basic onMessage() method of a sample message-driven
bean. The method unpacks the incoming text message to extract the text and
message identifier and calls a private putMessage method (defined within the
same message bean class) to put the message onto another queue.
public void onMessage(javax.jms.Message msg)
{
String text = null;
String messageID = null;
try
{
text = ((TextMessage)msg).getText();
System.out.println("senderBean.onMessage(), msg text2: "+text);
//
// store the message id to use as the Correlator value
//
messageID = msg.getJMSMessageID();
// Call a private method to put the message onto another queue
putMessage(messageID, text);
}
catch (Exception err)
{
err.printStackTrace();
}
return;
}
The result of this step is a message-driven bean
that can be assembled into an EAR file for deployment.
- Optional: Use the EJB deployment descriptor editor
to review and, if needed, change the deployment properties. You
can use the EJB deployment descriptor editor to review deployment properties
that you specified on the EJB Creation Wizard (like Transaction type and Message
selector) and other default deployment properties.
If needed, you can override
the values of these properties later, after the enterprise application has
been exported into an EAR file for deployment.
- In the property pane, select the Beans tab.
- Specify general deployment properties.
- Transaction type
- Whether the
message bean manages its own transactions or the container manages transactions
on behalf of the bean.
- Bean
- The message bean manages its own transactions
- Container
- The container manages transactions on behalf of the bean
- Specify advanced deployment properties.
Under
Activation Configuration, review the following properties:
- Acknowledge mode
- How the session acknowledges any messages it receives.
This property
applies only to message-driven beans that uses bean-managed transaction demarcation
(Transaction type is set to Bean).
- Auto Acknowledge
- The session automatically acknowledges a message when it has either successfully
returned from a call to receive, or the message listener it has called to
process the message successfully returns.
- Dups OK Acknowledge
- The session lazily acknowledges the delivery of messages. This is likely
to result in the delivery of some duplicate messages if JMS fails, so it should
be used only by consumers that are tolerant of duplicate messages.
As defined in the EJB specification, clients cannot use
using Message.acknowledge() to acknowledge messages. If a value of CLIENT_ACKNOWLEDGE
is passed on the createxxxSession call, then messages are automatically
acknowledged by the application server and Message.acknowledge() is not used.
- Destination type
- Whether the message bean uses a queue or topic destination.
- Queue
- The message bean uses a queue destination.
- Topic
- The message bean uses a topic destination.
- Durability
- Whether a JMS topic subscription is durable or non-durable.
- Durable
- A subscriber registers a durable subscription with a unique identity that
is retained by JMS. Subsequent subscriber objects with the same identity resume
the subscription in the state it was left in by the earlier subscriber. If
there is no active subscriber for a durable subscription, JMS retains the
subscription's messages until they are received by the subscription or until
they expire.
- Nondurable
- Non-durable subscriptions last for the lifetime of their subscriber object.
This means that a client sees the messages published on a topic only while
its subscriber is active. If the subscriber is not active, the client is missing
messages published on its topic.
A non-durable subscriber can only be used
in the same transactional context (for example, a global transaction or an
unspecified transaction context) that existed when the subscriber was created.
For more information about this context restriction, see The effect of transaction context on non-durable subscribers.
- Message selector
- The JMS message selector to be used to determine which messages the message
bean receives; for example:
JMSType='car' AND color='blue' AND weight>2500
The
selector string can refer to fields in the JMS message header and fields in
the message properties. Message selectors cannot reference message body values.
For more details about these properties, see Message-driven bean deployment descriptor properties.
- Specify bindings deployment properties.
Under
WebSphere Bindings, select the JCA Adapter option then specify the bindings
deployment properties:
- ActivationSpec JNDI name
- Type the JNDI name of the J2C activation specification that is to be used
to deploy this message-driven bean. This name must match the name of a J2C
activation specification that you define to WebSphere Application Server.
- ActivationSpec Authorization Alias
- The name of a J2C authentication alias used for authentication of connections
to the JCA resource adapter. A J2C authentication alias specifies the user
ID and password that is used to authenticate the creation of a new connection
to the JCA resource adapter.
- Destination JNDI name
- Type the JNDI name that the message-driven bean uses to look up the JMS
destination in the JNDI namespace.
- Assemble and package
the application for deployment.
Results
The result of this task is an EAR file, containing the message-driven
bean, for the enterprise application that can be deployed in WebSphere Application
Server.
What to do next
After you have developed an enterprise application to use message-driven
beans, configure and deploy the application; for example, define J2C activation
specifications for the message-driven beans and, optionally, change the deployment
descriptor attributes for the application. For more information about configuring
and deploying an application that uses message-driven beans, see
Deploying an enterprise application to use
message-driven beans