Using durable subscriptions

You use durable subscriptions for publish/subscribe messaging. A durable subscription can be used to preserve messages published on a topic while the subscriber is not active.

About this task

If there is no active subscriber for a durable subscription, JMS retains the subscription messages until they are received by the subscriber, or until they expire, or until the durable subscription is deleted. This enables subscriber applications to operate disconnected from the JMS provider for periods of time, and then reconnect to the provider and process messages that were published during their absence.

Each JMS durable subscription is identified by a subscription name (subName), which is defined when the durable subscription is created. A JMS connection also has an associated client identifier (clientID), which is used to associate a connection and its objects with the list of messages (on the durable subscription) that is maintained by the JMS provider for the client. The subName assigned to a durable subscription must be unique within a given client ID.

If an application needs to receive messages published on a topic while the subscriber is inactive, it uses a durable subscriber.

In normal operation there can be at most one active (connected) subscriber for a durable subscription at a time. However, when running inside an application server it is possible to clone the application server for failover and load-balancing purposes. In this case, a cloned durable subscription can have multiple simultaneous consumers.

The following operations for durable subscriptions are in addition to the usual JMS operations, such as to first look up a connection factory and a JMS destination, and to create a connection and session.

The following are the main operations for using durable subscriptions:

Creating a new durable subscription
Reconnecting to an existing durable subscription
Unsubscribing (deleting) a durable subscription

Procedure

Define the Durable Subscription Home
This property must be set on the JMS connection factory if durable subscriptions are to be created using connections created from this connection factory. The value is the name of the messaging engine where all durable subscriptions accessed through this connection are managed.
You can also set the Durable Subscription Home on the JMS topic destination, which enables a single connection to access durable subscriptions on more than one messaging engine.

To be able to create durable subscriptions, the property on the connection factory must not be null (the default). Setting a value of null or empty string on the property of a destination indicates that the value specified on the connection factory should be inherited.
Creating a new durable subscription
A durable TopicSubscriber can be created by a Session or by a TopicSession.
Having performed the normal setup, an application can create a durable subscriber to a destination. To do this, the client program creates a durable TopicSubscriber, by using session.createDurableSubscriber. The name subName is used as an identifier of the durable subscription.
```
session.createDurableSubscriber( Topic topic, 
        java.lang.String subName, 
        java.lang.String messageSelector, 
        boolean noLocal);
```
Alternatively, you can use the two-argument form of this operation, which takes only a topic and name (subName) as parameters. This alternative form invokes the four-argument operation with null as the messageSelector and false as the noLocal parameters.
```
session.createDurableSubscriber( Topic topic, java.lang.String subName);
```
A JMS durable subscription is created with a unique identifier of the form clientID+"##"+subName. The characters ## should not be used in the clientID or subName if the JMS connection is to use a durable subscription.
Handling exceptions. The following JMS exceptions can be thrown for the reasons listed in the exception messages:
- InvalidDestination - The name of this durable subscription (clientID+"##"+subName) clashes with an existing destination.
- IllegalState - The method was invoked on a closed connection.
- IllegalState - This destination is not accepting consumers. This probably means that there is already an active subscriber for this durable subscription.
- InvalidDestination - The mediation named in the parameters cannot be found.
- InvalidDestination - The destination cannot be found.
- JMSSecurity - The user does not have authorization to perform this operation.
- JMSException - Errors occurred in the MsgStore, Comms or Core layers.
Reconnecting to an existing durable subscription
To reconnect to a topic that has an existing durable subscription, the subscriber application calls session.CreateDurableSubscriber again, using the same parameters that it used to originally create the durable subscription. However, consider the following important restrictions:
- The subscriber must be attached to the same connection.
- The destination and subscription name must be the same as in the original method call.
- If a message selector was specified, it must be the same as in the original method call.
By calling createDurableSubscriber again, the subscriber application reconnects to the topic, and receives any messages that arrived while the subscriber was disconnected.
Unsubscribing (deleting) a durable subscription
To unsubscribe (delete) a durable subscription to a topic, the subscriber application calls session.unsubscribe(java.lang.String name).
Do not call the unsubscribe method to delete a durable subscription if there is a TopicConsumer currently consuming messages from the topic.