On 21/09/2011 11:09, Nigel Deakin wrote:
>
> This is my "second" proposal:
>
> MessageConsumer createDurableConsumer(Topic topic, java.lang.String name)
>
> MessageConsumer createDurableConsumer(Topic topic, java.lang.String name, java.lang.String messageSelector, boolean
> noLocal)
>
I've now updated the javadocs and the draft spec accordingly (these changes are additive, so those docs include other
changes).
The updated Javadocs are here:
http://java.net/projects/jms-spec/sources/repository/content/jms2.0/target/jms-2.0-javadoc.jar
(Two createDurableConsumer methods have been added to Session. See below for javadocs. The existing
createDurableSubscriber methods remain, though I have added a javadoc comment saying that these are now deprecated).
The updated draft spec is here:
http://java.net/projects/jms-spec/sources/repository/content/jms2.0/specification/word/JMS20.pdf
(all changes are highlighted clearly with changebars, but the only place I've changed is 6.11.1 "Durable
TopicSubscriber" and 11.5.9 "createDurableConsumer" which is the change log).
Here are the new methods:
/** Creates a durable subscription with the specified name on the
* specified topic, and creates a <code>MessageConsumer</code>
* on that durable subscription.
* <P>
* If the durable subscription already exists then this method
* creates a <code>MessageConsumer</code> on the existing durable
* subscription.
* <p>
* A durable subscription is used by a client which needs to receive
* all the messages published on a topic, including the ones published
* when there is no <code>MessageConsumer</code> or <code>TopicSubscriber</code> associated with it.
* The JMS provider retains a record of this durable subscription
* and ensures that all messages from the topic's publishers are retained
* until they are delivered to, and acknowledged by,
* a <code>MessageConsumer</code> or <code>TopicSubscriber</code> on this durable subscription
* or until they have expired.
* <p>
* A durable subscription will continue to accumulate messages
* until it is deleted using the <code>unsubscribe</code> method.
* <p>
* A durable subscription which has a <code>MessageConsumer</code> or <code>TopicSubscriber</code>
* associated with it is described as being active.
* A durable subscription which has no <code>MessageConsumer</code> or <code>TopicSubscriber</code>
* associated with it is described as being inactive.
* <p>
* Only one session at a time can have a
* <code>MessageConsumer</code> or <code>TopicSubscriber</code> for a particular durable subscription.
* <p>
* 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>MessageConsumer</code> or <code>TopicSubscriber</code>
* on that durable subscription must use the same client identifier.
* <p>
* A client can change an existing durable subscription by calling
* <code>createDurableConsumer</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.
*
* @param topic the non-temporary <CODE>Topic</CODE> to subscribe to
* @param name the name used to identify this subscription
*
* @exception JMSException if the session fails to create the durable subscription
* and <code>MessageConsumer</code> due to some internal error.
* @exception InvalidDestinationException if an invalid topic is specified.
*
* @since 2.0
*/
MessageConsumer createDurableConsumer(Topic topic, String name) throws JMSException;
/** Creates a durable subscription with the specified name on the
* specified topic, and creates a <code>MessageConsumer</code>
* on that durable subscription, specifying a message
* selector and whether messages published by its
* own connection should be delivered to it.
* <P>
* If the durable subscription already exists then this method
* creates a <code>MessageConsumer</code> on the existing durable
* subscription.
* <p>
* A durable subscription is used by a client which needs to receive
* all the messages published on a topic, including the ones published
* when there is no <code>MessageConsumer</code> or <code>TopicSubscriber</code> associated with it.
* The JMS provider retains a record of this durable subscription
* and ensures that all messages from the topic's publishers are retained
* until they are delivered to, and acknowledged by,
* a <code>MessageConsumer</code> or <code>TopicSubscriber</code> on this durable subscription
* or until they have expired.
* <p>
* A durable subscription will continue to accumulate messages
* until it is deleted using the <code>unsubscribe</code> method.
* <p>
* A durable subscription which has a <code>MessageConsumer</code> or <code>TopicSubscriber</code>
* associated with it is described as being active.
* A durable subscription which has no <code>MessageConsumer</code> or <code>TopicSubscriber</code>
* associated with it is described as being inactive.
* <p>
* Only one session at a time can have a
* <code>MessageConsumer</code> or <code>TopicSubscriber</code> for a particular durable subscription.
* <p>
* 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>MessageConsumer</code> or <code>TopicSubscriber</code>
* on that durable subscription must use the same client identifier.
* <p>
* A client can change an existing durable subscription by calling
* <code>createDurableConsumer</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.
*
* @param topic the non-temporary <CODE>Topic</CODE> to subscribe to
* @param name the name used to identify this subscription
* @param messageSelector only messages with properties matching the
* message selector expression are delivered. A value of null or
* an empty string indicates that there is no message selector
* for the message consumer.
* @param noLocal if set, inhibits the delivery of messages published
* by its own connection
*
* @exception JMSException if the session fails to create the durable subscription
* and <code>MessageConsumer</code> due to some internal error.
* @exception InvalidDestinationException if an invalid topic is specified.
* @exception InvalidSelectorException if the message selector is invalid.
*
* @since 2.0
*/
MessageConsumer createDurableConsumer(Topic topic, String name, String messageSelector, boolean noLocal) throws
JMSException;