6 Programming and Configuring MDBs: Details

Examine the steps to program and configure MDBs.

The sections 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 4.0 annotations, see also Deployment Elements and Annotations for MDBs and Using EJB 4.0 Compliant MDBs for the equivalent settings.

This chapter includes the following sections:

Configuring Destination Type

In an Enterprise Beans 4.0 ejb-jar.xml descriptor, set message-destination-type within the MDB's message-driven element. Alternatively, set the destinationType activation configuration property in ejb-jar.xml or in @MessageDriven.activationConfig.

Configuring Transaction Management Strategy for an MDB

Learn how to configure an MDB for managing its own transactions or deferring transaction management to the container.

To configure container-level transaction management using descriptor elements:

  • Set the transaction-type element in the message-driven element in the ejb-jar.xml file to Container.

  • Set the trans-attribute element in the container-transaction element in ejb-jar.xml to Required.

    Note:

    When transaction-type is Container and no transaction attribute is specified for onMessage, the default is Required for EJB 3.0 and later MDBs, including EJB 4.0 MDBs. For MDBs using a pre-EJB 3.0 deployment descriptor, WebLogic Server defaults to NotSupported and logs a warning. In that legacy case, explicitly specify Required to make message receipt and participating transactional work in onMessage part of the same container-managed transaction.

  • To change the timeout period for the transaction, set trans-timeout-seconds in the transaction-descriptor element of weblogic-ejb-jar.xml. If a transaction times out, it is rolled back, and the message is redelivered. If trans-timeout-seconds is not specified or is set to 0, the MDB uses the configured JTA transaction timeout, whose default is 30 seconds. For an application with long-running transactions, it may be appropriate to increase the timeout period.

To configure container-level transaction management using EJB annotations:

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

To configure bean-level transaction management using descriptor elements:

  • Set the transaction-type element in the message-driven element in the ejb-jar.xml file to Bean.

  • Set the acknowledge-mode element to specify the desired JMS acknowledgment semantics, either one of the following:

See Session in Developing JMS Applications for Oracle WebLogic Server.

Configuring MDBs for Destinations

Learn how to configure local and remote destination for the MDBs. Oracle WebLogic Server MDBs support WebLogic JMS destinations and foreign (non-Oracle) JMS provider destinations.

For the configuration scenarios in this section, a local WebLogic JMS destination is hosted on the same WebLogic Server instance as the MDB, or on another server in the same cluster, and is accessible through the MDB's local JNDI tree. A WebLogic JMS destination on a server outside that cluster is remote, even if both servers run on the same machine. Servers in the same cluster can run on different machines. Use the remote-provider configuration described below when the destination requires access to a different JNDI context.

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 Oracle 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-driven-descriptor for the MDB in weblogic-ejb-jar.xml:

  • initial-context-factory

  • provider-url

  • destination-jndi-name

  • connection-factory-jndi-name

For foreign and remote destinations, the simplest configuration strategy is to use Oracle 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 Oracle WebLogic Server cluster or domain, and an object in the local WebLogic JNDI tree.

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

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:

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.

Note:

The Foreign JMS Server mapping feature is not the same as the Foreign JNDI mapping feature. MDBs generally require that you use the Foreign JMS Server feature when mapping JMS resources into JNDI. The Foreign JNDI feature is meant for non-JMS resource types.

  • 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 Developing JMS Applications 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.

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 remote WebLogic JMS or a foreign provider:

    • Without mappings, specify the destination's JNDI name in the remote provider's JNDI tree.

    • With mappings, specify the local JNDI name configured for the Foreign Destination that maps to the remote 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 Oracle 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 resources for the module is described in Configure Resources for JMS System Modules in Oracle WebLogic Remote Console Online Help.

    Note:

    If you configure a custom WebLogic JMS connection factory for an MDB, set its AcknowledgePolicy to Previous. For transactional message delivery, also enable XAConnectionFactoryEnabled in the connection factory's transaction parameters.

  • If your JMS provider is remote or foreign:

    • Without mappings, specify the connection factory's JNDI name in the remote provider's JNDI tree. For remote WebLogic JMS, you may omit this setting when using the default MDB connection factory and that factory is enabled on the remote server.

    • With mappings, specify the local JNDI name configured for the Foreign Connection Factory that maps 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 Oracle WebLogic Server or Foreign JMS Server—With Mappings

Description of Figure 6-4 follows
Description of "Figure 6-4 D. Destination on a Remote Oracle 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

Fully qualified class name of the foreign provider's initial context factory.

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

Examine the guidelines for behaviors related to message delivery:

This section includes the following topics:

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 Developing JMS Applications 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 limits concurrent MDB instances to one per pool; it does not exclude other consumers of the destination.

  • If your MDBs are deployed on a cluster, deploy them to a single node in the cluster.

Ensure that other consumers do not process the same ordered message stream concurrently. An MDB listening to a distributed destination can have a separate pool for each selected member, even when deployed on one server; a pool limit of one does not serialize processing across those members. Use Unit-of-Order when ordering is required across that configuration.

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.

See Ordered Redelivery of Messages in Developing JMS Applications for Oracle WebLogic Server.

See jakarta.jms.MessageListener.onMessage(Message) in the Jakarta Messaging API documentation.

Preventing and Handling Duplicate Messages

The container handles acknowledgement of messages delivered to a JMS MDB. A failure before acknowledgement or transaction commit can cause a message to be redelivered, subject to the JMS provider's redelivery and expiration settings.

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.

With container-managed transactions and the Required transaction attribute, message receipt and all transactional work in onMessage that participates in the same transaction are committed or rolled back together. A rollback can cause the message to be redelivered and onMessage to run again. This protects participating transactional work from duplicate committed effects caused by redelivery; it does not roll back nontransactional side effects. Transaction coordination can add CPU and disk overhead.

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

When message receipt is nontransactional, successful completion of onMessage does not by itself prevent redelivery. If the server crashes after the method returns but before the container acknowledges delivery, the message may be delivered again, as Figure 6-5 illustrates. This also applies when onMessage has already committed a bean-managed transaction, because that transaction does not include message receipt.

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

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

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 Developing JMS Applications for Oracle WebLogic Server.

Using the Message-Driven Bean Context

Oracle WebLogic Server calls setMessageDrivenContext() to associate the MDB instance with a container context. Alternatively, EJB 4.0 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:

  • getCallerPrincipal()—Returns the caller principal associated with the invocation. Do not assume that this is the principal of the JMS message producer.

  • isCallerInRole(String roleName)—Tests the invocation's caller identity against the specified role. WebLogic Server permits this method for EJB 3.1 and later MDBs, including EJB 4.0 MDBs; it throws IllegalStateException for older descriptor versions.

  • setRollbackOnly()—Can only be used by EJBs that use container-managed transactions.

  • getRollbackOnly()— Can only be used by EJBs that use container-managed transactions.

  • getUserTransaction()—Can only be used by EJBs that use bean-managed transaction demarcations.

    Both caller-identity methods may be used in message-listener methods, including onMessage, and their AroundInvoke interceptors, subject to the version requirement above. Neither method may be called during construction, dependency injection, or PostConstruct and PreDestroy callbacks. Timeout callbacks may use getCallerPrincipal(), but may not use isCallerInRole().

    Note:

    Although getEJBHome() is also inherited as part of the MessageDrivenContext interface, message-driven beans do not have a home interface. Calling getEJBHome() from within an MDB instance causes an IllegalStateException.

Configuring Suspension of Message Delivery During JMS Resource Outages

You can configure how an MDB behaves when the EJB container detects repeated failures during message processing, such as when an MDB throws the same exception ten times in succession.

You can configure:

  • An MDB to suspend the JMS connection and thereby stop receiving additional messages when the EJB container detects a JMS resource outage. If you choose this configuration option, you can specify:

    • The initial number of seconds the MDB should wait before it first resumes receiving messages.

    • The maximum number of seconds the MDB should wait before it resumes receiving messages.

  • An MDB to not suspend the JMS connection when the EJB container detects a JMS resource outage.

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.

Configuring the Number of Seconds to Suspend a JMS Connection

You can 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.xml file:

  • init-suspend-seconds—the initial amount of time, in seconds, to suspend a JMS connection when the EJB container detects a JMS resource outage. The default value is 5.

  • max-suspend-seconds—the maximum amount of time, in seconds, to suspend a JMS connection when the EJB container detects a JMS resource outage. The default value is 60.

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

When automatic suspension is enabled (max-suspend-seconds is greater than 0), repeated delivery failures cause the container to suspend the JMS connection for init-suspend-seconds. If init-suspend-seconds is 0, the container uses an initial delay of 5 seconds. When the delay expires, the container attempts to resume delivery.

If repeated failures trigger another suspension, the next delay is twice the preceding delay, capped at max-suspend-seconds. With the defaults, successive delays are 5, 10, 20, 40, and 60 seconds, with subsequent delays remaining at 60 seconds while failures continue. Successful message processing resets the failure count and initial delay.

Setting max-suspend-seconds to 0 disables this automatic suspension, as described in Turning Off Suspension of a JMS Connection.

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

An MDB's configured run-as identity determines the security identity under which its message-processing method executes. The security identity used to establish a JMS connection is determined separately, based on the JMS provider and the configured authentication mechanism. When EJB component credential mapping is used, the container can obtain the credentials required to connect to the JMS provider.

To configure a security identity for an MDB:

  1. Create a WebLogic user to serve as the MDB's local run-as identity. This user does not need to have the same username or password as the account used to authenticate to a remote JMS provider.
  2. In ejb-jar.xml, declare the MDB's run-as role within its message-driven element:
    <security-identity>
  <run-as>
    <role-name>jmsrole</role-name>
  </run-as>
</security-identity>
  3. In the ejb-jar.xml deployment descriptor, declare the corresponding security role within the assembly-descriptor element:
    <assembly-descriptor>
  <security-role>
    <role-name>jmsrole</role-name>
  </security-role>
</assembly-descriptor>
  4. In weblogic-ejb-jar.xml, add the following security-role-assignment under the root weblogic-ejb-jar element to map jmsrole to the WebLogic user created in Step 1:
    <security-role-assignment>
  <role-name>jmsrole</role-name>
  <principal-name>username</principal-name>
</security-role-assignment>

    Here, username is the name of the WebLogic user created in Step 1.

  5. If the MDB uses EJB component credential mapping to authenticate to the JMS provider, configure a mapping from the MDB's local run-as identity to the username and password required by that provider. Other supported authentication mechanisms, such as credentials configured for a Foreign JMS Server, may also be used.

For MDBs accessing WebLogic JMS in another domain, see Using MDBs With Cross Domain Security for additional security configuration requirements.

Using MDBs With Cross Domain Security

Learn how to configure cross domain security for MDBs.

Cross Domain Security secures internal communication between WebLogic domains. Configure the MDB's JNDI and JMS authentication and destination permissions separately. Successful JMS connection authentication and message consumption do not establish that destination membership notifications or transaction coordination can complete successfully.

When an MDB consumes from a WebLogic JMS destination in another domain, apply the following requirements:

  • Standalone destination, without a transaction spanning WebLogic domains: Message receipt alone does not require Cross Domain Security for distributed-destination membership or inter-domain transaction coordination. Other operations performed by the MDB may introduce additional requirements.

  • Distributed destination: Configure Cross Domain Security between the MDB domain and the destination domain for internal communication used by the JMS Configuration Directory Service (CDS) to report destination membership and availability changes. This requirement also applies when message receipt is nontransactional.

  • Transactions spanning WebLogic domains, for either destination type: Configure compatible transaction communication using Cross Domain Security or Security Interoperability Mode, as described in Configuring Secure Inter-Domain and Intra-Domain Transaction Communication in Developing JTA Applications for Oracle WebLogic Server. Security Interoperability Mode applies to JTA communication; it does not replace the distributed-destination requirement above.

Keep the participating domains' security configurations consistent in both directions, including communication back to the MDB domain. When using Cross Domain Security, configure cross-domain users and credential mappings for each communicating domain pair. For interoperability with domains that do not use Cross Domain Security, follow the excluded-domain guidance in Configuring Cross-Domain Security in Administering Security for Oracle WebLogic Server. General symmetry advice does not waive the distributed-destination requirement above.

Configuring EJBs to Use Logical Message Destinations

You can declare logical message destinations in an EJB deployment descriptor and map them to JMS queues or topics. Enterprise bean code can access a mapped destination through a message destination reference, and the container can use a logical destination link to select the source of messages for an MDB.

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.

A logical destination name identifies a deployment-time declaration. Bean code looks up the reference's environment name, such as java:comp/env/jms/ExpenseQueueRef. To configure an MDB listener, use message-destination-link directly under that bean's message-driven element.

For information on how unresolved and unavailable message destinations are handled, see EJBs and Message Destination References in Developing Enterprise Beans, Version 4.0, for Oracle WebLogic Server.

Declaring and Mapping a Logical JMS Destination

The following three examples assume that a JMS queue is already configured in a JMS system module with the JNDI name jms/ExpenseQueue and is accessible from the MDB's local JNDI tree. For existing applications that use packaged JMS modules, see Using Application-Scoped JMS Resources below.

In ejb-jar.xml, add this declaration inside assembly-descriptor: 

<message-destination>
  <message-destination-name>ExpenseProcessingQueue</message-destination-name>
</message-destination>

In weblogic-ejb-jar.xml, add this mapping directly under weblogic-ejb-jar: 

<message-destination-descriptor>
  <message-destination-name>ExpenseProcessingQueue</message-destination-name>
  <destination-jndi-name>jms/ExpenseQueue</destination-jndi-name>
</message-destination-descriptor>

The logical name must match in the declaration and mapping. This mapping refers to an existing destination; it does not create a JMS queue or define a JMS module.

Configuring a Message Destination Reference for Enterprise Bean Code

To let an enterprise bean send messages to the mapped queue, add this reference inside that bean's declaration in ejb-jar.xml: 

<message-destination-ref>
  <message-destination-ref-name>jms/ExpenseQueueRef</message-destination-ref-name>
  <message-destination-type>jakarta.jms.Queue</message-destination-type>
  <message-destination-usage>Produces</message-destination-usage>
  <message-destination-link>ExpenseProcessingQueue</message-destination-link>
</message-destination-ref>

The bean can look up java:comp/env/jms/ExpenseQueueRef to obtain the queue. This reference makes the destination available to bean code; it does not configure the MDB listener's incoming destination.

Linking an MDB to a Logical JMS Destination

Use the logical destination link and its mapping to configure the MDB's destination. Avoid conflicting destination configurations in annotations, deployment descriptors or deployment plans.

To have the container deliver messages from the mapped queue to an MDB, add these elements inside that MDB's message-driven declaration in ejb-jar.xml: 

<message-destination-type>jakarta.jms.Queue</message-destination-type>
<message-destination-link>ExpenseProcessingQueue</message-destination-link>

message-destination-type specifies the expected destination type. If a destinationType activation property is also configured, use the same value.

Place these elements after transaction-type and before activation-config, if those elements are present. Do not add message-destination-usage directly under message-driven; that element belongs to message-destination-ref.

Each MDB that uses this logical destination must declare its own link. A logical destination does not automatically configure every MDB in the application. To refer to a logical destination declared in another module, use the supported relative-module-path form, such as other-ejb.jar#ExpenseProcessingQueue, and provide the declaration and mapping in that module.

Using Application-Scoped JMS Resources

WebLogic JMS application modules, including packaged and standalone modules, are deprecated. For new applications, configure JMS resources in JMS system modules. This subsection explains resource links for existing applications that use packaged JMS modules.

In these applications, JMS modules are packaged within an enterprise application (EAR) and declared in weblogic-application.xml. A JMS module defines resources such as queues, topics and connection factories. These resources can be configured for use only by the enclosing application. Packaging a module and configuring its resources establishes their deployment and visibility; declaring a logical destination and its references establishes how enterprise beans refer to those resources.

Each MDB must still be configured to consume from its intended destination. Application scope does not automatically associate all MDBs with one destination. Different MDBs in the same application can use different resources.

For module configuration, resource scope, targeting and deployment guidance, see Configuring JMS Application Modules for Deployment (Deprecated) in Administering JMS Resources for Oracle WebLogic Server. The following descriptor fragments illustrate the names that must match in a packaged application.

For example, the EAR's META-INF/weblogic-application.xml contains this JMS module declaration under weblogic-application: 

<module>
  <name>ExpenseJMS</name>
  <type>JMS</type>
  <path>jms/expense-resources-jms.xml</path>
</module>

The file at that path, relative to the EAR root, defines the resource:

<weblogic-jms xmlns="http://xmlns.oracle.com/weblogic/weblogic-jms">
  <queue name="ExpenseQueue">
    <sub-deployment-name>ExpenseQueueTarget</sub-deployment-name>
  </queue>
</weblogic-jms>

The deployment configuration must map the ExpenseQueueTarget subdeployment within the ExpenseJMS module to the JMS server that hosts the queue. The queue in this example omits both jndi-name and local-jndi-name and is accessed through its application resource link.

To map the earlier logical destination to that queue, replace the earlier message-destination-descriptor mapping in weblogic-ejb-jar.xml with: 

<message-destination-descriptor>
  <message-destination-name>ExpenseProcessingQueue</message-destination-name>
  <destination-resource-link>ExpenseJMS#ExpenseQueue</destination-resource-link>
</message-destination-descriptor>

Keep this mapping directly under weblogic-ejb-jar. The resource-link format is JMSModuleName#ResourceName:

  • JMSModuleName must match <module><name> in weblogic-application.xml, including capitalization: ExpenseJMS in this example. The <path> identifies the JMS descriptor file and is not used in the resource link.

  • ResourceName must match the destination's name attribute in that JMS descriptor: ExpenseQueue in this example. It is separate from the JNDI name, the subdeployment name ExpenseQueueTarget, and the logical destination name ExpenseProcessingQueue.

This mapping refers to the module and queue configured above; it does not create them. A message-destination-link such as other-ejb.jar#ExpenseProcessingQueue uses a different naming convention to locate a logical declaration in another EJB module.

Retain the earlier logical message-destination declaration, any bean-code references that are needed, and each consuming MDB's message-destination-type and message-destination-link. The logical link remains ExpenseProcessingQueue; only the WebLogic mapping changes to identify the application-scoped queue.