Skip Headers
Oracle® Fusion Middleware Programming Message-Driven Beans for Oracle WebLogic Server
12c Release 1 (12.1.1)

Part Number E24977-02
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

6 Programming and Configuring MDBs: Details

The topics in this section supplement the instructions in Programming and Configuring MDBs: Main Steps.

Note:

This chapter uses a pre-EJB 3.0 deployment descriptor to illustrate basic MDB configuration. If you plan to use EJB 3.1 annotations, see also Chapter 11, "Deployment Elements and Annotations for MDBs." and Chapter 7, "Using EJB 3.1 Compliant MDBs," for the equivalent settings.

Configuring Destination Type

Configure the type of destination to which the MDB listens in the destination-type element in the message-driven-destination element of ejb-jar.xml or by using an annotation.

Configuring Transaction Management Strategy for an MDB

An MDB can manage its own transactions or defer transaction management to the container.

To configure container-level transaction management using descriptor elements:

To configure container-level transaction management using EJB annotations:

import javax.ejb.TransactionAttribute;
  import javax.ejb.TransactionAttributeType;
  ...
  @TransactionAttribute(value = TransactionAttributeType.REQUIRED)
  public void onMessage(Message msg) {
  ...

To configure bean-level transaction management using descriptor elements:

For more information, see "Session" in Programming JMS for Oracle WebLogic Server.

Configuring MDBs for Destinations

WebLogic Server MDBs support WebLogic JMS destinations and foreign (non-Oracle) JMS provider destinations.

A local destination is one that runs on the same machine or in the same cluster as the MDB. A remote destination is one that runs on a different machine and is not a member of the same cluster as the MDB. Whether a destination is local or remote depends on whether or not it and the MDB share the same JNDI context.

To be considered local to one another, an MDB and the associated JMS destination must both run either on the same machine or within the same WebLogic Server cluster. An MDB and a JMS destination on server instances in the same WebLogic Server cluster are local to one another even if they are on separate machines, because the server instances in a WebLogic Server cluster each have a copy of the same cluster-wide JNDI tree.

Destinations that run under a non-Oracle JMS provider are referred to as foreign. Foreign JMS providers have their own JNDI provider and foreign JMS objects do not share the same context with a WebLogic Server MDB—unless the foreign JMS objects are configured with mappings to appear in the MDB's JNDI context. This approach is discussed in Whether to Use Foreign JMS Server Mappings.

The nature of a destination—local versus remote and WebLogic JMS versus non-Oracle—governs the configuration alternatives available, and dictates to some extent how you configure these key elements in the message-destination-descriptor for the MDB in weblogic-ejb-jar.xml:

For foreign and remote destinations, the simplest configuration strategy is to use WebLogic Server foreign JMS server mappings. These mappings allow you to create a "symbolic link" between a JMS object in a third-party JNDI provider or in a different WebLogic Server cluster or domain, and an object in the local WebLogic JNDI tree.

For more information on when foreign JMS server mappings are appropriate, and the rules for configuring the message-driven-descriptor in weblogic-ejb-jar.xml, see these sections:

To configure the elements in message-driven-descriptor for specific scenarios, see Common Destination Scenarios: Illustrations and Key Element Settings.

Whether to Use Foreign JMS Server Mappings

Using mappings means configuring a Foreign Connection Factory and a Foreign Destination that correspond to remote JMS objects (either non-Oracle or WebLogic JMS) as entries in your local JNDI tree.

  • The use of mappings is recommended if you use a foreign JMS provider or a remote WebLogic JMS provider. For more information on JMS mapping classes, see "Simplified Access to Remote or Foreign JMS Providers" in "Enhanced Support for Using WebLogic JMS with EJBs and Servlets" in Programming JMS for Oracle WebLogic Server.

  • If you use a mapping for either the connection factory or the destination, you must create and use mappings for each of these objects.

Whether or not you use mappings determines how you configure the initial-context-factory and destination-jndi-name, as described below.

How to Set provider-url

provider-url specifies the URL of the JNDI service used by the JMS provider for the destination to which the MDB listens.

  • If the JMS provider is local to the MDB (by definition, WebLogic JMS), do not specify provider-url.

  • If the JMS provider is remote, whether WebLogic JMS or a foreign provider, and:

    • You do not use mappings, specify provider-url.

    • You do use mappings, do not specify provider-url. The URL is implicitly encoded in the mapping.

How to Set initial-context-factory

initial-context-factory identifies the class that implements the initial context factory used by the JMS provider.

  • If your JMS provider is WebLogic JMS, whether local or remote, do not specify initial-context-factory.

  • If your JMS provider is foreign, and

    • you do not use mappings, specify the initial context factory used by the JMS provider.

    • you do use mappings, do not specify initial-context-factory.

How to Set destination-jndi-name

destination-jndi-name identifies the JNDI name of destination to which the MDB listens.

  • If your JMS provider is local, specify the name bound in the local JNDI tree for the destination.

  • If your JMS provider is foreign and:

    • You do not use mappings, specify the name of the destination, as bound in the foreign provider's JNDI tree.

    • You do use mappings, specify the name Foreign Destination you set up in your local JNDI tree that corresponds the remote or foreign destination.

How to Set connection-factory-jndi-name

connection-factory-jndi-name identifies the JNDI name of the connection factory used by the JMS provider.

  • If your JMS provider is local, do not specify connection-factory-jndi-name unless you have configured a custom connection factory that the MDB will use.

    Custom connection factories are used when the default WebLogic Server connection factory does not satisfy your application requirements. For example, you might configure a custom connection factory in order to specify a particular desired value for the MessagesMaximum attribute. The procedure for configuring a connection factory is described in "Configure connection factories" in Oracle WebLogic Server Administration Console Help.

    Note:

    If you configure a custom JMS connection factory for an MDB, be sure to set the Acknowledge Policy attribute to Previous, and that the UserTransactionsEnabled attribute is enabled.

  • If your JMS provider is remote or foreign, and:

    • You do not use mappings, specify the name of the connection factory used by the JMS provider, as bound in the remote JNDI tree.

    • You do use mappings, specify the Foreign Connection Factory you set up in your local JNDI tree that corresponds to the remote or foreign JMS provider's connection factory.

Common Destination Scenarios: Illustrations and Key Element Settings

The figures in this section illustrate common destination configurations. For remote and foreign destinations, scenarios with and without mappings are included.

Table 6-1 summarizes how to configure the elements in the message-driven-descriptor element of weblogic-ejb-jar.xml for each scenario.

Figure 6-1 A. Destination on a Local WebLogic JMS Server

Description of Figure 6-1 follows
Description of "Figure 6-1 A. Destination on a Local WebLogic JMS Server"

Figure 6-2 B. Destination On a Remote WebLogic JMS Server—No Mappings

Description of Figure 6-2 follows
Description of "Figure 6-2 B. Destination On a Remote WebLogic JMS Server—No Mappings"

Figure 6-3 C. Destination on Foreign JMS Server—No Mappings

Description of Figure 6-3 follows
Description of "Figure 6-3 C. Destination on Foreign JMS Server—No Mappings"

Figure 6-4 D. Destination on a Remote WebLogic Server or Foreign JMS Server—With Mappings

Description of Figure 6-4 follows
Description of "Figure 6-4 D. Destination on a Remote WebLogic Server or Foreign JMS Server—With Mappings"

Table 6-1 Common Configuration Scenarios

Scenario If destination is on... Mappings Configured? destination-jndi-name initial-context-factory provider-url connection-factory-jndi-name

A

Local WebLogic JMS server

Not applicable for local WebLogic JMS server

Name of the local destination, as bound in local JNDI tree

Do not specify

Do not specify

Specify only if using a custom connection factory

B

Remote WebLogic JMS Server

No mappings configured

Name of the remote destination, as bound in the remote JNDI tree

Do not specify

URL or cluster address for the remote WebLogic JMS Server

Specify only if using a custom connection factory on the remote provider

C

Foreign JMS Provider

No mappings configured

Name of the remote destination, as bound in the remote JNDI tree

Name of remote initial context factory, as bound in remote JNDI tree

URL to access the foreign JMS provider

JNDI name of foreign connection factory

D

Remote Weblogic JMS Server

or

Foreign JMS server

Mappings configured

The name of the Foreign Destination—as bound in your local JNDI tree —that maps to the remote or foreign destination

Do not specify

Do not specify

The name of the Foreign Connection Factory—as bound in your local JNDI tree —that maps to the remote or foreign connection factory


Configuring Message Handling Behaviors

These topics provide guidelines for behaviors related to message delivery:

Ensuring Message Receipt Order

Make sure that the MDB's business logic allows for asynchronous message processing. Do not assume that MDBs receive messages in the order the client issues them.

When using WebLogic JMS destinations, Oracle recommends using the Unit-of-Order feature if strict ordering is required. This feature enforces ordering under all circumstances without requiring modification of the MDB, enables concurrent processing of sub-orderings that exist within the same destinations, and can be enabled via configuration or programmatically as appropriate. See "Using Message Unit-of-Order" in Programming JMS for Oracle WebLogic Server.

If you are not using WebLogic destinations with unit-of-order to ensure that receipt order matches the order in which the client sent the message, you must do the following:

  • Set max-beans-in-free-pool to 1 for the MDB. This ensures that the MDB is the sole consumer of the message.

  • If your MDBs are deployed on a cluster, deploy them to a single node in the cluster, as illustrated in Figure 6-5.

To ensure message ordering in the event of transaction rollback and recovery, configure a custom connection factory with MessagesMaximum set to 1, and ensure that no redelivery delay is configured. Foreign vendors have different names for the equivalent setting. This setting controls the number of messages that a vendor may push to a consumer before the consumer completes processing of its current message.

For more information see "Ordered Redelivery of Messages" in Programming JMS for Oracle WebLogic Server.

See the Java documentation on the Interface MessageListenerjavax.jms.MessageListener.onMessage()—for more information, at http://download.oracle.com/javaee/1.2.1/api/javax/jms/MessageListener.html.

Preventing and Handling Duplicate Messages

A JMS vendor expects an MDB to acknowledge received messages. If the MDB receives the message, but fails to send an acknowledgement, the JMS vendor re-sends the same message.

Your MDB design should allow for the likelihood of duplicate messages. Duplicate messages can be undesirable in certain cases. For example, if an MDB's onMessage() method includes code to debit a bank account, receiving and processing that message twice would result in the account being debited twice. In addition, re-sending messages consumes more processing resources.

The best way to prevent delivery of duplicate messages is to use container-managed transactions. In a container-managed transaction, message receipt and acknowledgement occur within the transaction; either both happen or neither happens. However, while this provides more reliability than using bean-managed transactions, performance can be compromised because container-managed transactions use more CPU and disk resources.

If the MDB manages its own transactions, your onMessage() code must handle duplicate messages, as receipt and acknowledgement occur outside of a transaction. In some applications, receipt and processing of duplicate messages is acceptable. In other cases, such as the bank account scenario described above, if a transaction is bean-managed, the bean code must prevent processing of duplicate messages. For example, the MDB could track messages that have been consumed in a database.

Even if an MDB's onMessage() method completes successfully, the MDB can still receive duplicate messages if the server crashes between the time onMessage() completes and the time the container acknowledges message delivery. Figure 6-5 illustrates this scenario.

Figure 6-5 Server Crash Between Completion of onMessage() and Container Delivery Acknowledgement

Description of Figure 6-5 follows
Description of "Figure 6-5 Server Crash Between Completion of onMessage() and Container Delivery Acknowledgement"

Redelivery and Exception Handling

If an MDB is consuming a message when an unexpected error occurs, the MDB can throw a system exception that causes JMS to resend, delay, and then resend or give up, depending on how JMS is configured.

To force message redelivery for a transactional MDB, use the bean context to call setRollbackOnly().

To force message redelivery for any MDB—transactional or non-transactional—you can throw an exception derived from the RuntimeException or Error thrown by the MDB. This causes the MDB instance to be destroyed and recreated, which incurs a performance penalty. If you want to avoid the overhead of a destroy and recreate, while still throwing a runtime exception, you can use a WebLogic extension. Throw an instance of a weblogic.ejb.NonDestructiveRuntimeException, for example,

throw new weblogic.ejb.NonDestructiveRuntimeException("force redelivery");

You may want to configure a redelivery delay based on what type of task the MDB's onMessage() method is performing. In some cases, redelivery should be instantaneous, for example, in an application that posts breaking news to a newswire service. In other cases, for example, if the MDB throws an exception because the database is down, redelivery should not occur immediately, but after the database is back up.

Note:

For fully ordered MDBs that do not use the Unit-of-Order feature, do not set a redelivery delay.

For instructions on configuring a redelivery delay, and other JMS exception handling features that can be used with MDB see "Managing Rolled Back, Recovered, Redelivered, or Expired Messages" in Programming JMS for Oracle WebLogic Server.

Using the Message-Driven Bean Context

WebLogic Server calls setMessageDrivenContext() to associate the MDB instance with a container context. Alternatively, EJB 3.1 MDB applications can specify an annotation that injects the MDB context. This is not a client context; the client context is not passed along with the JMS message.

To access the container context's properties from within the MDB instance, use the following methods from the MessageDrivenContext interface:

Configuring Suspension of Message Delivery During JMS Resource Outages

In this release of WebLogic Server, you can configure how an MDB behaves when the EJB container detects a JMS resource outage (an MDB throwing the same exception ten times in succession).

You can configure:

When a JMS connection is suspended, message delivery is suspended for all JMS sessions associated with the connection. By default, when it detects a JMS resource outage, the EJB container suspends an MDB's JMS connection for init-suspend-seconds.

Manually Suspending and Resuming Message Delivery

Administrators can use the Administration Console to manually suspend and resume message delivery to deployed MDBs. For information see "Suspend and resume MDB JMS connections" in Oracle WebLogic Server Administration Console Help.

Configuring the Number of Seconds to Suspend a JMS Connection

You may want to suspend a JMS connection during a resource outage, which can be defined as an MDB throwing the same exception 10 times in succession.

To suspend an MDB's JMS connection, configure the following elements in the weblogic-ejb-jar.xm file:

How the EJB Container Determines How Long to Suspend a JMS Connection

The EJB container uses the following algorithm, based on the init-suspend-seconds and max-suspend-seconds, to determine the amount of time a JMS connection is suspended.

When the EJB container detects a JMS resource outage:

  1. The MDB's JMS connection is suspended for the amount of time specified by init-suspend-seconds.

  2. The connection is checked. If the resource is available, go to Step 12.

  3. If the value of init-suspend-seconds is greater than or equal to max-suspend-seconds, go to Step 9.

  4. The amount of time used to suspend the JMS connection, represented by Xseconds, is calculated by multiplying the time of the previous suspension by 2.

  5. The MDB's JMS connection is suspended for the amount of time specified by Xseconds.

  6. The connection is checked. If the resource is available, go to Step 12.

  7. If the value of init-suspend-seconds is greater than or equal to max-suspend-seconds, go to Step 9

  8. Go to Step 4.

  9. The MDB's JMS connection is suspended for the amount of time specified by max-suspend-seconds.

  10. Check the connection. If the resource is available, go to Step 12.

  11. Go to Step 9.

  12. Continue processing.

Turning Off Suspension of a JMS Connection

If you do not want an MDB's JMS connection to be suspended when the EJB container detects a resource outage, set the value of max-suspend-seconds to 0. When the value of max-suspend-seconds is 0, the value of init-suspend-seconds is ignored.

Configuring a Security Identity for a Message-Driven Bean

When a message-driven bean (MDB) receives messages from a JMS queue or topic, the EJB container uses a Credential Mapping provider and a credential map to obtain the security identity—username and password—to use when establishing the JMS connection and to execute the onMessage() method. This credential mapping occurs only once, when the MDB is started.

Once the EJB container is connected, the JMS provider uses the established security identity to retrieve all messages.

To configure a security identity for an MDB:

  1. Create a WebLogic user for the MDB. See "Users, Groups, and Security Roles" in Securing Resources Using Roles and Policies for Oracle WebLogic Server. Assign the user the username and password that the non-Oracle JMS provider requires to establish a JMS connection.

  2. In the ejb-jar.xml deployment descriptor, define a run-as identity for the MDB:

    <security-identity> 
        <run-as> 
            <role-name>admin</role-name> 
        </run-as>
    </security-identity> 
    
  3. To create the security-identity, you must also define the security-role inside the assembly-descriptor element in ejb-jar.xml, as shown below.

    <assembly-descriptor>
        <security-role>
            <role-name>jmsrole</role-name>
        </security-role>
        ....
    </assembly-descriptor>
    
  4. In the weblogic-ejb-jar.xml deployment descriptor, map the run-as identity to the user defined in Step 2, as shown below:

    <security-role-assignment>
        <role-name>admin</role-name> 
        <principal-name>username</principal-name> 
    </security-role-assignment> 
    

    where username is the username for the user created in step 1.

  5. If the JMS provider is not WebLogic JMS, configure the credential mapper as described in "Create EJB component credential mappings" in Oracle WebLogic Server Administration Console Help.

    Note:

    If the JMS provider is WebLogic JMS, it is not necessary to configure a credential mapper.

Using MDBs With Cross Domain Security

MDBs may require you to configure Cross Domain Security. You should consider the following guidelines when implementing MDBs:

Configuring EJBs to Use Logical Message Destinations

Note:

Logical destinations and application-scoped destinations are not commonly used and are for advanced users only. For most users, Oracle recommends using the methods discussed in Configuring MDBs for Destinations.

Declare logical message destinations in an EJB's deployment descriptor and map the logical message destinations to actual message destinations (JMS queues or topics, or MDBs). Once you declare logical message destinations, you can then create message destination references that are linked to the logical message destinations. EJBs use the logical message destination name to perform a JNDI lookup and access the actual message destination. Logical JMS message destinations can be defined for individual MDBs or entire applications.

For information on how unresolved and unavailable message destinations are handled, see "EJBs and Message Destination References" in Programming Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server.

Configuring Logical JMS Message Destinations for Individual MDBs

You can configure logical JMS message destinations for individual MDBs.

To configure an MDB to use a logical message destination to link to an actual message destination:

  1. Declare the message destination in the message-destination-descriptor element in weblogic-ejb-jar.xml.

  2. Declare message destination references in the following elements in ejb-jar.xml:

    • message-destination-ref

    • message-destination-ref-name—the environment name used in the enterprise bean code for the message destination, relative to java:comp/env. For example, <message-destination-ref>jms/StockQueue</message-destination-ref>.

    • message-destination-type—the expected type of the referenced destination. For example, <message-destination-type>javax.jms.Queue</message-destination-type>.

    • message-destination-usage—specifies whether messages are consumed from the destination, produced for the destination, or both. For example, <message-destination-usage>Produces<message-destination-usage>.

    • message-destination-link—links the message destination reference to the actual message destination. This value must match the destination defined in message-destination-name in the weblogic-ejb-jar.xml file.

Configuring Application-Scoped Logical JMS Message Destinations

In this release of WebLogic Server, you can configure resources for applications. Resources that are configured for entire applications are called application-scoped resources. This section describes application-scoped logical JMS destinations for an EJB application. For additional information on application-scoped resources, such as JMS and JDBC, see Programming JMS for Oracle WebLogic Server and Programming JDBC for Oracle WebLogic Server.

Application-scoped resources, such as logical JMS message destinations, for EJBs apply to all MDBs in the application. You can override application-scoped JMS for specific MDBs by configuring the MDBs to use logical message destinations to link to actual message destinations, as described in Configuring Logical JMS Message Destinations for Individual MDBs.

To configure application-scoped JMS for EJBs:

  1. Declare the message destination in the message-destination-descriptor element in weblogic-ejb-jar.xml.

  2. Declare message destination references in the following elements in ejb-jar.xml:

  • message-driven

    • message-destination-type—the expected type of the referenced destination. For example, <message-destination-type>javax.jms.Queue</message-destination-type>.

    • message-destination-usage—specifies whether messages are consumed from the destination, produced for the destination, or both. For example, <message-destination-usage>Produces<message-destination-usage>.

    • message-destination-link—links the message destination reference to the actual message destination. For example, <message-destination-link>ExpenseProcessingQueue<message-destination-link>. This value must match the destination defined in message-destination-name in the weblogic-ejb-jar.xml file.

  • message-destination

    • message-destination-name—the name of the message destination. For example, <message-destination-name>ExpenseProcessingQueue<message-destination-name>. This value must match the destination defined in message-destination-name in weblogic-ejb-jar.xml.