10 Configuring and Deploying MDBs Using JMS Topics

Examine how to develop an MDB that automatically sets up JMS topic subscriptions and then processes subscription messages. A message that is published to a JMS topic is replicated to all subscriptions that have a matching selector filter.

A single deployed MDB may create multiple topic subscriptions and may have one or more free pools per host Oracle WebLogic Server instance. This behavior is controlled by MDB attribute settings, topic type, and whether the MDB is running on the same cluster or JVM as its topic. (For information about MDB free pools, see MDBs and Concurrent Processing.)

This chapter also describes how to use topic MDBs together with WebLogic JMS distributed topics. WebLogic JMS distributed topics are logical topics that are composed of multiple physical topics, where each physical topic is hosted on a different JMS Server instance. This distributed topic capability was significantly enhanced in Oracle WebLogic Server 10.3.4 to provide increased scalability and high availability. The enhancements include direct support for remotely hosted distributed topics, for fully distributing the processing of a single logical subscription across multiple physical subscriptions, and for multiple JVMs to process messages from the same physical subscription.

This chapter includes the following sections:

For additional information about JMS topics see:

Oracle recommends reviewing the previous chapters of this book before reading this chapter.

Supported Topic Types

WebLogic MDBs support singleton, foreign provider, replicated distributed, and partitioned distributed topic types.

WebLogic MDBs support the following types of topics:

  • Singleton topics -- A singleton topic is either a non-distributed WebLogic JMS topic or a reference to a particular member topic of a WebLogic JMS distributed topic. The JNDI name syntax for a WebLogic JMS uniform distributed topic member is based on the name of the JMS server that hosts the member: jms-server-name@jndi-name-of-distributed-topic.

  • Foreign provider topics -- Non-WebLogic JMS topics are called foreign provider topics. MDBs treat foreign provider topics similarly to singleton topics. Such topics are typically considered to be remote.

  • Replicated distributed topics -- WebLogic JMS distributed topics are logical topics composed of multiple physical topics, where each physical topic is hosted on a different JMS server instance in the same cluster. In releases of Oracle WebLogic Server prior to 10.3.4, each message sent to any member of a distributed topic is always automatically replicated (forwarded) to all subscriptions on all of the other members of the distributed topic. This kind of distributed topic is still supported and is now called a replicated distributed topic (abbreviated RDT).

  • Partitioned distributed topics - WebLogic JMS distributed topics are logical topics composed of multiple physical topics, where each physical topic is hosted on a different JMS server instance in the same cluster. A partitioned distributed topic (abbreviated PDT) does not forward messages between members. Messages published to a member of a PDT are only copied to subscriptions on that member. Partitioned distributed topics are supported starting with Oracle WebLogic Server 10.3.4.

To configure a distributed topic type, you set Partitioned or Replicated as the value for the JMS distributed topic configuration attribute JMS Forwarding Policy. See Configuring Partitioned Distributed Topics in Administering JMS Resources for Oracle WebLogic Server.

The Most Commonly Used MDB Attributes

Examine some of the topic MDB attributes.

The most commonly used topic MDB attributes are:

  • JMS destination and connection factory

  • Subscription durability

  • Container managed transactions

  • Message distribution tuning

Some other useful topic MDB attributes are:

  • Free pool size

  • Auto-delete on undeploy

  • Message filtering (JMS selectors)

  • Subscription identifier

The message distribution tuning settings include the topicMessagesDistributionMode, distributedDestinationConnection, and generate-unique-jms-client-id attributes.

Configure generate-unique-jms-client-id in the message-driven-descriptor element of weblogic-ejb-jar.xml. This setting controls whether WebLogic Server generates unique JMS client IDs in Compatibility mode. In the One-Copy modes, JMS client IDs are determined by the selected distribution mode's behavior.

Most attributes can be configured either by using an annotation or via descriptor XML stanzas. In addition, specific attribute names for descriptor XML stanzas and annotations are summarized in the tables in Deployment Elements and Annotations for MDBs.

Setting the JMS Destination, Destination Type, and Connection Factory

A topic MDB's configuration must properly specify the location of its JMS connection factory, its destination, and its destination type. Typically, this is accomplished by:

  1. Specify the topic type. In an Enterprise Beans 4.0 ejb-jar.xml descriptor, set message-destination-type to jakarta.jms.Topic within the MDB's message-driven element. Alternatively, set the destinationType activation configuration property to jakarta.jms.Topic in ejb-jar.xml or in @MessageDriven.activationConfig.
  2. Specifying a connection factory JNDI name and a destination JNDI name. Specifying a connection factory JNDI name is usually not necessary if the connection factory is hosted on the same cluster or server as the MDB. The default usually suffices.
  3. If the destination is not located in the same cluster or server as the MDB pool, administratively configure a mapping from the remote destination and connection factory JNDI entries to local JNDI entries that match those specified in #2. There are alternative approaches to referencing remote resources, but the mapping approach is the Oracle-recommended best practice.

For each free pool, the MDB container creates a connection using the specified connection factory, then uses the connection to find or create one or more subscriptions on its destination, and finally uses the connection to create JMS consumers that receive the messages from the subscription(s).

For the specific names of connection factory and destination MDB attributes, as well as recommended JNDI mapping configuration, see Configuring MDBs for Destinations.

Setting Subscription Durability

MDBs automatically create subscriptions on JMS topics. JMS topics support two types of subscriptions: durable and non-durable.

  • Non-durable subscriptions exist only for the length of time their subscribers exist. When a subscription has no more subscribers, the subscription is automatically deleted. Messages stored in a non-durable subscription are never recovered after a JMS server shut down or crash.

  • Durable subscriptions make it possible for a subscriber to receive messages that are published while the subscriber application is unavailable. For each durable subscription on a topic, JMS retains matching persistent messages until they are acknowledged, unless they expire or are otherwise removed under the provider's message-management policies. This includes messages published while the durable subscription has no active consumer. For messages consumed in a transaction, acknowledgement takes effect when the transaction commits. JMS also stores a copy of each non-persistent message in each durable subscription, but such messages are not recovered if the JMS server shuts down or crashes.

    Non-durable subscriptions are the default. To configure a durable subscription, set the subscriptionDurability activation configuration property to Durable. In ejb-jar.xml, add the following property to the MDB's activation-config element within message-driven: 

<activation-config-property>
  <activation-config-property-name>subscriptionDurability</activation-config-property-name>
  <activation-config-property-value>Durable</activation-config-property-value>
</activation-config-property>

Alternatively, add @ActivationConfigProperty(propertyName = "subscriptionDurability", propertyValue = "Durable") to @MessageDriven.activationConfig.

Setting Automatic Deletion of Durable Subscriptions

You can configure an MDB to automatically delete a durable topic subscription when the MDB is undeployed or deleted from a server. To configure an MDB to automatically delete durable topic subscriptions, set durable-subscription-deletion to True. By default, durable-subscription-deletion is set to False

Setting Container Managed Transactions

See Configuring Transaction Management Strategy for an MDB.

Setting Message Filtering (JMS Selectors)

JMS provides an SQL-like syntax for filtering messages based on standard JMS message header fields and message properties. In addition, WebLogic JMS supports an extension to the selector syntax that allows the specification of selectors that include XML "xpath" expressions for filtering XML messages based on their XML contents.

One way to specify a message selector is to specify it as the propertyValue for an ActivationConfigProperty with propertyName = "messageSelector".

The syntax of JMS selectors is fully described in the Javadoc for the jakarta.jms.Message class. The WebLogic xpath selector extension syntax is described in Filtering Messages in Developing JMS Applications for Oracle WebLogic Server.

Controlling MDB Concurrency

As discussed in Topic Deployment Scenarios, an MDB deployment may create one or more MDB free pools. The max-beans-in-free-pool and dispatch-policy descriptor attributes work together to control MDB thread concurrency in an MDB free pool as follows:

  • For a discussion of how to determine the number of concurrent MDBs, see Determining the Number of Concurrent MDBs in Tuning Performance of Oracle WebLogic Server.

  • In Compatibility mode, concurrency also depends on the JMS provider and transaction-batching configuration. With WebLogic JMS and one message per transaction, transactional MDB invocations can run concurrently within the configured concurrency limits. With container-managed transaction batching in Compatibility mode, only one MDB onMessage invocation runs at a time per free pool. In addition, max-beans-in-free-pool should be explicitly set to 1 for bean-managed transaction MDBs that are driven by a foreign (non-WebLogic) topic.

    Caution:

    Non-transactional Foreign Topics: Oracle recommends explicitly setting max-beans-in-free-pool to 1 for non-transactional MDBs that consume from foreign (non-WebLogic) topics through WebLogic Server's JMS integration. This integration supports foreign topics in Compatibility mode and limits message processing to one concurrent MDB invocation per free pool. This concurrency limit does not make non-transactional processing atomic or guarantee recovery from application failures.

    Unit-of-Order: Oracle recommends explicitly setting max-beans-in-free-pool to 1 for non-transactional Compatibility mode MDBs that consume from a WebLogic JMS topic and process messages that have a WebLogic JMS Unit-of-Order value. Unit-of-Order messages in this use case may not be processed in order unless max-beans-in-free-pool is set to 1.

See Tuning Message-Driven Beans in Tuning Performance of Oracle WebLogic Server for more information.

Setting Subscription Identifiers

Individual JMS topic subscriptions are created and referenced based on their "subscription identifier," which an MDB generates based on a number of MDB configuration settings. For a discussion of the syntax of generated subscription identifiers, see Topic Subscription Identifiers.

Setting Message Distribution Tuning

This section describes how and when to use message distribution tuning settings. It contains information that applies to all topic types (singleton, foreign, and distributed). The settings include the topicMessagesDistributionMode, distributedDestinationConnection, and generate-unique-jms-client-id attributes. They control where topic subscriptions are created, what the subscription identifiers are, and whether an MDB processes each published topic message only once or once per server.

For detailed descriptions and diagrams of the resulting automatically generated subscription IDs, subscription locations, and deployed MDB free pool locations, see Topic Deployment Scenarios, and Topic Subscription Identifiers.

Setting topicMessagesDistributionMode

Use the topicMessagesDistributionMode setting in combination with the distributedDestinationConnection setting or the generate-unique-jms-client-id setting to control topic message processing behavior. To configure topicMessagesDistributionMode, set that activation configuration property's value in the MDB's activation-config element in ejb-jar.xml, or use @ActivationConfigProperty(propertyName = "topicMessagesDistributionMode", propertyValue = "One-Copy-Per-Application") within @MessageDriven.activationConfig, substituting the desired mode.

The valid values for topicMessagesDistributionMode are:

  • One-Copy-Per-Application -- Specifies that the MDB application as a whole receives each message published to a distributed topic once, no matter how many servers host the application. This mode works with WebLogic JMS singleton and distributed topics in Oracle WebLogic Server 10.3.4 and later.

  • One-Copy-Per-Server -- Specifies that each deployment instance of the MDB application receives every message published to a distributed topic. This mode works with WebLogic JMS singleton and distributed topics in Oracle WebLogic Server 10.3.4 and later.

  • Compatibility - (Default) Specifies that the MDB application handles messages from distributed topics in the same way they were handled in Oracle WebLogic Server releases prior to 10.3.4. The mode supports durable and non-durable subscriptions with foreign (non-WebLogic) topics, local replicated distributed topics (RDTs), and singleton WebLogic topics; it also supports non-durable subscriptions with remote replicated distributed topics. See the Compatibility notes section for more detail.

    Note:

    Oracle recommends using the One-Copy-Per-Application and One-Copy-Per-Server modes for most new applications, except those that must consume from WebLogic JMS topics in versions of Oracle WebLogic Server prior to 10.3.4 or from foreign (non-WebLogic) topics.

    The topic distribution modes support different topic types and versions with the following restrictions:

    • The One-Copy-Per-Application and One-Copy-Per-Server modes work only with WebLogic singleton and distributed topics in Oracle WebLogic Server 10.3.4 and later. WebLogic MDBs log a warning and do not process messages with these modes when using a foreign (non-WebLogic) topic or when using a WebLogic topic from Oracle WebLogic Server releases prior to 10.3.4.

    • One-Copy-Per-Server topic MDBs that are durable, that subscribe to a local RDT, and that use the default LocalOnly value for the distributedDestinationConnection attribute, do not support Service Migration and require that exactly one topic member be configured per Oracle WebLogic Server instance. If a service migration occurs, if there is no local topic member configured, or if more than one topic member is deployed per server, then the application may experience duplicate or lost messages and may also create abandoned subscriptions that accumulate unprocessed messages. If service migration is required, then use the EveryMember option for the distributedDestinationConnection attribute instead of the default LocalOnly. All other JMS service-migration and MDB deployment requirements still apply. See Migration and Recovery for Clustered MDBs.

    • The Compatibility mode supports durable and non-durable subscriptions with foreign (non-WebLogic) topics, with local replicated distributed topics (RDTs) (with limitations described later), and with singleton WebLogic topics. Compatibility mode also supports non-durable subscriptions with a remote RDT. A deployment of a durable MDB that subscribes to the logical JNDI name of a remote RDT may succeed, but the MDB deployment will fail to connect, with Warning log messages. Similarly, a deployment of an MDB that subscribes to a WebLogic PDT may succeed, but the MDB deployment will fail to connect, with Warning log messages. See Notes on the Compatibility mode of topicMessagesDistributionMode, for more detail.

    • For durable Compatibility-mode MDBs that subscribe to a local RDT, see Notes on the Compatibility mode of topicMessagesDistributionMode.

    For detailed descriptions and diagrams of MDB generated subscriptions, subscription IDs, and free pool locations, refer to Topic Deployment Scenarios, and Topic Subscription Identifiers.

Setting distributedDestinationConnection

To optionally fine tune the behavior of the One-Copy-Per-Application and One-Copy-Per-Server modes of topicMessagesDistributionMode for a local distributed topic, you can use the distributedDestinationConnection activation config property. Alternatively, you can use the distributed-destination-connection element in the weblogic-ejb-jar.xml deployment descriptor. The valid values are LocalOnly and EveryMember.

For local distributed topics, EveryMember creates an MDB free pool for each topic member, while LocalOnly restricts connections to members on the MDB's current WebLogic Server. Although the descriptor default is LocalOnly, a local partitioned distributed topic in One-Copy-Per-Server mode uses EveryMember. When LocalOnly is explicitly configured or supplied by default for that combination, WebLogic overrides it and logs warning 015035.

Use this setting to tune local distributed-topic connections in the One-Copy modes. For remote distributed topics, the container determines member connections from the topic type, distribution mode and subscription durability. In Compatibility mode, this setting does not control which destination members the MDB connects to, but it can affect generated JMS client IDs when generate-unique-jms-client-id is enabled.

One reason to use EveryMember is that the LocalOnly option for durable MDBs has restrictions for local RDTs in the One-Copy-Per-Server mode. See Warning About Using Local RDTs with Durable MDBs.

Another reason to use EveryMember is to better handle uneven message loads or message processing delays. See Handling Uneven Message Loads and/or Message Processing Delays, for advice.

Notes on the Compatibility mode of topicMessagesDistributionMode

  • See Setting topicMessagesDistributionMode, for a statement about supported topic types and versions.

  • If you're using the Compatibility topicMessagesDistributionMode in combination with non-transactional MDBs, and the topic is a foreign (non-WebLogic) destination, or the topic is a WebLogic destination with Unit-of-Order (UOO) messages, then see Controlling MDB Concurrency, for warnings.

  • Set the generate-unique-jms-client-id attribute to change behavior:

    • If generate-unique-jms-client-id is set to true, each durable MDB free pool generates a unique subscriber ID. Each MDB free pool will then receive a copy of each published message. For more information see Topic Subscription Identifiers. For more information about free pools, see MDBs and Concurrent Processing, and Topic Deployment Scenarios.

    • If generate-unique-jms-client-id is false (the default), only one subscription will be created by a durable MDB, and only one MDB free pool will successfully connect to the durable subscription (the remaining MDB pools will fail to connect, log warnings, and will keep retrying).

  • For durable subscription MDBs that subscribe to the logical name of a local replicated distributed topic (a local RDT), only the configuration described in Warning About Using Local RDTs with Durable MDBs, is supported.

  • For durable subscription MDBs that subscribe to the logical name of a remote replicated topic (a remote RDT):

    • A deployment of a durable MDB that subscribes to the logical JNDI name of the RDT may succeed, but the MDB will fail to connect and will log warning messages.

  • For durable subscription MDBs that subscribe to a particular member destination of a remote replicated topic:

    • A deployment of a durable MDB that subscribes directly to a member of the RDT will succeed, and the subsequent behavior will be determined by the generate-unique-jms-client-id setting. For a uniform distributed destination, the JNDI name of a particular member is "jms-server-name@udd-jndi-name".

  • For a non-durable subscription MDB that subscribes to the logical name of a local replicated distributed topic (a local RDT), only the configuration described in Warning About Using Local RDTs with Non-Durable MDBs, is fully supported.

  • In Compatibility mode, distributedDestinationConnection does not control which destination members the MDB connects to, but it can affect generated JMS client IDs when generate-unique-jms-client-id is enabled.

Best Practices

Examine some of the best practices when you configure MDBs.

Consider the information in the following sections to help you configure MDBs.

Warning about Non-Transactional MDBs in Compatibility Mode

If you're using the Compatibility mode of topicMessagesDistributionMode in combination with non-transactional MDBs and the topic is a foreign (non-WebLogic) destination or the topic is a WebLogic destination with Unit-of-Order (UOO) messages, see Controlling MDB Concurrency, for warnings.

Warning About Using Local RDTs with Durable MDBs

In Compatibility mode, for durable subscription MDBs that subscribe to the logical name of a local replicated distributed topic (a local RDT), only the following configuration is supported:

  • Always set generate-unique-jms-client-id to true.

  • Ensure each Oracle WebLogic Server in the cluster hosts exactly one member of the RDT.

  • Do not use WebLogic JMS service-migration. It is unsupported for this use case; but you can use "whole server migration."

  • Note that each server receives a copy of each message sent to the topic. When a message arrives at one of the RDT physical topic members, the RDT automatically ensures that a copy of the message is forwarded to each of the other members of the topic.

For durable MDBs in One-Copy-Per-Server mode that subscribe to the logical name of a local RDT with distributedDestinationConnection=LocalOnly, the same one-member-per-server and service-migration restrictions apply. In this mode, each server hosting the MDB uses its own subscription identity. The generate-unique-jms-client-id setting applies to Compatibility mode and is not required for this One-Copy mode.

If your configuration does not match the recommendations, you may get nondeterministic behavior, including lost messages, duplicate messages, and stuck messages. For more information, including alternatives, see Setting topicMessagesDistributionMode.

Warning About Using Local RDTs with Non-Durable MDBs

In Compatibility mode, for non-durable subscription MDBs that subscribe to the logical name of a local replicated distributed topic (a local RDT), only the following configuration is fully supported:

  • Ensure each Oracle WebLogic Server in the cluster hosts exactly one member of the RDT.

  • Do not use WebLogic JMS service-migration. It is unsupported for this use case; but you can use "whole server migration."

  • Note that each server receives a copy of each message sent to the topic. When a message arrives at one of the RDT physical topic members, the RDT automatically ensures that a copy of the message is forwarded to each of the other members of the topic.

The same one-member-per-server and service-migration restrictions apply to non-durable MDBs in One-Copy-Per-Server mode that subscribe to the logical name of a local RDT with distributedDestinationConnection=LocalOnly. In this mode, each server hosting the MDB uses its own subscription identity.

If your configuration does not match the recommendations, you may get nondeterministic behavior, including lost messages, duplicate messages, and stuck messages. For more information, including alternatives, see Setting topicMessagesDistributionMode.

Warning about Changing Durable MDB Attributes, Topic Type, EJB Name

Changing MDB or JMS settings can cause the current messages on durable subscriptions to be deleted, or can cause existing durable subscriptions to be abandoned, deleted, or replaced in favor of new durable subscriptions. These settings include topic type, JMS selector, distribution tuning, subscription durability, ejb-name, and client-id.

Abandoned durable subscriptions continue to accumulate messages even though no MDB is processing the messages. This can eventually lead to quota exceptions or even JVM out-of-memory errors that prevent additional messages from being published to the topic.

For a discussion about locating and removing abandoned subscriptions see Managing Durable Subscriptions in Developing JMS Applications for Oracle WebLogic Server. For a discussion about subscription IDs and locations, see Topic Subscription Identifiers.

Choosing Between Partitioned and Replicated Topics

Supported Topic Types, describes the two types of WebLogic distributed topics (partitioned and replicated). In general, Oracle recommends using partitioned topics (PDTs), when available, except for these two cases:

  • When replicated topic (RDT) behavior is required to interoperate with legacy applications or non-MDB applications.

  • In the local RDT case in the One-Copy-Per-Server LocalOnly case under certain message loads. The message load determines whether the heavy forwarding overhead built into an RDT is less expensive in comparison to the increased network traffic required for the fully connected topology in the PDT One-Copy-Per-Server mode. In general, it is better to use a PDT for non-persistent or "lighter" persistent message loads.

To configure a distributed topic type, you set Partitioned or Replicated as the value for the WebLogic JMS Distributed Topic configuration attribute JMS Forwarding Policy. See Configuring Partitioned Distributed Topics in Administering JMS Resources for Oracle WebLogic Server.

Choosing an MDB Topic Messages Distribution Mode

Oracle recommends using the One-Copy-Per-Application and One-Copy-Per-Server modes for most new applications, except for those that must consume from WebLogic JMS topics in Oracle WebLogic Server releases prior to 10.3.4 or from foreign (non-WebLogic) topics. These two modes only work with WebLogic JMS topics in Oracle WebLogic Server 10.3.4 or later.

Managing and Viewing Subscriptions:

See Topic Deployment Scenarios, and Topic Subscription Identifiers, for detailed discussions of the names and location of subscriptions.

See also Managing Durable Subscriptions in Developing JMS Applications for Oracle WebLogic Server.

Handling Uneven Message Loads and/or Message Processing Delays

For applications with uneven message loads or unanticipated message processing delays, you may want to consider the following:

  • In One-Copy-Per-Application mode with a local distributed topic, consider distributedDestinationConnection=EveryMember when message backlogs or processing costs are uneven across members. MDB instances on different servers can then participate in processing messages from shared subscriptions, although this can increase network traffic. In One-Copy-Per-Server mode, each MDB server uses its own subscription identity; EveryMember does not turn those separate subscriptions into one shared application subscription. For a PDT in that mode, EveryMember is already the effective connection mode.

  • To distribute incoming messages among PDT members, configure producer load balancing on the producer's connection factory. Enabling Load Balancing Enabled and disabling Server Affinity Enabled can spread sends beyond local members, but the result also depends on the distributed topic's load-balancing policy and routing constraints such as transaction affinity and Unit-of-Order. These settings do not guarantee equal MDB processing load. Disabling Server Affinity Enabled does not disable the RDT producer load balancer's local-member preference. See Load Balancing Messages Across a Distributed Destination in Administering JMS Resources for Oracle WebLogic Server.

  • Decrease the WebLogic JMS asynchronous message pipeline size to 1 to prevent additional messages from being pushed to an MDB thread that is already blocked processing a previous message. The default for this setting is 10, and it is configured by (a) configuring a custom WebLogic connection factory with the Messages Maximum attribute tuned to 1 and XA Enabled set to true, (b) targeting the connection factory to the same cluster that hosts the distributed topic, and (c) modifying the MDB so that it references the custom connection factory.

Configuring for Service Migration

Examine how to configure service migration manually or automatically in an MDB deployment.

For durable MDBs in One-Copy-Per-Server mode that subscribe to a local RDT, configure distributedDestinationConnection=EveryMember if JMS service migration is required. All other JMS service-migration and MDB deployment requirements still apply. The LocalOnly configuration is subject to the restrictions in Warning About Using Local RDTs with Durable MDBs. Compatibility mode has separate restrictions described in that section; setting EveryMember does not remove them.

With LocalOnly, member connections depend on which topic members are hosted on the MDB's current server. For One-Copy-Per-Application, ensure that the MDB is deployed on every candidate server that can host a migrated topic member. See Migration and Recovery for Clustered MDBs for the migration cautions and deployment guidance. Whole server migration remains an alternative for the configurations described in the local-RDT warnings.

Upgrading Applications from Previous Releases

Examine the steps to upgrade MDB applications to take advantage of features such as scalability and high availability in the latest releases.

As described throughout this chapter, new JMS features in Oracle WebLogic Server 10.3.4, such as relaxed client ID, sharable subscriptions, and partitioned distributed topics, make it possible to implement and deploy MDBs that provide enhanced scalability and high availability. To take advantage of these features, you must upgrade MDB applications written for releases of Oracle WebLogic Server prior to 10.3.4.

Compatibility, the default setting for topicMessagesDistributionMode, preserves legacy topic-message distribution behavior. Applications from earlier releases must also satisfy the application-migration requirements of the target WebLogic Server release, including any required migration from Java EE javax.* APIs to their Jakarta EE jakarta.* equivalents. See Setting topicMessagesDistributionMode for the behavior of this mode.

To upgrade applications from previous releases,

  1. Consider changing to a partitioned distributed topic. See Choosing Between Partitioned and Replicated Topics.
  2. Set the topicMessagesDistributionMode to One-Copy-Per-Server or One-Copy-Per-Application and tune the distributedDestinationConnection options. See Setting Message Distribution Tuning.

Caution:

Current messages are not preserved when changing out of Compatibility mode. See Warning about Changing Durable MDB Attributes, Topic Type, EJB Name.

Topic MDB Sample

Examine a sample MDB using distributed topics.

Example 10-1 shows an MDB that uses a durable subscription to a WebLogic JMS topic, processes messages in a container-managed transaction, and forwards them to a target destination.

The MDB connects using JMS connection factory MyCF to receive from topic MyTopic. It forwards the messages to MyTargetDest using a connection generated from connection factory MyTargetCF.

This example assumes that MyTopic, MyCF, MyTargetCF and MyTargetDest are configured and available in the MDB's local JNDI tree. For WebLogic JMS connection factories defined in a JMS module, enable XAConnectionFactoryEnabled on both MyCF and MyTargetCF to support transactional receipt and forwarding. For more about MDB connection-factory configuration, see How to Set connection-factory-jndi-name.

The Required transaction attribute causes onMessage to execute in a container-managed transaction. Message receipt and JMS operations that participate in that transaction are committed or rolled back together. The call to createSession(false, Session.AUTO_ACKNOWLEDGE) does not, by itself, exclude a WebLogic-managed JMS session from participating in the container transaction.

Resource reference pooling note: The MDB uses a resource reference to access MyTargetCF. The resource reference automatically enables JMS producer pooling, as described in Enhanced Support for Using WebLogic JMS with EJBs and Servlets in Developing JMS Applications for Oracle WebLogic Server.

For a similar sample using queues instead of topics, see Example 7-3.

Example 10-1 Sample MDB Using Distributed Topics

package test;
import jakarta.annotation.Resources;
import jakarta.annotation.Resource;
import jakarta.ejb.ActivationConfigProperty;
import jakarta.ejb.MessageDriven;
import jakarta.ejb.MessageDrivenContext;
import jakarta.ejb.TransactionAttribute;
import jakarta.ejb.TransactionAttributeType;
import jakarta.jms.*;
 
@MessageDriven(
  name = "MyMDB",
  activationConfig = {
    @ActivationConfigProperty(propertyName  = "destinationType", 
                              propertyValue = "jakarta.jms.Topic"),
 
    @ActivationConfigProperty(propertyName  = "subscriptionDurability",
                              propertyValue = "Durable"),
 
    @ActivationConfigProperty(propertyName  = "connectionFactoryJndiName",
                              propertyValue = "MyCF"), // External JNDI Name
 
    @ActivationConfigProperty(propertyName  = "destinationJndiName",
                              propertyValue = "MyTopic"), // Ext. JNDI Name
 
    @ActivationConfigProperty(propertyName  = "topicMessagesDistributionMode",
                              propertyValue = "One-Copy-Per-Application") 
  }
)
 
@Resources ({
  @Resource(name="targetCFRef",        
            mappedName="MyTargetCF",   // External JNDI name 
            type=jakarta.jms.ConnectionFactory.class),
 
  @Resource(name="targetDestRef", 
            mappedName="MyTargetDest", // External JNDI name
            type=jakarta.jms.Destination.class)
})

public class MyMDB implements MessageListener {

  // inject a reference to the MDB context

  @Resource
  private MessageDrivenContext mdctx;  

  // cache targetCF and targetDest for re-use (performance) 

  private ConnectionFactory targetCF;
  private Destination targetDest;

  @TransactionAttribute(value = TransactionAttributeType.REQUIRED)
  public void onMessage(Message message) {

    System.out.println("My MDB got message: " + message);

    // Forward the message to "MyTargetDest" using "MyTargetCF"

    Connection jmsConnection = null;

    try {
      if (targetCF == null) 
        targetCF = (jakarta.jms.ConnectionFactory)mdctx.lookup("targetCFRef");

      if (targetDest == null)
        targetDest = (jakarta.jms.Destination)mdctx.lookup("targetDestRef");

      jmsConnection = targetCF.createConnection();
      Session s = jmsConnection.createSession(false, Session.AUTO_ACKNOWLEDGE);
      MessageProducer mp = s.createProducer(null);

      mp.send(targetDest, message);

    } catch (JMSException e) {

      System.out.println("Forcing rollback due to exception " + e);
      e.printStackTrace();
      mdctx.setRollbackOnly();

    } finally {

      // Closing a connection automatically returns the connection and
      // its session plus producer to the resource reference pool.

      try { if (jmsConnection != null) jmsConnection.close(); }
      catch (JMSException ignored) {};
    }
  }
 
}