5 Programming and Configuring MDBs: Main Steps

Examine the step-by-step instructions for implementing an MDB using pre-EJB 3.0 style XML descriptors to configure its behavior.

For a summary of key deployment elements for MDBs, see Deployment Elements and Annotations for MDBs. For an introduction to key deployment elements for topic MDBs, see Configuring and Deploying MDBs Using JMS Topics.

This chapter includes the following sections:

• Required JMS Configuration

• Create MDB Class and Configure Deployment Elements

Required JMS Configuration

Examine the steps to configure JMS connection factory and JMS destination.

The steps in the following section assume that you have access to the appropriate JMS components:

• A JMS connection factory.

  A connection factory must be XA transaction (global JTA transaction) capable in order to support transactional MDBs.

  The default WebLogic JMS MDB connection factory is XA-capable, is automatically generated on WebLogic clusters, and is sufficient for the majority of MDBs that consume from WebLogic JMS destinations. For information about WebLogic JMS default connection factories, see Using a Default Connection Factories Defined by WebLogic Server in Administering JMS Resources for Oracle WebLogic Server.

  For instructions about how to create a custom WebLogic JMS connection factory, see Create connection factories in a system module in Oracle WebLogic Server Administration Console Online Help.

  The default behavior and configuration methods for other JMS provider connection factories vary. If you use a non-Oracle JMS provider, see the vendor documentation for details.

• A JMS destination

  For instructions on configuring WebLogic JMS destinations, see Configure Messaging in Oracle WebLogic Server Administration Console Online Help.

  Note:

  If your JMS provider is a remote Oracle WebLogic Server JMS provider or a foreign JMS provider, and you use the wrapper approach recommended in Whether to Use Foreign JMS Server Mappings, in addition to configuring the non-local JMS components, you must also configure a Foreign Connection Factory and Foreign JMS Destination in your local JNDI tree.

Create MDB Class and Configure Deployment Elements

Examine the steps to implement a message-driven bean in an Oracle WebLogic Server.

Use the following steps to implement a message-driven bean:

1. Create a source file (message-driven bean class) that implements both the javax.ejb.MessageDrivenBean and javax.jms.MessageListener interfaces.

   The MDB class must define the following methods:

   • One ejbCreate() method that the container invokes after creating each new instance of the MDB.

   • One onMessage() method that is called by the EJB container when a message is received. This method contains the business logic that processes the message.

   • One setMessageDrivenContext{} method that provides information to the bean instance about its environment (certain deployment descriptor values); the MDB also uses the context to access container services. See Using the Message-Driven Bean Context,.

   • One ejbRemove() method that removes the message-driven bean instance from the free pool.

   Note:

   Most EJB 3.2 applications implement only javax.jms.MessageListener, which defines a single method - onMessage(). However, a message-driven bean is permitted to implement a listener interface with no methods. A bean that implements a no-methods interface, exposes all non-static public methods of the bean class and of any superclasses except java.lang.Object as message listener methods.

2. Declare the MDB in ejb-jar.xml, as illustrated in the following excerpt:

   <ejb-jar>
       <enterprise-beans>
           <message-driven>
               <ejb-name>...</ejb-name>
               <ejb-class>...</ejb-class>
               <transaction-type>Container</transaction-type>
               <acknowledge-mode>auto_acknowledge</acknowledge-mode>
               <message-driven-destination>
                   <destination-type>javax.jms.Topic</destination-type>
                   <subscription-durability>Durable</subscription-durability>
               </message-driven-destination>
           </message-driven>
       </enterprise-beans>
       <assembly-descriptor>
           <container-transaction>
               <method>
                   <ejb-name>...</ejb-name>
                   <method-name>onMessage()</method-name>
               </method>
               <trans-attribute>Required</trans-attribute>
           </container-transaction>
       </assembly-descriptor>
   </ejb-jar>
   

   The key behaviors to configure are:

   • Transaction management strategy—The MDB's transaction management strategy, in the transaction-type element. For instructions, see Configuring Transaction Management Strategy for an MDB.

   • Destination type—The type of destination to which the MDB listens. For more information, see Configuring Destination Type.

3. Configure WebLogic-specific behaviors for the MDB in the message-driven-descriptor element of weblogic-ejb-jar.xml. For example:

   <weblogic-ejb-jar>
       <weblogic-enterprise-bean>
           <ejb-name>exampleMessageDrivenA</ejb-name>
           <message-driven-descriptor>
               <pool>...</pool>
               <timer-descriptor>...</timer-descriptor>
               <destination-jndi-name>...</destination-jndi-name>
               <initial-context-factory>...</initial-context-factory>
               <provider-url>...</provider-url>
               <connection-factory-jndi-name>...</connection-factory-jndi-name>
               <jms-polling-interval-seconds>...</jms-polling-interval-seconds>
               <jms-client-id>...</jms-client-id>
               <generate-unique-jms-client-id>...</generate-unique-jms-client-id>
               <durable-subscription-deletion>...</durable-subscription-deletion>
               <max-messages-in-transaction>...</max-messages-in-transaction>
               <init-suspend-seconds>...</init-suspend-seconds>
               <max-suspend-seconds>...</max-suspend-seconds>
           </message-driven-descriptor>
       </weblogic-enterprise-bean>
   </weblogic-ejb-jar>
   

   The key elements to configure are those that specify how to access the destination. In general, applications that follow best practices should never need to specify the initial-context-factory or provider-url fields. For instructions, see Configuring MDBs for Destinations.

4. Compile and generate the MDB class using the instructions in Compile Java Source in Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server.
5. Deploy the bean on Oracle WebLogic Server using the instructions in the section Preparing Applications and Modules for Deployment in Deploying Applications to Oracle WebLogic Server

   If Oracle WebLogic Server cannot find an MDB's JMS destination during deployment, deployment succeeds, but Oracle WebLogic Server prints a message saying the destination was not found. The MDB bean then periodically tries to connect to its JMS queue until it succeeds. For more information, see Migration and Recovery for Clustered MDBs.