The following sections describe the concepts and functionality of distributed destinations necessary to design higher availability applications:
A distributed destination is a set of destinations (queues or topics) that are accessible as a single, logical destination to a client. A distributed destination has the following characteristics:
Applications that use distributed destinations are more highly available than applications that use simple destinations because WebLogic JMS provides load balancing and failover for member destinations of a distributed destination within a cluster. Once properly configured, your producers and consumers are able to send and receive messages through the distributed destination. WebLogic JMS then balances the messaging load across all available members of the distributed destination. When one member becomes unavailable due a server failure, traffic is then redirected toward other available destination members in the set. For more information on how destination members are load balanced, see “Configuring Distributed Destination Resources”.
Distributed destinations are created by the system administrator using the Administration Console. For more information, see “Configuring Distributed Destination Resources”.
WebLogic Server supports two types of distributed destinations:
In a uniform distributed destination (UDD), each of the member destinations has a consistent configuration of all distributed destination parameters, particularly in regards to weighting, security, persistence, paging, and quotas.
Oracle recommends using UDDs because you no longer need to create or designate destination members, but instead rely on WebLogic Server to uniformly create the necessary members on the JMS servers to which a UDD is targeted. This feature of UDDs provides dynamic updating of a UDD when a new member is added or a member is removed.
For example, if UDD is targeted to a cluster, there is a UDD member on every JMS server in the cluster. If a new JMS server is added, a new UDD member is dynamically added to the UDD. Likewise, if a JMS server is removed, the corresponding UDD member is removed from the UDD. This allows UDDs to provide higher availability by eliminating bottlenecks caused by configuration errors. For more information, see “Configuring Distributed Destination Resources”.
In a weighted distributed destination, the member destinations do not have a consistent configuration of all distributed destination parameters, particularly in regards to weighting, security, persistence, paging, and quotas.
Oracle recommends converting weighted distributed destinations to UDDs because of the administrative inflexibility when creating members that are intended to carry extra message load or have extra capacity (more weight). Lack of a consistent member configuration can lead to unforeseen administrative and application problems because the weighted distributed destination can not be deployed consistently across a cluster.
For more information, see “Configuring Distributed Destination Resources”.
A distributed destination is a set of physical JMS destination members (queues or topics) that is accessed through a single JNDI name. As such, a distributed destination can be looked up using JNDI. It implements the javax.jms.Destination interface, and can be used to create producers, consumers, and browsers.
Because a distributed destination can be served by multiple WebLogic Servers within a cluster, when creating a reference to a distributed destination by using one of the createQueue()
or createTopic()
methods, the name supplied is simply the name of the JMSDistributedQueueMBean
or JMSDistributedTopicMBean
preceded by the parent module name, separated by an exclamation point (!). No JMS server name or separating forward slash (/
) is required.
For example, the following code illustrates how to look up a distributed destination topic:
topic = myTopicSession.createTopic("myModuel!myDistributedTopic");
Note: | When calling the createQueue() or createTopic() methods, any string containing a forward slash (/ ), is assumed to be the name of a distributed destination member—not the name of a distributed destination. If no such destination member exists, then the call will fail with an InvalidDestinationException . See Deploying Message-Driven Beans on a Distributed Topic. |
A distributed queue is a set of physical JMS queue members. As such, a distributed queue can be used to create a QueueSender
, QueueReceiver
, and a QueueBrowser
. The fact that a distributed queue represents multiple physical queues is mostly transparent to your application.
The queue members can be located anywhere, but must all be served by JMS servers in a single server cluster. When a message is sent to a distributed queue, it is sent to exactly one of the physical queues in the set of members for the distributed queue. Once the message arrives at the queue member, it is available for receipt by consumers of that queue member only. ‘
This section provides information on using distributed queues:
Queue members can forward messages to other queue members by configuring the Forward Delay attribute in the Administration Console, which is disabled by default. This attribute defines the amount of time, in seconds, that a distributed queue member with messages, but which has no consumers, will wait before forwarding its messages to other queue members that do have consumers.
After creating a queue sender, if the queue supplied at creation time was a distributed queue, then each time a message is produced using the sender a decision is made as to which queue member will receive the message. Each message is sent to a single physical queue member.
The message is not replicated in any way. As such, the message is only available from the queue member where it was sent. If that physical queue becomes unavailable before a given message is received, then the message is unavailable until that queue member comes back online.
It is not enough to send a message to a distributed queue and expect the message to be received by a queue receiver of that distributed queue. Since the message is sent to only one physical queue member, there must be a queue receiver receiving or listening on that queue member.
Note: | For information on the load-balancing heuristics for distributed queues with zero consumers, see “Configuring Distributed Destination Resources”. |
When creating a queue receiver, if the supplied queue is a distributed queue, then a single physical queue member is chosen for the receiver at creation time. The created QueueReceiver
is pinned to that queue member until the queue receiver loses its access to the queue member. At that point, the consumer will receive a JMSException
, as follows:
Upon receiving such an exception, an application can close its queue receiver and recreate it. If any other queue members are available within the distributed queue, then the creation will succeed and the new queue receiver will be pinned to one of those queue members. If no other queue member is available, then the application won’t be able to recreate the queue receiver and will have to try again later.
Note: | For information on the load-balancing heuristics for distributed queues with zero consumers, see “Configuring Distributed Destination Resources”. |
When creating a queue browser, if the supplied queue is a distributed queue, then a single physical queue member is chosen for the browser at creation time. The created queue browser is pinned to that queue member until the receiver loses its access to the queue member. At that point, any calls to the queue browser will receive a JMSException
. Any calls to the enumeration will return a NoSuchElementException
.
Note: | The queue browser can only browse the queue member that it is pinned to. Even though a distributed queue was specified at creation time, the queue browser cannot see or browse messages for the other queue members in the distributed destination. |
A distributed topic is a set of physical JMS topic members. As such, a distributed topic can be used to create a TopicPublisher
and TopicSubscriber
. The fact that a distributed topic represents multiple physical topics is mostly transparent to the application.
Note: | Durable subscribers (DurableTopicSubscriber ) cannot be created for distributed topics. However, you can still create a durable subscription on distributed topic member and the other topic members will forward the messages to the topic member that has the durable subscription. |
The topic members can be located anywhere but must all be served either by a single WebLogic Server or any number of servers in a cluster. When a message is sent to a distributed topic, it is sent to all of the topic members in the distributed topic set. This allows all subscribers to the distributed topic to receive messages published for the distributed topic.
A message published directly to a topic member of a distributed destination (that is, the publisher did not specify the distributed destination) is also forwarded to all the members of that distributed topic. This includes subscribers that originally subscribed to the distributed topic, and which happened to be assigned to that particular topic member. In other words, publishing a message to a specific distributed topic member automatically forwards it to all the other distributed topic members, just as publishing a message to a distributed topic automatically forwards it to all of its distributed topic members. For more information about looking up specific distributed destination members, see Accessing Distributed Destination Members.
This section provides information on using distributed queues:
When creating a topic publisher, if the supplied destination is a distributed destination, then any messages sent to that distributed destination are sent to all available topic members for that distributed topic, as follows:
Note: | Every effort is made to first forward the message to distributed members that utilize a persistent store. However, if none of the distributed members utilize a store, then the message is still sent to one of the members according to the selected load-balancing algorithm, as described in “Configuring Distributed Destination Resources”. |
JMSException
when it tries to send a message.When creating a topic subscriber, if the supplied topic is a distributed topic, then the topic subscriber receives messages published to that distributed topic. If one or more of the topic members for the distributed topic are not reachable by a topic subscriber, then depending on whether the messages are persistent or non-persistent the following occurs:
Note: | If a JMS store is configured for a JMS server that is hosting a distributed topic member, then all the Distributed Topic System Subscribers associated with that member destination are treated as durable subscriptions, even when a topic member does not have a JMS store explicitly configured. As such, the saving of all the messages sent to these distributed topic subscribers in memory can result in unexpected memory and disk consumption. Therefore, a recommended best design practice when deploying distributed destination is to consistently configure all member destinations: either with a JMS store for durable messages, or without a JMS store for non-durable messages. For example, if you want all of your distributed topic subscribers to be non-durable, but some member destinations implicitly have a JMS store configured because their associated JMS server uses a JMS store, then you need to explicitly set the StoreEnabled attribute to False for each member destination to override the JMS server setting. |
Ultimately, a topic subscriber is pinned to a physical topic member. If that topic member becomes unavailable, then the topic subscriber will receive a JMSException
, as follows:
Upon receiving such an exception, an application can close its topic subscriber and recreate it. If any other topic member is available within the distributed topic, then the creation should be successful and the new topic subscriber will be pinned to one of those topic members. If no other topic member is available, then the application will not be able to recreate the topic subscriber and will have to try again later.
When an MDB is deployed on a distributed topic and is targeted to a WebLogic Server instance in a cluster that is hosting two members of the distributed topic on a JMS server, the MDB gets deployed on both the members of the distributed topic. This occurs because MDBs are pinned to a distributed topic member’s destination name.
Therefore, you will receive [number of messages sent] * [number of distributed topic members] more messages per MDB, depending on how may distributed topic members are deployed on a WebLogic Server instance. For example, if a JMS server contains two distributed topic members, then two MDBs are deployed, one for each member, so you will receive twice as many messages.
The following sections provide information on how to directly access a member a of a distributed destination.
Note: | Applications defeat load balancing by directly accessing the individual physical destinations. For more information, see “Configuring Distributed Destination Resources”. |
In order to access a uniform destination member within a uniform distributed destination, you must look up the JNDI name or the member name using the weblogic.jms.extensions.JMSModuleHelper class
uddMemberName and
uddMemberJNDIName APIs. You can then use the JNDI name or supply the module name followed by an exclamation point (!), the JMS server name followed by a forward slash (/
), and the member name.
For example, the following code illustrates how to look up a particular member of a uniform distributed queue (myQueue
), on a JMS server (myServer
) in module (myModule
):
queue = myQueueSession.createQueue("
myModule!myServer/myQueue
");
Note: | When calling the createQueue() or createTopic() methods, any string containing a forward slash (/ ), is assumed to be the name of a distributed destination member—not a distributed destination. If no such destination member exists, then the call will fail with an InvalidDestinationException . |
In order to access a weighted destination member within a distributed destination, you must look up the destination member using the configured JNDI name, or supply the module name followed by an exclamation point (!), the JMS server name followed by a forward slash (/
), and the JMSQueueMBean
or JMSTopicMBean
configuration MBean name.
For example, the following code illustrates how to look up a particular member of a weighted distributed queue (myQueue
), on a JMS server (myServer
) in module (myModule
):
queue = myQueueSession.createQueue("
myModule!myServer/myQueue
");
Note: | When calling the createQueue() or createTopic() methods, any string containing a forward slash (/ ), is assumed to be the name of a distributed destination member—not a distributed destination. If no such destination member exists, then the call will fail with an InvalidDestinationException . |
Note: | If the distributed queue member on which a queue producer is created should fail, yet the WebLogic Server instance where the producer’s JMS connection resides is still running, the producer remains alive and WebLogic JMS will fail it over to another distributed queue member, irrespective of whether the Load Balancing option is enabled. For example, a WebLogic cluster contains WLSServer1, WLSServer2, and WLSServer3 and you are connected to WLServer2. If server WLSServer 2 fails, WebLogic JMS fail the producer over to one of the remaining cluster members. For more information, see “Configuring Distributed Destinations”. |
A simple way to failover a client connected to a failed distributed destination is to write reconnect logic in the client code to connect to the distributed destination after catching onException
.
A message-driven bean (MDB) acts as a JMS message listener, which is similar to an event listener except that it receives messages instead of events. For more information on MDBs, see:
The following sections provide common use case scenarios when using distributed destinations:
To maximize message production, Oracle recommends that each member of a distributed destination be associated with a producer and a consumer. The following diagram demonstrates how to efficiently provide maximum message production and high availability using a UDD without using load balancing:
In this situation, UDD1 is a uniform distributed destination composed of two physical members: D1 and D2. Each physical destination has a producer/consumer pair and the effective path for a message follows the solid line from the producer through the destination member to the consumer. If you are using ordering, you should have a producer for each expected Unit-of-Order. See Using Unit-of-Order with Distributed Destinations in Programming WebLogic JMS.
This section provides information on how to maximize message availability.
Ideally, its best to pair a producer with a consumer but it is not always practical. The rate that messages are consumed is the limiting factor that determines the message throughput of your application. You can increase the availability of consumers by using load balancing between member destinations. In this situation, consumers are not paired with a producer as the UDD load balances an incoming message to the next available consumer using the assigned load balancing algorithm.
Note: | Some combinations of Unit-of-Order features can result in the starvation of competing Unit-of-Order message streams, including the under utilization of resources when the number of consumers exceed the number of in-flight messages with different Unit-of-Order names. You will need to test your applications under maximum loads to optimize your system's performance and eliminate conditions that under utilize resources. |
When using a distributed topic, every member destination will forward its messages to every other member of the distributed topic.
In this situation, UDD1 is a uniform distributed destination composed of two physical members: D1 and D2. Each physical destination has a producer/consumer pair. Each consumer receives messages sent by Producer 1 and Producer 2.
In this situation, a producer is sending messages to one member of a UDD but there is no consumer available to get the message. This typically happens as a producer sends a message to one of the destinations (D1) and a consumer is listening for messages on another destination (D2).
UDD1 is a uniform distributed destination composed of two physical members: D1 and D2. D1 has a producer and D2 has a consumer. Avoid this configuration by using producer/consumer pairs or by configuring forwarding on the destination.