Message-Driven Beans (MDBs)



Search Tips   |   Advanced Search



  1. Overview
  2. Transactions
  3. Extended messaging
  4. Troubleshooting
  5. Security
  6. Examples


WAS supports asynchronous messaging using MDBs, which are used to delegate incoming messages to enterprise beans.

The message listener service uses MDBs, with one MDB roughly equivalent to one listener port session, where each session represents a connection to a queue destination or a topic destination.

For example, for each message arriving on an MQ queue, the listener port session passes the message to a new instance of a user-developed MDB for processing. The listener gets the next message without waiting for the MDB to return.

A connection factory is used to create connections with the JMS provider for a specific queue or topic destination.

If you are using the WebSphere MQ JMS, any messages posted to MQ queues are automatically read in by the listeners, with no polling required by the application or container.

Messages arriving at a destination being processed by a listener have no client credentials associated with them; the messages are anonymous. Security depends on the role specified by the RunAs Identity for the MDB.

Each listener completes several steps for the JMS destination that it is to monitor, including...


Transaction support

If transaction handling is specified for a JMS destination, the listener starts a global transaction before it reads any incoming message from that destination. When the MDB processing has finished, the JMS listener commits or rolls back the transaction. See JTA transaction control for more information.

If the processing of a message causes the transaction to be rolled back, then the message that caused the bean instance to be invoked is left on the JMS destination. Configure Maximum retries and backout queues to prevent the listener port from stopping due to bad messages.


Configure the message listener service to use MDBs

To configure resources needed by the message listener service to support MDBs...

  1. Configure the message listener service
  2. Add a new listener port
  3. Configure a listener port
  4. For each MDB, configure deployment attributes to match the listener port definitions
  5. Configure security for MDBs
  6. Install the app.


Deploy an enterprise application to use MDBs

To deploy an enterprise application to use MDBs, complete the following steps...

  1. Add a new listener port.

  2. For each MDB in the application, configure the deployment attributes to match the listener port definitions

  3. Install the application.


Important files for MDBs and extended messaging

The following files in the WAS_HOME/temp directory are important for the operation of the WAS messaging service, so should not be deleted. If you do need to delete the WAS_HOME/temp directory or other files in it, ensure that you preserve the following files.

server-durableSubscriptions.ser If you uninstall an application that contains a MDB, this file is used to unsubscribe the durable subscription.

server-AsyncMessageRequestLog.ser Used to keep track of late responses that need to be delivered to the late response message handler for the extended messaging provider.



  1. Check for messages about MDBs in...


  2. Check that listener ports are turned on.

  3. Check for problems with the WebSphere Messaging functions.

  4. Enable Diagnostic trace for the "Messaging" group.

  5. Configure applications to generate MQ JMS Linked Exceptions

    We need to get the underlying MQ return code that caused the MQJMS exception to be thrown. This is called the "linked exception." For example, if the comp code is 2, reason code 2059, then we know that the JMS exception was thrown as a result of the "Queue manager unavailable" reason code.

    In order to have this output produced in the stack trace, implement the following code in JMS application.

      catch (JMSException jmse)                                             
          Exception le = jmse.getLinkedException();                         
          if (le != null) le.printStackTrace();                             

  6. Check the Release Notes

  7. Configure MQ JMS Trace

    To configure MQ JMS Trace go to...

    Servers | Application Servers | Server_Name | Process Definition | Java Virtual Machine | Custom Properties

    ...and set...

    java -DMQJMS_TRACE_LEVEL=base myJMSApp

    If the JMS application is started as servlet the above will not work. In this case you can invoke trace from within the source code. For example...; level);      ;                       
    java.util.Properties.props = System.getProperties();                     
    props.put("MQJMS_TRACE_DIR", "path/to/trace/directory";                       

    The filename is fixed to mqjms.trc - only the directory can be modified in this manner.

  8. Configure MQ trace

    1. ps -ef > pid1.out
    2. ipcs -a > ipcs1.out
    3. strmqtrc -t all -t detail -m QmgrName
    4. Recreate the error
    5. ipcs -a > ipcs2.out
    6. endmqtrc -a
    7. ps -ef > pid2.out

    Trace files are written to...


    To read, the trace files need to be formatted...

    dspmqtrc filename


Configure security for MDBs

Messages arriving at a listener port have no client credentials associated with them. The messages are anonymous. To call secure enterprise beans from an MDB, configure the RunAs Identity.

JMS connections used by MDBs can benefit from the added security of using J2C container-managed authentication defined on the connection factory definition. To set...

  1. Display the listener port settings...

    Servers | application_server | Message Listener Service | Listener Ports | listener_port

  2. Get the name of the connection factory by looking at the Connection factory JNDI name property.

  3. Display the JMS connection factory properties....

    Resources | WebSphere MQ JMS Provider | WebSphere Queue Connection Factories | connection_factory

  4. Set the Container-managed Authentication Alias property.

  5. Click OK