http://java.net/jira/browse/JMS_SPEC-39
I've made some small additional changes to the javadoc comments for the following methods to clarify the case where the
durable subscription already exists. I have already reworded these comments as part of JMS_SPEC-39 and this is just a
small additional documentation improvement which is not intended to change the spec behaviour.
Here are the methods affected:
Session.createDurableSubscriber (2 methods)
Session.createDurableConsumer (2 methods, added for JMS_SPEC-51)
MessagingContext.createSyncDurableConsumer (2 methods)
MessagingContext.setMessageListener (only the 2 methods for durable subscriptions)
MessagingContext.setBatchMessageListener (only the 2 methods for durable subscriptions
Here's an example for Session.createDurableSubscriber:
This is the old comment:
* If the durable subscription already exists then this method
* creates a <code>TopicSubscriber</code> on the existing durable
* subscription.
This is the new comment:
* If a durable subscription already exists with the same name
* and client identifier (if set) and the same topic and message selector
* then this method creates a <code>TopicSubscriber</code> on the existing durable
* subscription.
Note that the javadoc comment for these methods already states the following:
* A durable subscription is identified by a name specified by the client
* and by the client identifier if set. If the client identifier was set
* when the durable subscription was first created then a client which
* subsequently wishes to create a <code>TopicSunscriber</code>
* on that durable subscription must use the same client identifier.
* <p>
* A client can change an existing durable subscription by calling
* <code>createDurableSubscriber</code>
* with the same name and client identifier (if used),
* and a new topic and/or message selector.
* Changing a durable subscriber is equivalent to
* unsubscribing (deleting) the old one and creating a new one.
The important point which I want readers to understand is that if you want to create a consumer on an existing durable
subscription you need to use the same subscriptionName and clientID (if set), and also the same topic and message selector.
(If you specify a different topic or message selector you will delete the old durable subscription and create a new one,
as it already says).
The updated Javadocs are here:
http://java.net/projects/jms-spec/sources/repository/content/jms2.0/target/jms-2.0-javadoc.jar