jms-spec
  1. jms-spec
  2. JMS_SPEC-39

Make clientId optional when creating a durable subscription

    Details

    • Type: Improvement Improvement
    • Status: Resolved
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 1.1
    • Fix Version/s: 2.0ED, 2.0
    • Labels:
      None

      Description

      (There was a change of mind on this issue. Initially this feature was added for both JMS 1.1 unshared subscriptions as well as JMS 2.0 shared subscriptions but we changed our mind and in the end it was added for JMS 2.0 shared subscriptions only. This note was added retrospectively to make this issue easier to understand when reading it.)

      This is a proposal to make clientId optional when creating a durable subscription

      In JMS 1.1, a durable subscription is defined by the combination of clientId and subscriptionName. Section 6.11.1 of the Specification states:

      Sessions with durable subscribers must always provide the same client
      identifier. In addition, each client must specify a name that uniquely identifies
      (within client identifier) each durable subscription it creates.

      Whilst it is clear that a durable subscription needs to have a name to allow it to be identified, it is less clear why it needs to be identified by clientId. This is the only place in the JMS API where a connection must have clientId set.

      This requirement to have clientId set causes complication for applications, especially in a Java EE application, where clientId must be set on the connection factory. This means that the connection factory can only be used to create a single instance, and if a connection pool is used it must be constrained to allow only a single instance.

      It is therefore proposed that the use of clientId be made optional when creating a durable subscription. In this case, the subscription will be defined by the name of the subscription alone.

      This change is not intended to change the existing restrictions stated in Section 6.11.1:

      Only one session at a time can have a TopicSubscriber for a particular durable subscription.

        Activity

        Hide
        timlfox added a comment -

        I don't understand how client id can be optional. The unique id of a durable subscription is effectively defined by a tuple (client_id, subscription_name).

        This means there can be many different durable subscriptions with the same value of subscription_name but different values of client_id.

        Client id normally maps to some kind of notion of user, so this allows each user to maintain their own namespace within which they don't have to worry about naming of durable subscriptions.

        Removing client id would mean there is effectively one "global" namespace of durable subscriptions. This is not desirable IMHO.

        Show
        timlfox added a comment - I don't understand how client id can be optional. The unique id of a durable subscription is effectively defined by a tuple (client_id, subscription_name). This means there can be many different durable subscriptions with the same value of subscription_name but different values of client_id. Client id normally maps to some kind of notion of user, so this allows each user to maintain their own namespace within which they don't have to worry about naming of durable subscriptions. Removing client id would mean there is effectively one "global" namespace of durable subscriptions. This is not desirable IMHO.
        Hide
        Nigel Deakin added a comment -

        If clientID was set then it would still be used (to maintain backwards compatibility). However this change would allow a durable subscription to be created for which its identifying "tuple" was (null,subscription_name).

        Show
        Nigel Deakin added a comment - If clientID was set then it would still be used (to maintain backwards compatibility). However this change would allow a durable subscription to be created for which its identifying "tuple" was (null,subscription_name).
        Hide
        Nigel Deakin added a comment - - edited

        The updated Javadocs are here:
        http://java.net/projects/jms-spec/sources/repository/content/jms2.0/target/jms-2.0-javadoc.jar

        The only changes are to comments, not to the API. The updated comments as follows:

        On the Session interface the javadocs for the two createDurableSubscriber methods and the unsubscribe method have been rewritten as follows:

            /** Creates a durable subscription with the specified name on the
             * specified topic, and creates a <code>TopicSubscriber</code>
             * on that durable subscription.
             * <P>
             * If the durable subscription already exists then this method
             * creates a <code>TopicSubscriber</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>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>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>TopicSubscriber</code>
             * associated with it is described as being active.
             * A durable subscription which has no <code>TopicSubscriber</code>
             * associated with it is described as being inactive.
             * <p>
             * Only one session at a time can have a
             * <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>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.
             *
             * @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 a subscriber
             * due to some internal error.
             * @exception InvalidDestinationException if an invalid topic is specified.
             *
             * @since 2.0
             */
            TopicSubscriber createDurableSubscriber(Topic topic, String name) throws JMSException;
        
            /** Creates a durable subscription with the specified name on the
             * specified topic, and creates a <code>TopicSubscriber</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>TopicSubscriber</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>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>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>TopicSubscriber</code>
             * associated with it is described as being active.
             * A durable subscription which has no <code>TopicSubscriber</code>
             * associated with it is described as being inactive.
             * <p>
             * Only one session at a time can have a
             * <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>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.
             *
             * @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 a subscriber
             * due to some internal error.
             * @exception InvalidDestinationException if an invalid topic is specified.
             * @exception InvalidSelectorException if the message selector is invalid.
             *
             * @since 2.0
             */
             TopicSubscriber createDurableSubscriber(Topic topic, String name, String messageSelector, boolean noLocal) throws JMSException;
        
            /** Unsubscribes a durable subscription that has been created by a client.
              *
              * <P>This method deletes the state being maintained on behalf of the
              * subscriber by its provider.
              * <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 created then a client which
              * subsequently wishes to use this method to
              * delete a durable subscription must use the same client identifier.
              *
              * <P>It is erroneous for a client to delete a durable subscription
              * while there is an active <CODE>MessageConsumer</CODE>
              * or <CODE>TopicSubscriber</CODE> for the
              * subscription, or while a consumed message is part of a pending
              * transaction or has not been acknowledged in the session.
              *
              * @param name the name used to identify this subscription
              *
              * @exception JMSException if the session fails to unsubscribe to the
              * durable subscription due to some internal error.
              * @exception InvalidDestinationException if an invalid subscription name
              * is specified.
              *
              * @since 1.1
              */
            void unsubscribe(String name) throws JMSException;
        
        Show
        Nigel Deakin added a comment - - edited The updated Javadocs are here: http://java.net/projects/jms-spec/sources/repository/content/jms2.0/target/jms-2.0-javadoc.jar The only changes are to comments, not to the API. The updated comments as follows: On the Session interface the javadocs for the two createDurableSubscriber methods and the unsubscribe method have been rewritten as follows: /** Creates a durable subscription with the specified name on the * specified topic, and creates a <code>TopicSubscriber</code> * on that durable subscription. * <P> * If the durable subscription already exists then this method * creates a <code>TopicSubscriber</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>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>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>TopicSubscriber</code> * associated with it is described as being active. * A durable subscription which has no <code>TopicSubscriber</code> * associated with it is described as being inactive. * <p> * Only one session at a time can have a * <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>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. * * @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 a subscriber * due to some internal error. * @exception InvalidDestinationException if an invalid topic is specified. * * @since 2.0 */ TopicSubscriber createDurableSubscriber(Topic topic, String name) throws JMSException; /** Creates a durable subscription with the specified name on the * specified topic, and creates a <code>TopicSubscriber</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>TopicSubscriber</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>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>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>TopicSubscriber</code> * associated with it is described as being active. * A durable subscription which has no <code>TopicSubscriber</code> * associated with it is described as being inactive. * <p> * Only one session at a time can have a * <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>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. * * @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 a subscriber * due to some internal error. * @exception InvalidDestinationException if an invalid topic is specified. * @exception InvalidSelectorException if the message selector is invalid. * * @since 2.0 */ TopicSubscriber createDurableSubscriber(Topic topic, String name, String messageSelector, boolean noLocal) throws JMSException; /** Unsubscribes a durable subscription that has been created by a client. * * <P>This method deletes the state being maintained on behalf of the * subscriber by its provider. * <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 created then a client which * subsequently wishes to use this method to * delete a durable subscription must use the same client identifier. * * <P>It is erroneous for a client to delete a durable subscription * while there is an active <CODE>MessageConsumer</CODE> * or <CODE>TopicSubscriber</CODE> for the * subscription, or while a consumed message is part of a pending * transaction or has not been acknowledged in the session. * * @param name the name used to identify this subscription * * @exception JMSException if the session fails to unsubscribe to the * durable subscription due to some internal error. * @exception InvalidDestinationException if an invalid subscription name * is specified. * * @since 1.1 */ void unsubscribe(String name) throws JMSException;
        Hide
        Nigel Deakin added a comment - - edited

        On the proposed MessagingContext interface the javadocs for the two createSyncDurableSubscriber methods, the two setMessageListener methods used to create durable subscriptions, the two setBatchMessageListener methods used to create durable subscriptions and the unsubscribe method have been rewritten as follows:

            /** Creates a durable subscription with the specified name on the
             * specified topic, and creates a <code>SyncMessageConsumer</code>
             * on that durable subscription.
             * <P>
             * If the durable subscription already exists then this method
             * creates a <code>SyncMessageConsumer</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 active consumer 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 consumer 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 consumer may be created on a durable subscription using the
             * <code>createSyncDurableSubscriber</code> methods on <code>MessagingContext</code>,
             * the appropriate <code>setMessageListener</code> methods on <code>MessagingContext</code>
             * or the <code>createDurableSubscriber</code> methods on <code>Session</code> or <code>TopicSession</code>
             * A durable subscription which has a consumer
             * associated with it is described as being active.
             * A durable subscription which has no consumer
             * associated with it is described as being inactive.
             * <p>
             * Only one session at a time can have a
             * active consumer on 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>SyncMessageConsumer</code>
             * on that durable subscription must use the same client identifier.
             * <p>
             * A client can change an existing durable subscription by calling
             * <code>createSyncDurableSubscriber</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 JMSRuntimeException if the session fails to create a subscriber
             * due to some internal error.
             * @exception InvalidDestinationRuntimeException if an invalid topic is specified.
             *
             */
            SyncMessageConsumer createSyncDurableSubscriber(Topic topic, String name);
        
            /** Creates a durable subscription with the specified name on the
             * specified topic, and creates a <code>SyncMessageConsumer</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>SyncMessageConsumer</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 active consumer 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 consumer 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 consumer may be created on a durable subscription using the
             * <code>createSyncDurableSubscriber</code> methods on <code>MessagingContext</code>,
             * the appropriate <code>setMessageListener</code> methods on <code>MessagingContext</code>
             * or the <code>createDurableSubscriber</code> methods on <code>Session</code> or <code>TopicSession</code>
             * A durable subscription which has a consumer
             * associated with it is described as being active.
             * A durable subscription which has no consumer
             * associated with it is described as being inactive.
             * <p>
             * Only one session at a time can have a
             * active consumer on 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>SyncMessageConsumer</code>
             * on that durable subscription must use the same client identifier.
             * <p>
             * A client can change an existing durable subscription by calling
             * <code>createSyncDurableSubscriber</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 JMSRuntimeException if the session fails to create a subscriber
             * due to some internal error.
             * @exception InvalidDestinationRuntimeException if an invalid topic is specified.
             * @exception InvalidSelectorRuntimeException if the message selector is invalid.
             *
             */
            SyncMessageConsumer createSyncDurableSubscriber(Topic topic, String name, String messageSelector, boolean noLocal);
        
            /**
             * Creates a durable subscription with the specified name on the specified topic,
             * and creates a consumer on that durable subscription
             * that will deliver messages to the specified <code>MessageListener</code>.
             * <p>
             * If the durable subscription already exists then this method creates a consumer on the existing durable subscription
             * that will deliver messages to the specified <code>MessageListener</code>.
             * <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 active consumer 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 consumer 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 consumer may be created on a durable subscription using the
             * <code>createSyncDurableSubscriber</code> methods on <code>MessagingContext</code>,
             * the appropriate <code>setMessageListener</code> methods on <code>MessagingContext</code>
             * or the <code>createDurableSubscriber</code> methods on <code>Session</code> or <code>TopicSession</code>
             * A durable subscription which has a consumer
             * associated with it is described as being active.
             * A durable subscription which has no consumer
             * associated with it is described as being inactive.
             * <p>
             * Only one session or messaging context at a time can have a
             * active consumer on 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 consumer
             * on that durable subscription must use the same client identifier.
             * <p>
             * A client can change an existing durable subscription by calling
             * this or any of the other methods listed above
             * 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.
             * <p>
             * If the specified listener is null then this method does nothing.
             *
             * @param topic - The topic from which messages are to be consumed
             * @param subscriptionName - The name used to identify the durable subscription
             * @param listener - The listener to which the messages are to be delivered
             * @throws JMSRuntimeException - If the operation fails due to some internal error.
             * @throws InvalidDestinationRuntimeException - If an invalid topic is specified.
             */
        void setMessageListener (Topic topic, String subscriptionName, MessageListener listener);
        
            /**
             * Creates a durable subscription with the specified name on the specified topic,
             * and creates a consumer on that durable subscription
             * that will deliver messages to the specified <code>MessageListener</code>,
             * 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 consumer on the existing durable subscription
             * that will deliver messages to the specified <code>MessageListener</code>.
             * <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 active consumer 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 consumer 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 consumer may be created on a durable subscription using the
             * <code>createSyncDurableSubscriber</code> methods on <code>MessagingContext</code>,
             * the appropriate <code>setMessageListener</code> methods on <code>MessagingContext</code>
             * or the <code>createDurableSubscriber</code> methods on <code>Session</code> or <code>TopicSession</code>
             * A durable subscription which has a consumer
             * associated with it is described as being active.
             * A durable subscription which has no consumer
             * associated with it is described as being inactive.
             * <p>
             * Only one session or messaging context at a time can have a
             * active consumer on 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 consumer
             * on that durable subscription must use the same client identifier.
             * <p>
             * A client can change an existing durable subscription by calling
             * this or any of the other methods listed above
             * 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.
             * <p>
             * If the specified listener is null then this method does nothing.
             *
             * @param topic - The topic from which messages are to be consumed
             * @param subscriptionName - The name used to identify the durable 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 true, inhibit* subsequently wishes to create a consumer
             * on that durable subscription must use the same client identifier.
             * <p>
             * A client can change an existing durable subscription by calling
             * this or any of the other methods listed above
             * 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.
             * <p>
             * If the specified listener is null then this method does nothing.
             *
             * @param topic - The topic from which messages are to be consumed
             * @param subscriptionName - The name used to identify the durable 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 true, inhibits the delivery of messages published by its own connection.
             * @param listener - The listener to which the messages are to be delivered
             * @throws JMSRuntimeException - If the operation fails due to some internal error.
             * @throws InvalidDestinationRuntimeException - If an invalid topic is specified.
             * @throws InvalidSelectorRuntimeException - If the message selector is invalid.
             */
            void setMessageListener(Topic topic, String subscriptionName, String messageSelector, boolean NoLocal, MessageListener listener);
        
           /**
             * Creates a durable subscription with the specified name on the specified topic,
             * and creates a consumer on that durable subscription
             * that will deliver messages in batches to the specified <code>BatchMessageListener</code>
             * with the specified maximum batch size and timeout.
             * <p>
             * If the durable subscription already exists then this method creates a consumer on the existing durable subscription
             * that will deliver messages to the specified <code>MessageListener</code>.
             * <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 active consumer 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 consumer 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 consumer may be created on a durable subscription using the
             * <code>createSyncDurableSubscriber</code> methods on <code>MessagingContext</code>,
             * the appropriate <code>setMessageListener</code> methods on <code>MessagingContext</code>
             * or the <code>createDurableSubscriber</code> methods on <code>Session</code> or <code>TopicSession</code>
             * A durable subscription which has a consumer
             * associated with it is described as being active.
             * A durable subscription which has no consumer
             * associated with it is described as being inactive.
             * <p>
             * Only one session or messaging context at a time can have a
             * active consumer on 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 consumer
             * on that durable subscription must use the same client identifier.
             * <p>
             * A client can change an existing durable subscription by calling
             * this or any of the other methods listed above
             * 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.
             * <p>
             * Messages will be delivered to the specified <code>BatchMessageListener</code>
             * in batches whose size is no greater than the specified maximum batch size.
             * The JMS provider may defer message
             * delivery until the specified batch timeout has expired in order to
             * assemble a batch of messages that is as large as possible but no greater
             * than the batch size.
             * <p>
             * If the specified listener is null then this method does nothing.
             *
             * @param topic - The topic from which messages are to be consumed
             * @param subscriptionName - The name used to identify the durable subscription
             * @param listener - The listener to which the messages are to be delivered
             * @param maxBatchSize - The maximum batch size that should be used. Must be greater than zero.
             * @param batchTimeout - The batch timeout in milliseconds. A value of zero means no
             * timeout is required The JMS provider may override the
             * specified timeout with a shorter value.
             * @throws JMSRuntimeException - If the operation fails due to some internal error.
             * @throws InvalidDestinationRuntimeException - If an invalid topic is specified.
             */
            void setBatchMessageListener(Topic topic, String subscriptionName, BatchMessageListener listener, int maxBatchSize, long batchTimeout);
        
            /**
             * Creates a durable subscription with the specified name on the specified topic,
             * using the specified message message selector,
             * and creates a consumer on that durable subscription
             * that will deliver messages in batches to the specified <code>BatchMessageListener</code>
             * with the specified maximum batch size and timeout.
             * This method can specify whether messages published by its own connection
             * should be delivered to the specified listener.
             * <p>
             * If the durable subscription already exists then this method creates a consumer on the existing durable subscription
             * that will deliver messages to the specified <code>MessageListener</code>.
             * <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 active consumer 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 consumer 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 consumer may be created on a durable subscription using the
             * <code>createSyncDurableSubscriber</code> methods on <code>MessagingContext</code>,
             * the appropriate <code>setMessageListener</code> methods on <code>MessagingContext</code>
             * or the <code>createDurableSubscriber</code> methods on <code>Session</code> or <code>TopicSession</code>
             * A durable subscription which has a consumer
             * associated with it is described as being active.
             * A durable subscription which has no consumer
             * associated with it is described as being inactive.
             * <p>
             * Only one session or messaging context at a time can have a
             * active consumer on 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 consumer
             * on that durable subscription must use the same client identifier.
             * <p>
             * A client can change an existing durable subscription by calling
             * this or any of the other methods listed above
             * 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.
             * <p>
             * Messages will be delivered to the specified <code>BatchMessageListener</code>
             * in batches whose size is no greater than the specified maximum batch size.
             * The JMS provider may defer message
             * delivery until the specified batch timeout has expired in order to
             * assemble a batch of messages that is as large as possible but no greater
             * than the batch size.
             * <p>
             * If the specified listener is null then this method does nothing.
             *
             * @param topic - The topic from which messages are to be consumed
             * @param subscriptionName - The name used to identify the durable 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 true, inhibits the delivery of messages published by its own connection.
             * @param listener - The listener to which the messages are to be delivered
             * @param maxBatchSize - The maximum batch size that should be used. Must be greater than zero.
             * @param batchTimeout - The batch timeout in milliseconds. A value of zero means no
             * timeout is required The JMS provider may override the
             * specified timeout with a shorter value.
             * @throws JMSRuntimeException - If the operation fails due to some internal error.
             * @throws InvalidDestinationRuntimeException - If an invalid topic is specified.
             * @throws InvalidSelectorRuntimeException - If the message selector is invalid.
             */
            void setBatchMessageListener(Topic topic, String subscriptionName, String messageSelector, boolean NoLocal,
        BatchMessageListener listener, int maxBatchSize, long batchTimeout);
        
            /** Unsubscribes a durable subscription that has been created by a client.
             *
             * <P>This method deletes the state being maintained on behalf of the
             * subscriber by its provider.
             * <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 created then a client which
             * subsequently wishes to use this method to
             * delete a durable subscription must use the same client identifier.
             *
             * <P>It is erroneous for a client to delete a durable subscription
             * while there is an active consumer on that subscription,
             * or while a consumed message is part of a pending
             * transaction or has not been acknowledged in the session.
             * <P>
             * If the active consumer is represented by a <CODE>SyncMessageConsumer</CODE> then calling
             * <CODE>close</CODE> on either that object or the <CODE>MessagingContext</CODE> used to create it
             * will render the consumer inactive and allow the subscription to be deleted.
             * <P>
             * If the active consumer was created by calling <code>setMessageListener</code> on the <CODE>MessagingContext</CODE>
             * then calling <CODE>close</CODE> on the <CODE>MessagingContext</CODE>
             * will render the consumer inactive and allow the subscription to be deleted.
             * <p>
             * If the active consumer is represented by a <code>MessageConsumer</code> or <code>TopicSubscriber</code> then calling
             * <code>close</code> on that object or on the <code>Session</code> or <code>Connection</code> used to create it
             * will render the consumer inactive and allow the subscription to be deleted.
             *
             * @param name the name used to identify this subscription
             *
             * @exception JMSRuntimeException if the session fails to unsubscribe to the
             * durable subscription due to some internal error.
             * @exception InvalidDestinationRuntimeException if an invalid subscription name
             * is specified.
             */
            void unsubscribe(String name);
        
        Show
        Nigel Deakin added a comment - - edited On the proposed MessagingContext interface the javadocs for the two createSyncDurableSubscriber methods, the two setMessageListener methods used to create durable subscriptions, the two setBatchMessageListener methods used to create durable subscriptions and the unsubscribe method have been rewritten as follows: /** Creates a durable subscription with the specified name on the * specified topic, and creates a <code>SyncMessageConsumer</code> * on that durable subscription. * <P> * If the durable subscription already exists then this method * creates a <code>SyncMessageConsumer</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 active consumer 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 consumer 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 consumer may be created on a durable subscription using the * <code>createSyncDurableSubscriber</code> methods on <code>MessagingContext</code>, * the appropriate <code>setMessageListener</code> methods on <code>MessagingContext</code> * or the <code>createDurableSubscriber</code> methods on <code>Session</code> or <code>TopicSession</code> * A durable subscription which has a consumer * associated with it is described as being active. * A durable subscription which has no consumer * associated with it is described as being inactive. * <p> * Only one session at a time can have a * active consumer on 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>SyncMessageConsumer</code> * on that durable subscription must use the same client identifier. * <p> * A client can change an existing durable subscription by calling * <code>createSyncDurableSubscriber</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 JMSRuntimeException if the session fails to create a subscriber * due to some internal error. * @exception InvalidDestinationRuntimeException if an invalid topic is specified. * */ SyncMessageConsumer createSyncDurableSubscriber(Topic topic, String name); /** Creates a durable subscription with the specified name on the * specified topic, and creates a <code>SyncMessageConsumer</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>SyncMessageConsumer</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 active consumer 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 consumer 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 consumer may be created on a durable subscription using the * <code>createSyncDurableSubscriber</code> methods on <code>MessagingContext</code>, * the appropriate <code>setMessageListener</code> methods on <code>MessagingContext</code> * or the <code>createDurableSubscriber</code> methods on <code>Session</code> or <code>TopicSession</code> * A durable subscription which has a consumer * associated with it is described as being active. * A durable subscription which has no consumer * associated with it is described as being inactive. * <p> * Only one session at a time can have a * active consumer on 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>SyncMessageConsumer</code> * on that durable subscription must use the same client identifier. * <p> * A client can change an existing durable subscription by calling * <code>createSyncDurableSubscriber</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 JMSRuntimeException if the session fails to create a subscriber * due to some internal error. * @exception InvalidDestinationRuntimeException if an invalid topic is specified. * @exception InvalidSelectorRuntimeException if the message selector is invalid. * */ SyncMessageConsumer createSyncDurableSubscriber(Topic topic, String name, String messageSelector, boolean noLocal); /** * Creates a durable subscription with the specified name on the specified topic, * and creates a consumer on that durable subscription * that will deliver messages to the specified <code>MessageListener</code>. * <p> * If the durable subscription already exists then this method creates a consumer on the existing durable subscription * that will deliver messages to the specified <code>MessageListener</code>. * <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 active consumer 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 consumer 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 consumer may be created on a durable subscription using the * <code>createSyncDurableSubscriber</code> methods on <code>MessagingContext</code>, * the appropriate <code>setMessageListener</code> methods on <code>MessagingContext</code> * or the <code>createDurableSubscriber</code> methods on <code>Session</code> or <code>TopicSession</code> * A durable subscription which has a consumer * associated with it is described as being active. * A durable subscription which has no consumer * associated with it is described as being inactive. * <p> * Only one session or messaging context at a time can have a * active consumer on 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 consumer * on that durable subscription must use the same client identifier. * <p> * A client can change an existing durable subscription by calling * this or any of the other methods listed above * 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. * <p> * If the specified listener is null then this method does nothing. * * @param topic - The topic from which messages are to be consumed * @param subscriptionName - The name used to identify the durable subscription * @param listener - The listener to which the messages are to be delivered * @throws JMSRuntimeException - If the operation fails due to some internal error. * @throws InvalidDestinationRuntimeException - If an invalid topic is specified. */ void setMessageListener (Topic topic, String subscriptionName, MessageListener listener); /** * Creates a durable subscription with the specified name on the specified topic, * and creates a consumer on that durable subscription * that will deliver messages to the specified <code>MessageListener</code>, * 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 consumer on the existing durable subscription * that will deliver messages to the specified <code>MessageListener</code>. * <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 active consumer 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 consumer 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 consumer may be created on a durable subscription using the * <code>createSyncDurableSubscriber</code> methods on <code>MessagingContext</code>, * the appropriate <code>setMessageListener</code> methods on <code>MessagingContext</code> * or the <code>createDurableSubscriber</code> methods on <code>Session</code> or <code>TopicSession</code> * A durable subscription which has a consumer * associated with it is described as being active. * A durable subscription which has no consumer * associated with it is described as being inactive. * <p> * Only one session or messaging context at a time can have a * active consumer on 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 consumer * on that durable subscription must use the same client identifier. * <p> * A client can change an existing durable subscription by calling * this or any of the other methods listed above * 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. * <p> * If the specified listener is null then this method does nothing. * * @param topic - The topic from which messages are to be consumed * @param subscriptionName - The name used to identify the durable 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 true, inhibit* subsequently wishes to create a consumer * on that durable subscription must use the same client identifier. * <p> * A client can change an existing durable subscription by calling * this or any of the other methods listed above * 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. * <p> * If the specified listener is null then this method does nothing. * * @param topic - The topic from which messages are to be consumed * @param subscriptionName - The name used to identify the durable 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 true, inhibits the delivery of messages published by its own connection. * @param listener - The listener to which the messages are to be delivered * @throws JMSRuntimeException - If the operation fails due to some internal error. * @throws InvalidDestinationRuntimeException - If an invalid topic is specified. * @throws InvalidSelectorRuntimeException - If the message selector is invalid. */ void setMessageListener(Topic topic, String subscriptionName, String messageSelector, boolean NoLocal, MessageListener listener); /** * Creates a durable subscription with the specified name on the specified topic, * and creates a consumer on that durable subscription * that will deliver messages in batches to the specified <code>BatchMessageListener</code> * with the specified maximum batch size and timeout. * <p> * If the durable subscription already exists then this method creates a consumer on the existing durable subscription * that will deliver messages to the specified <code>MessageListener</code>. * <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 active consumer 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 consumer 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 consumer may be created on a durable subscription using the * <code>createSyncDurableSubscriber</code> methods on <code>MessagingContext</code>, * the appropriate <code>setMessageListener</code> methods on <code>MessagingContext</code> * or the <code>createDurableSubscriber</code> methods on <code>Session</code> or <code>TopicSession</code> * A durable subscription which has a consumer * associated with it is described as being active. * A durable subscription which has no consumer * associated with it is described as being inactive. * <p> * Only one session or messaging context at a time can have a * active consumer on 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 consumer * on that durable subscription must use the same client identifier. * <p> * A client can change an existing durable subscription by calling * this or any of the other methods listed above * 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. * <p> * Messages will be delivered to the specified <code>BatchMessageListener</code> * in batches whose size is no greater than the specified maximum batch size. * The JMS provider may defer message * delivery until the specified batch timeout has expired in order to * assemble a batch of messages that is as large as possible but no greater * than the batch size. * <p> * If the specified listener is null then this method does nothing. * * @param topic - The topic from which messages are to be consumed * @param subscriptionName - The name used to identify the durable subscription * @param listener - The listener to which the messages are to be delivered * @param maxBatchSize - The maximum batch size that should be used. Must be greater than zero. * @param batchTimeout - The batch timeout in milliseconds. A value of zero means no * timeout is required The JMS provider may override the * specified timeout with a shorter value. * @throws JMSRuntimeException - If the operation fails due to some internal error. * @throws InvalidDestinationRuntimeException - If an invalid topic is specified. */ void setBatchMessageListener(Topic topic, String subscriptionName, BatchMessageListener listener, int maxBatchSize, long batchTimeout); /** * Creates a durable subscription with the specified name on the specified topic, * using the specified message message selector, * and creates a consumer on that durable subscription * that will deliver messages in batches to the specified <code>BatchMessageListener</code> * with the specified maximum batch size and timeout. * This method can specify whether messages published by its own connection * should be delivered to the specified listener. * <p> * If the durable subscription already exists then this method creates a consumer on the existing durable subscription * that will deliver messages to the specified <code>MessageListener</code>. * <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 active consumer 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 consumer 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 consumer may be created on a durable subscription using the * <code>createSyncDurableSubscriber</code> methods on <code>MessagingContext</code>, * the appropriate <code>setMessageListener</code> methods on <code>MessagingContext</code> * or the <code>createDurableSubscriber</code> methods on <code>Session</code> or <code>TopicSession</code> * A durable subscription which has a consumer * associated with it is described as being active. * A durable subscription which has no consumer * associated with it is described as being inactive. * <p> * Only one session or messaging context at a time can have a * active consumer on 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 consumer * on that durable subscription must use the same client identifier. * <p> * A client can change an existing durable subscription by calling * this or any of the other methods listed above * 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. * <p> * Messages will be delivered to the specified <code>BatchMessageListener</code> * in batches whose size is no greater than the specified maximum batch size. * The JMS provider may defer message * delivery until the specified batch timeout has expired in order to * assemble a batch of messages that is as large as possible but no greater * than the batch size. * <p> * If the specified listener is null then this method does nothing. * * @param topic - The topic from which messages are to be consumed * @param subscriptionName - The name used to identify the durable 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 true, inhibits the delivery of messages published by its own connection. * @param listener - The listener to which the messages are to be delivered * @param maxBatchSize - The maximum batch size that should be used. Must be greater than zero. * @param batchTimeout - The batch timeout in milliseconds. A value of zero means no * timeout is required The JMS provider may override the * specified timeout with a shorter value. * @throws JMSRuntimeException - If the operation fails due to some internal error. * @throws InvalidDestinationRuntimeException - If an invalid topic is specified. * @throws InvalidSelectorRuntimeException - If the message selector is invalid. */ void setBatchMessageListener(Topic topic, String subscriptionName, String messageSelector, boolean NoLocal, BatchMessageListener listener, int maxBatchSize, long batchTimeout); /** Unsubscribes a durable subscription that has been created by a client. * * <P>This method deletes the state being maintained on behalf of the * subscriber by its provider. * <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 created then a client which * subsequently wishes to use this method to * delete a durable subscription must use the same client identifier. * * <P>It is erroneous for a client to delete a durable subscription * while there is an active consumer on that subscription, * or while a consumed message is part of a pending * transaction or has not been acknowledged in the session. * <P> * If the active consumer is represented by a <CODE>SyncMessageConsumer</CODE> then calling * <CODE>close</CODE> on either that object or the <CODE>MessagingContext</CODE> used to create it * will render the consumer inactive and allow the subscription to be deleted. * <P> * If the active consumer was created by calling <code>setMessageListener</code> on the <CODE>MessagingContext</CODE> * then calling <CODE>close</CODE> on the <CODE>MessagingContext</CODE> * will render the consumer inactive and allow the subscription to be deleted. * <p> * If the active consumer is represented by a <code>MessageConsumer</code> or <code>TopicSubscriber</code> then calling * <code>close</code> on that object or on the <code>Session</code> or <code>Connection</code> used to create it * will render the consumer inactive and allow the subscription to be deleted. * * @param name the name used to identify this subscription * * @exception JMSRuntimeException if the session fails to unsubscribe to the * durable subscription due to some internal error. * @exception InvalidDestinationRuntimeException if an invalid subscription name * is specified. */ void unsubscribe(String name);
        Hide
        Nigel Deakin added a comment -

        The updated draft spec is here:
        http://java.net/projects/jms-spec/sources/repository/content/jms2.0/specification/word/JMS20.pdf
        All changes are hightlighted. The changes made for this issue are as follows:

        In JMS 2.0 it is no longer mandatory for the client identifier to be set when creating or activating a durable subscription. The following changes have been updated to reflect this change:

        Section 4.3.2 "Client Identifier" has been changed to state that its use in identifying a durable subscription is optional.

        Section 6.3 "Durable Subscription" has been amended by adding a cross-reference to Section 6.11.1 "Durable TopicSubscriber" at the end.

        Section 6.11.1 "Durable TopicSubscriber" has been completely rewritten. This section was essentially a copy of the javadoc comment on the createDurableSubscriber methods and since those javadoc comments have been rewritten to make them clearer this section has been rewritten as well.

        The only substantive change is to state that the use of client identifier in identifying a durable subscription is optional. Cross-references to Section 6.3 "Durable Subscription" and Section 4.3.2 "Client Identifier" have been added at the end.

        Section 11.5.7. Durable subscriptions has been added, which is a change log.

        Show
        Nigel Deakin added a comment - The updated draft spec is here: http://java.net/projects/jms-spec/sources/repository/content/jms2.0/specification/word/JMS20.pdf All changes are hightlighted. The changes made for this issue are as follows: In JMS 2.0 it is no longer mandatory for the client identifier to be set when creating or activating a durable subscription. The following changes have been updated to reflect this change: Section 4.3.2 "Client Identifier" has been changed to state that its use in identifying a durable subscription is optional. Section 6.3 "Durable Subscription" has been amended by adding a cross-reference to Section 6.11.1 "Durable TopicSubscriber" at the end. Section 6.11.1 "Durable TopicSubscriber" has been completely rewritten. This section was essentially a copy of the javadoc comment on the createDurableSubscriber methods and since those javadoc comments have been rewritten to make them clearer this section has been rewritten as well. The only substantive change is to state that the use of client identifier in identifying a durable subscription is optional. Cross-references to Section 6.3 "Durable Subscription" and Section 4.3.2 "Client Identifier" have been added at the end. Section 11.5.7. Durable subscriptions has been added, which is a change log.
        Hide
        Nigel Deakin added a comment -

        Additional changes have been made to the javadoc comments for the following methods to clarify the case where the durable subscription already exists:

        • 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 updated Javadocs are here:
        http://java.net/projects/jms-spec/sources/repository/content/jms2.0/target/jms-2.0-javadoc.jar

        Show
        Nigel Deakin added a comment - Additional changes have been made to the javadoc comments for the following methods to clarify the case where the durable subscription already exists: 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 updated Javadocs are here: http://java.net/projects/jms-spec/sources/repository/content/jms2.0/target/jms-2.0-javadoc.jar
        Hide
        Nigel Deakin added a comment -

        It has now been decided that changing the Session method createDurableSubscriber to make clientId optional for durable subscriptions breaks the http://java.net/projects/javaee-spec/pages/CompatibilityRequirements Backwards Compatibility Requirements for Java EE Specifications.

        It will therefore remain mandatory to set clientId when creating a non-shared durable subscription using the following existing or new methods:

        Methods on Session:

        • TopicSubscriber createDurableSubscriber(Topic topic, String name) (JMS 1.1)
        • TopicSubscriber createDurableSubscriber(Topic topic, String name, String messageSelector, boolean noLocal) (JMS 1.1)
        • MessageConsumer createDurableConsumer(Topic topic, String name) (JMS 2.0)
        • MessageConsumer createDurableConsumer(Topic topic, String name, String messageSelector, boolean noLocal) (JMS 2.0)

        Methods on JMSContext:

        • JMSConsumer createDurableConsumer(Topic topic, String name)
        • JMSConsumer createDurableConsumer(Topic topic, String name, String messageSelector, boolean noLocal)

        These methods:

        • Will only allow a single consumer on a durable subscription
        • clientId MUST be set

        However setting clientId will be optional when creating a shared durable subscriptions using any of the following new methods:

        Methods on Session:

        • MessageConsumer createSharedDurableConsumer(Topic topic, String name)
        • MessageConsumer createSharedDurableConsumer(Topic topic, String name, String messageSelector, boolean noLocal)

        Methods on JMSContext:

        • JMSConsumer createSharedDurableConsumer(Topic topic, String name)
        • JMSConsumer createSharedDurableConsumer(Topic topic, String name, String messageSelector, boolean noLocal)

        These methods:

        • Will allow multiple consumers on a durable subscription
        • clientId may or may not be set
        Show
        Nigel Deakin added a comment - It has now been decided that changing the Session method createDurableSubscriber to make clientId optional for durable subscriptions breaks the http://java.net/projects/javaee-spec/pages/CompatibilityRequirements Backwards Compatibility Requirements for Java EE Specifications . It will therefore remain mandatory to set clientId when creating a non-shared durable subscription using the following existing or new methods: Methods on Session : TopicSubscriber createDurableSubscriber(Topic topic, String name) (JMS 1.1) TopicSubscriber createDurableSubscriber(Topic topic, String name, String messageSelector, boolean noLocal) (JMS 1.1) MessageConsumer createDurableConsumer(Topic topic, String name ) (JMS 2.0) MessageConsumer createDurableConsumer(Topic topic, String name, String messageSelector, boolean noLocal) (JMS 2.0) Methods on JMSContext : JMSConsumer createDurableConsumer(Topic topic, String name) JMSConsumer createDurableConsumer(Topic topic, String name, String messageSelector, boolean noLocal) These methods: Will only allow a single consumer on a durable subscription clientId MUST be set However setting clientId will be optional when creating a shared durable subscriptions using any of the following new methods: Methods on Session : MessageConsumer createSharedDurableConsumer(Topic topic, String name) MessageConsumer createSharedDurableConsumer(Topic topic, String name, String messageSelector, boolean noLocal) Methods on JMSContext : JMSConsumer createSharedDurableConsumer(Topic topic, String name) JMSConsumer createSharedDurableConsumer(Topic topic, String name, String messageSelector, boolean noLocal) These methods: Will allow multiple consumers on a durable subscription clientId may or may not be set
        Hide
        Nigel Deakin added a comment -

        Marking this issue as "resolved", with a resolution of "Won't fix"

        Show
        Nigel Deakin added a comment - Marking this issue as "resolved", with a resolution of "Won't fix"

          People

          • Assignee:
            Nigel Deakin
            Reporter:
            Nigel Deakin
          • Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved: