Queue Forwarding QueueSenders QueueReceivers

Using Distributed Destinations 9-3

9.5 Using Distributed Destinations

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, at http:java.sun.comjavaee5docsapijavaxjmsDestination.html , and can be used to create producers, consumers, and browsers. For information on obtaining a reference to a distributed destination, see Section C, How to Lookup a Destination. ■ Section 9.5.1, Using Distributed Queues ■ Section 9.5.2, Using Replicated Distributed Topics ■ Section 9.5.3, Using Partitioned Distributed Topics

9.5.1 Using Distributed Queues

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: ■ Section 9.5.1.1, Queue Forwarding ■ Section 9.5.1.2, QueueSenders ■ Section 9.5.1.3, QueueReceivers ■ Section 9.5.1.4, QueueBrowsers

9.5.1.1 Queue Forwarding

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. By default, WebLogic Server resets the delivery count when forwarding between distributed queue members. See Reset Delivery Count On Forward.

9.5.1.2 QueueSenders

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. 9-4 Programming JMS for Oracle WebLogic Server 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.

9.5.1.3 QueueReceivers

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: ■ If the queue receiver is synchronous, then the exception is returned to the user directly. ■ If the queue receiver is asynchronous, then the exception is delivered inside of a ConsumerClosedException that is delivered to the ExceptionListener defined for the consumer session, if any. 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 wont be able to recreate the queue receiver and will have to try again later.

9.5.1.4 QueueBrowsers