This topic describes things to consider when using 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.
If there is no active subscriber for a durable subscription, JMS
retains the subscription’s 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.
For information about durable subscriptions, see the JMS 1.1 Specification (for example, section
9.3.3 "Using Durable Subscriptions").
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
- 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, 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 JMSExceptions 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.