Develop an enterprise application to use message-driven beans

 

+

Search Tips   |   Advanced Search

 

Use this task to develop an enterprise application to use a message-driven bean (MDB).

When a message arrives, MDBs are invoked using either...

• J2C activation spec
• JMS listener

Develop the MDB to delegate business processing of messages to another enterprise bean, to...

• Separate message handling and business processing

• Enable 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 MDB.

You develop an enterprise application to use a MDB like any other enterprise bean, except that a MDB does not have a home interface or a remote interface.

To develop an enterprise application to use a MDB...

1. Create the Enterprise Application project.

2. Create the MDB class.

   You can use the New Enterprise Bean wizard to create appropriate methods for your 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 MDBs must implement the MessageDrivenBean interface. For JMS messaging, a MDBs 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 MDB 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 MDB ejbTimeout method. The MDB 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 MDB 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.

       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 we 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 the 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's home interface from the javax.ejb.EJBHome interface. This method must contain any code 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 MDB. 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 MDB that can be assembled into an EAR file for deployment.

3. Use the EJB deployment descriptor editor to review and, if needed, change the deployment properties.

   Use the EJB deployment descriptor editor to review deployment properties specified on the EJB creation wizard (like Transaction type and Message selector) and other default deployment properties.

   If needed, we can override the values of these properties later, after the enterprise application has been exported into an EAR file for deployment.

   1. In the property pane, select the Beans tab.

   2. 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

   3. 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 MDBs 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 appserver and Message.acknowledge() is not used.

      The acknowledgement is sent when the message is deleted. If we have a non-transactional MDB, 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'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.

      See 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.

   4. 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 spec that is to be used to deploy this MDB. This name must match the name of a J2C activation spec that you define to WAS.

      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 used to authenticate the creation of a new connection to the JCA resource adapter.

      Destination JNDI name

      Type the JNDI name that the MDB uses to look up the JMS destination in the JNDI namespace.

4. 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 WAS.

 

Next steps

After we have developed an enterprise application to use MDBs, configure and deploy the application; for example, define J2C activation specifications for the MDBs and, optionally, change the deployment descriptor attributes for the application.

See: Configure and deploy an application that uses message-driven beans

 

Related tasks

Message-driven bean deployment descriptor properties
Designing an enterprise application to use message-driven beans
Deploy an enterprise application to use MDBs against JCA 1.5-compliant resources
Deploy an enterprise application to use EJB 2.0 MDBs with listener ports
Programming to use MDBs