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 should 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 means that the business processing can be invoked
by either the arrival of incoming messages or, for example, by 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 as with 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.
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 Java EE Connector Architecture (JCA)-compliant
resource adapters might provide their own message listener interfaces
that must 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 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 the onMessage() method
might be needed. For information about the message listener interface
needed, see the documentation that was provided with your JCA-compliant
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 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 attributes.
You can use the EJB deployment descriptor editor to review deployment
properties that you specified on the EJB creation wizard (such as Transaction
type and Message selector) and other
default deployment attributes.
If needed, you can override the values
of these properties later, after the enterprise application has been
exported into an EAR file for deployment, as described in Configuring deployment attributes for a message-driven bean against JCA 1.5-compliant resources and Configuring deployment attributes for a message-driven bean against a listener port.
- In the property pane, select the Beans tab.
- Specify general deployment attributes.
- 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 attributes.
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.
Note: The acknowledgement
is sent when the message is deleted.
If you
have a non-transactional message-driven bean, the system either deletes
the message when the bean starts, or when the bean completes. If the
bean generates an exception, and therefore does not complete, the
system takes one of the following actions:
- If the system is configured to delete the message when the bean
completes, then the message is despatched to a new instance of the
bean, so the message has another opportunity to be processed.
- If the system is configured to delete the message when the bean
starts, then the message is lost.
The message
is deleted when the bean starts if the quality of service is set to Best
effort nonpersistent. For all other qualities of service,
the message is deleted when the bean completes.
- 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 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 attributes.
Under WebSphere Bindings, select the JCA
Adapter option then specify the bindings deployment attributes:
- ActivationSpec JNDI name
- 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
- 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 against JCA 1.5-compliant resources.