13 Developing Advanced Pub/Sub Applications

Understand the advanced WebLogic JMS publish and subscribe (pub/sub) concepts and functionality of Uniform Distributed Topics (UDTs) necessary to design high availability (HA) applications.

Overview of Advanced High Availability Concepts

WebLogic messaging offers high availability and scalability by using distributed destinations. The WebLogic Server migration features also provide high availability for the individual members of a distributed destination.

Note:

Oracle recommends designing applications that utilize WebLogic Server MDBs or the Oracle SOA JMS Adapter rather than explicitly handling all potential topology changes.

WebLogic Messaging High Availability Features

Oracle's WebLogic messaging offers high availability (HA) and scalability using the following features:

Distributed Destinations make a group of JMS physical destinations accessible as a single, logical destination to a client. Applications that use distributed destinations usually have higher availability and better scalability because WebLogic JMS provides load balancing and failover among member destinations of a distributed destination within a cluster. Automatic Service Migration (ASM) and Whole Server Migration (WSM) enable restarting either a set of services (including JMS servers and destinations) or an entire WebLogic Server instance in a new location. These migration features provide high availability for the individual members of a distributed destination.

The nature of these technologies means that the topology of a JMS system can be unknown to a client application as:

  • The scaling of a cluster, along with the scaling of a distributed destination may exceed the number of consumers defined by the application.

  • The topology may dynamically change in the event of a server or service failure.

Typically, topology changes are handled transparently using MDBs either locally or on a remote WebLogic Server instance. However, when using other client types, these topology changes must be explicitly handled by the application, especially if the application is remote to the servers hosting the JMS destinations.

Application Design Limitations When Using Replicated Distributed Topics

Applications implementing Uniform Distributed Topics earlier than WebLogic Server 10.3.4.0 were constrained by the following limitations:

  • Messages are always forwarded and duplicated across a distributed topic, which means that either parallel processing, and/or ensuring that a clustered application gets one copy of each message, may requires significant additional configuration, coding, and message hops.

  • Only one consumer at a time can process the messages in a given subscription except for the limited case of Non-XA MDBs where all processing of the subscription must occur on the same server with a thread pool. This prevents most customers from designing application architectures that intend to have "round-robin" distributed or parallel processing of a single subscription's topic messages, instead of single-threaded processing.

  • MDBs only directly support durable subscriptions on distributed topics that are located in the same cluster.

  • For applications other than MDBs, a durable subscriber created for a distributed topic can only be created on a distributed topic (DT) member, and the durable subscription will only exist on that member. If the member hosting the subscription is down, then the subscription will not be available to any subscriber (and is therefore not "highly available" by definition).

  • Pinning subscribers to a distributed topic member prevents automatic adjustment to changes in topology in the same way that adjustments are made for distributed queues.

Advanced Topic Features

Starting in WebLogic Server 10.3.4.0, partitioned distributed topics, combined with the ability to share subscriptions and allow multiple connections to use the same Client ID, provide the following application design patterns that provide parallel processing and HA capabilities similar to distributed queues:

  • One copy per instance: Each instance of an application gets one copy of each message that is published to the Topic.

  • One copy per application: Each application as a whole (that is all instances of the application together) receives one copy of each message that is published to the Topic. Each instance only receives a subset of the messages that are sent to the Topic.

Note:

Oracle recommends designing applications that utilize WebLogic Server MDBs. See Configuring and Deploying MDBs Using JMS Topics in Programming Message-Driven Beans for Oracle WebLogic Server for detailed information about how to design and implement applications that use message-driven beans to provide improved HA and scalability.

Advanced Topic Messaging Features for High Availability

In order to understand how an application can achieve One-copy-per-instance and One-copy-per-application design patterns, you need to understand the new and changed features such as shared subscriptions and the client ID policy.

Shared Subscriptions and Client ID Policy

Before WebLogic Server 10.3.4.0, one subscription, durable or non durable, could only be accessed by a single subscriber instance at any time. Each subscriber receives all messages that are sent to a topic after the subscription is established and the messages for each subscription are processed sequentially by one consumer.

In this WebLogic Server release, multiple subscribers can share one subscription (durable or non durable). Messages are distributed among multiple consumers that share the same subscription and can be processed in parallel. Subscription sharing only occurs on the same destination instance or the same member instance of a DT. See Configure Shared Subscriptions in Administering JMS Resources for Oracle WebLogic Server.

WebLogic supports policy-based subscription sharing and the standard named shared-subscription APIs. For policy-based sharing through the traditional subscriber APIs, configure a client ID and the Sharable Subscription Sharing Policy. The standard Session.createSharedConsumer() and Session.createSharedDurableConsumer() APIs instead take a subscription name; they do not require a client ID or a Sharable connection-factory setting. Distributed-topic restrictions are described in Considerations When Using Standard Shared Subscriptions.

Client ID Policy controls reuse of a client ID by connections. Restricted, the default, prevents another Restricted connection in the cluster from using that client ID concurrently. Unrestricted permits reuse. The policies also distinguish subscriptions; do not treat otherwise identical Restricted and Unrestricted subscriptions as the same subscription. See How Sharing a Durable Subscription Works.

What Is the Subscription Key

A subscription’s identity depends on the API and client ID policy used to create it. For WebLogic policy-based non-durable sharing, consumers must use the same client ID and client ID policy, and must match the physical topic, message selector, and noLocal setting. A different physical topic, selector, or noLocal setting creates a separate non-durable subscription.

For durable subscriptions, the subscription name and client ID, when present, identify the subscription within the applicable client-ID-policy scope. With Unrestricted client ID policy, matching names and client IDs can identify separate subscriptions on different physical topics or distributed-topic members. Restricted subscriptions do not acquire that member-local identity simply by reusing the same name.

Standard named shared subscriptions use a subscription name and, when configured, a client ID. Follow the matching rules of the standard creation API and the WebLogic distributed-topic restrictions described in Considerations When Using Standard Shared Subscriptions.

Configuring a Shared Subscription

For WebLogic policy-based sharing, set Subscription Sharing Policy to Sharable on the connection factory, or use the applicable WebLogic connection-level override before creating consumers. Consumers from different connection factories can share a subscription when their effective policies and subscription details match. Sharing is local to a physical topic or distributed-topic member. See What Is the Subscription Key and SubscriptionSharingPolicy in MBean Reference for Oracle WebLogic Server.

How Sharing a Non-Durable Subscription Works

This section describes WebLogic policy-based non-durable sharing through the traditional subscriber APIs. Set a client ID and the Sharable Subscription Sharing Policy. Without a client ID, those APIs create separate non-durable subscriptions even when the policy is Sharable. Standard named shared subscriptions can omit the client ID; see Considerations When Using Standard Shared Subscriptions.

The first subscriber that is created with a subscription key creates the subscription. All subsequently created subscribers with the same subscription key share the subscription created by the first subscriber if all subscription details (such as: the selector, noLocal option, and the physical destination) match. For example:

  • If a subscription is created with a selector and noLocal option, a subscriber creation call that uses the same subscription key but a different selector, noLocal option or a different physical destination is treated as a different subscription.

  • Multiple Exclusive non-durable consumers with otherwise matching subscription details receive through independent subscriptions. Mixing Exclusive and Sharable consumers with matching details can instead fail because of a policy conflict; see How a Shared Subscription Policy for a Non-Durable Subscription Is Determined.

    Note:

    Connections using the same Restricted client ID cannot coexist. Use the same connection, or use Unrestricted client ID policy consistently when separate connections need the same client ID.

How a Shared Subscription Policy for a Non-Durable Subscription Is Determined

For WebLogic policy-based non-durable sharing, matching Sharable consumers join the same subscription on the physical topic. While matching consumers are active, creating a consumer with a conflicting Exclusive or Sharable policy fails with a jakarta.jms.JMSException.

Multiple Exclusive non-durable consumers are permitted with otherwise matching subscription details; each uses an independent subscription. An Exclusive consumer therefore does not join the existing consumer’s subscription. This differs from an exclusive durable subscription, which cannot have multiple active consumers.

Closing the last consumer removes a non-durable subscription. Creating consumers afterward creates new subscriptions according to their effective settings.

How a Non-Durable Subscription Is Closed

When the last consumer of a non-durable subscription closes, the subscription and its associated resources are removed.

There is no runtime MBean that represents a non-durable subscription, regardless of whether it is a shared or exclusive subscription. It is possible to monitor individual subscribers using the appropriate JMSConsumerRuntime MBean.

How Sharing a Durable Subscription Works

This section describes WebLogic policy-based durable sharing. Consumers share an existing durable subscription only when its identity and subscription details match and the effective sharing policy permits sharing. A Restricted client ID and subscription name identify the existing subscription within the cluster. With Unrestricted client ID policy, the same client ID and subscription name can identify separate subscriptions on different physical topics or distributed-topic members; consumers share only the subscription on the same physical destination.

Matching subscription details include the selector and noLocal setting. Changing either setting is a subscription change, not a way to attach another consumer to the unchanged subscription.

A creation request that changes subscription details fails with a jakarta.jms.JMSException while the existing subscription is in use. When the old subscription can be deleted, replacing it discards its retained messages. Close its consumers and complete outstanding transactions before attempting such a change; absence of active consumers alone does not guarantee that deletion can proceed.

Changing only Subscription Sharing Policy after all consumers close does not delete the subscription’s retained messages. See How a Shared Subscription Policy for a Durable Subscription Is Determined. For standard named shared subscriptions, see Considerations When Using Standard Shared Subscriptions.

How a Shared Subscription Policy for a Durable Subscription Is Determined

For WebLogic policy-based durable sharing, the first active consumer establishes the subscription’s sharing policy. While the subscription has active consumers, a request with a conflicting policy fails with a jakarta.jms.JMSException. After all consumers close, a new consumer can establish a different sharing policy.

An Exclusive durable subscription permits only one active consumer. A Sharable durable subscription permits multiple matching Sharable consumers; it does not permit an Exclusive consumer to join while those consumers remain active.

Note:

Changing the Subscription Sharing Policy on an existing durable subscription does not delete any messages that already exist on the subscription.

How to Unsubscribe a Durable Subscription

Before unsubscribing a subscription, you must consider the Client ID Policy for the subscription:

  • Applications that use a client ID Policy with a value of RESTRICTED unsubscribe a durable subscription using the standard Session.unsubscribe(String name) API.

Note:

Before WebLogic Server 10.3.4.0, all client IDs are RESTRICTED by default. A client ID could only be used by one connection at any given time in a WLS JMS cluster.

  • For Unrestricted client ID policy, use WLSession.unsubscribe(Topic topic, String name). Supply the physical topic or distributed-topic member first, followed by the subscription name. A logical distributed-topic object or a null topic is not valid for this call.

Considerations When Unsubscribing a Durable Subscriber

The following section provides information on how to unsubscribe or avoid scenarios that throw an exception:

  • If there are active consumers on the subscription, a call to the unsubscribe() method throws a JMSException.

  • Close all consumers and complete outstanding transactions before unsubscribing. Uncommitted or unacknowledged receives can prevent deletion even after the consumers have closed. A successful unsubscribe removes the matching durable subscription and its retained messages; handle JMSException if the operation cannot complete.

  • The unsubscribe() method of a durable subscription is done per standalone topic or per member of a DT.

  • A subscription created using a connection with a RESTRICTED client ID can only be cleaned up from a connection that uses the same RESTRICTED Client ID.

  • A subscription created using a connection with an UNRESTRICTED client ID can only be cleaned up from a connection using the same UNRESTRICTED client ID.

  • If WebLogic JMS does not find a matching subscription on the topic that was created with the same client ID and client ID Policy as the unsubscribe call, then an InvalidDestinationException is thrown.

  • If an unsubscribe call with an UNRESTRICTED client ID specifies a DT or does not specify any Topic, then an InvalidDestinationException is thrown.

  • Although .Net and C API messaging applications can share subscriptions by using the client ID Policy and Subscription Sharing Policy on a connection factory deployed on WebLogic Server 10.3.4.0 or later, an unsubscribe API extension is not yet available for subscriptions that use an unrestricted client ID. The workaround is to use administrative measures described in Managing Durable Subscriptions.

Managing Durable Subscriptions

A durable subscription that is no longer needed can continue to accumulate messages after its consumers stop. Such subscriptions can consume quota and storage and may eventually prevent further sends. Confirm that a subscription is no longer required before deleting it and its retained messages.

For example, the unsubscribe call fails when there are active subscribers on the subscription and the unsubscribe call does not reach subscriptions on inactive (shutdown) members. When this happens, the subscription is left on the member where the call failed until it is manually removed by an administrator or the call is repeated.

To help handle these situations, administrators have the following options to monitor and manage durable subscriptions:

  • There is one instance of the JMSDurableSubscriberRuntimeMBean for each durable subscription. Administrators can monitor a topic or UDT using the WebLogic Remote Console or by using WLST command line or scripts. See Monitor Servers in Oracle WebLogic Remote Console Online Help.

  • Use LastMessagesReceivedTime together with consumer activity and message counts to investigate a potentially abandoned subscription. LastMessagesReceivedTime reports the last successful delivery to a subscriber; if no message has been delivered since the subscription was created or recovered, it reports that creation or recovery time. MessagesCurrentCount describes messages still available, while MessagesPendingCount describes uncommitted or unacknowledged messages. An old timestamp or an inactive consumer alone does not prove that a durable subscription is abandoned. Confirm application ownership and the disposition of retained messages before removing the subscription.

Naming Conventions for JMSDurableSubscriberRuntimeMBean

If a durable subscription is created using the subscription key, <MyClientID, MySubscriptionName>, then the name of the associated JMSDurableSubscriberRuntimeMBean is either:

  • MyClientID_MySubscriptionName when the client ID Policy is RESTRICTED. Where MyClientID is the Client ID for this subscription, and MySubscriptionName is the name of the subscription.

  • MyClientID_MySubscriptionName@topicName@JMSServerName when the client ID Policy is UNRESTRICTED. Where MyClientID is the client ID for this subscription, MySubscriptionName is the name of the subscription., topicName is the name of a standalone topic or a member of a UDT, and JMSServerName is the name of the JMS Server that the topic or member is deployed on.

Design Strategies When Using Topics

Learn about the Topic-based design strategies that can be used to develop high availability applications.

One-Copy-Per-Instance Design Strategy

With the one-copy-per-instance design strategy, each application instance has its own subscription and receives its own copy of messages published to the topic, subject to normal JMS delivery and message-selection rules. This strategy is appropriate when every application instance needs to process messages independently.

This pattern is usually best implemented using an MDB configured for the intended strategy. The MDB container sets up the required policies and subscriptions across the cluster. See Best Practices for Distributed Topics.

For applications that do not use MDBs, see Shared Subscriptions and Client ID Policy and Advanced Programming with Distributed Destinations Using the JMS Destination Availability Helper API for information about subscription sharing and distributed-topic member availability.

One-Copy-Per-Application Design Strategy

With the one-copy-per-application design strategy, application instances share subscriptions so that each message published to the topic is delivered to the application as a whole rather than separately to every instance, subject to normal JMS delivery and message-selection rules. Messages can be distributed among the instances, allowing them to share the work of processing messages.

This pattern is usually best implemented using an MDB configured for the intended strategy. The MDB container sets up the required policies and subscriptions across the cluster. See Best Practices for Distributed Topics.

For applications that do not use MDBs, see Shared Subscriptions and Client ID Policy and Advanced Programming with Distributed Destinations Using the JMS Destination Availability Helper API for information about subscription sharing and distributed-topic member availability.

Considerations When Using Standard Shared Subscriptions

The named shared-subscription APIs introduced in JMS 2.0 remain part of Jakarta Messaging. The following WebLogic restrictions apply to distributed topics.

Observe these rules when using the standard shared-subscription APIs:

  • For a shared non-durable subscription on a logical distributed topic or an individual distributed-topic member, use Unrestricted Client ID Policy when the connection has no client ID.

  • Do not pass a logical distributed-topic object directly to Session.createSharedDurableConsumer(). Create durable subscriptions on individual members, or use MDBs or the documented WebLogic helpers to manage member subscriptions.

  • For a shared durable subscription on an individual distributed-topic member, use Unrestricted Client ID Policy when the connection has no client ID.

Note:

For Unrestricted client ID policy, use WLSession.unsubscribe(Topic topic, String name). Supply the physical topic or distributed-topic member first, followed by the subscription name. A logical distributed-topic object or a null topic is not valid for this call.

Replacing a Replicated Distributed Topic

Learn about replacing a Replicated Distributed Topic (RDT) with a standalone topic or PDT.

Reasons for Replacing a Replicated Distributed Topic

It is sometimes necessary to replace an existing Replicated Distributed Topic (RDT) with a Partitioned Distributed Topic (PDT) or standalone topic because RDTs are not supported in the following scopes:

An attempt to configure or deploy an RDT in any of these scopes generates a configuration validation error.

It also can be helpful to replace an RDT with a PDT or standalone topic because these options handle the same use cases, yet are simpler and tend to perform better. RDTs implicitly run transactional internal forwarders to duplicate messages between their members, and these forwarders have a relatively high overhead.

Important Prerequisites Before Replacing an RDT

Plan the replacement so that required messages on the existing replicated distributed topic are processed before it is retired. Coordinate producers and consumers, complete outstanding transactions, and identify every durable subscription that must be retained or recreated.

For a side-by-side replacement, create the new topic with a different name and configure its required subscriptions and consumers before directing production traffic to it. Coordinate the cutover to avoid unintended loss or duplicate processing. After required messages on the old topic have been processed, close its consumers, remove only the obsolete durable subscriptions using the supported unsubscribe or administrative operations, and retire the old topic configuration.

Do not delete persistent-store files or database tables as a shortcut for removing old topic subscriptions. A store can contain other required resources. See Managing Durable Subscriptions.

Replacing an RDT with a Standalone Topic

Replacing an RDT with a singleton standalone topic instead of a PDT can be the simplest option, but sacrifices scalability and some HA. Ensuring that a cluster-hosted standalone topic is migratable, can mitigate HA concerns. See What About Failover? in Administering JMS Resources for Oracle WebLogic Server.

Note:

Standalone topics that are hosted on cluster-targeted JMS servers or a dynamic cluster can only be hosted on a JMS server that references a store configured with a singleton distribution policy. They also require configuring cluster leasing on a cluster where database leasing is recommended over consensus leasing. See Simplified JMS Cluster and High Availability Configuration in Administering JMS Resources for Oracle WebLogic Server.

Replacing an RDT with a PDT

To configure a PDT, set the forwarding-policy attribute of a uniform distributed topic to Partitioned instead of Replicated. A PDT does not duplicate a message produced to one of its members to every other member, so this different semantic may require further changes:

  • For MDB consumers of a PDT, configure the activation-config property topicMessagesDistributionMode as One-Copy-Per-Server or One-Copy-Per-Application, according to the intended delivery pattern. Compatibility mode is not supported for PDTs. See Configuring and Deploying MDBs Using JMS Topics and Topic Deployment Scenarios in Developing Message-Driven Beans for Oracle WebLogic Server.

  • If you are using the SOA JMS adapter to consume from a PDT, then no change is needed. It defaults to the MDB equivalent of one-copy-per-app when consuming from a PDT. See Accessing Distributed Destinations (Queues and Topics) on the WebLogic Server JMS in Understanding Technology Adapters.

  • For OSA JMS Adapter consumers, check the adapter release’s supported PDT configuration and ensure that its subscriptions cover the required PDT members before replacing the topic.

  • If you have jakarta.jms topic consumers that are not an MDB, SOA JMS Adapter, or OSA JMS Adapter, then application code changes may be needed. For example, the application may need to be changed so that it consumes from subscriptions on each and every PDT member instead of from a single subscription. This is because a PDT does not replicate each sent message to each of its members. For more information and a discussion of helper APIs in this area, see Developing Advanced Pub/Sub Applications, Advanced Programming with Distributed Destinations and Using the JMS Destination Availability Helper API.

Best Practices for Distributed Topics

Follow Oracle’s recommendations when designing new applications using distributed topics.