jms-spec
  1. jms-spec
  2. JMS_SPEC-51

New methods to replace Session.createDurableSubscriber() and return a MessageConsumer

    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

      In JMS 1.1 the following two methods on Session return a TopicSubscriber.

      TopicSubscriber createDurableSubscriber(Topic topic)

      TopicSubscriber createDurableSubscriber(Topic topic, java.lang.String name, java.lang.String messageSelector, boolean noLocal)

      These are the only "domain-independent" methods in the whole JMS 1.1 API which depend on a "domain-specific" interface. This dependency prevents the "domain-specific" interfaces being removed from JMS as proposed in JMS_SPEC-47.

      It is therefore proposed to modify these methods to return a MessageConsumer. Since this is a supertype of TopicSubscriber it should not break existing applications.

        Issue Links

          Activity

          Hide
          Nigel Deakin added a comment - - edited

          It has been pointed out that the above proposal would require existing applications would need to cast the MessageConsumer that is returned down to a TopicSubscriber.

          This suggests that we need to provide new versions of this method which return a MessageConsumer. This would allow us to mark the old methods as deprecated and propose them for removal.

          We can't simply add new methods with the same name which return a MessageConsumer since the compiler would consider these duplicate methods.

          Two options have been proposed:

          Option 1

          We could define new methods named createConsumer:

          MessageConsumer createConsumer(Topic topic, java.lang.String name)

          MessageConsumer createConsumer(Topic topic, java.lang.String name, java.lang.String messageSelector, boolean noLocal)

          However there's potential confusion between the first of those methods and the existing method to create an ordinary consumer with a message selector:

          MessageConsumer createConsumer(Destination destination, java.lang.String messageSelector)

          The compiler would allow it, but if the user tried to create a durable subscription using a variable which was really a Topic but which was declared as Destination then the wrong method would be called.

          It could also be argued that removing the word "durable" from the method name would be confusing for users.

          We could either live with these drawbacks, or we could use:

          Option 2

          We could define new methods named createDurableConsumer:

          MessageConsumer createDurableConsumer(Topic topic, java.lang.String name)

          MessageConsumer createDurableConsumer(Topic topic, java.lang.String name, java.lang.String messageSelector, boolean noLocal)

          Show
          Nigel Deakin added a comment - - edited It has been pointed out that the above proposal would require existing applications would need to cast the MessageConsumer that is returned down to a TopicSubscriber . This suggests that we need to provide new versions of this method which return a MessageConsumer . This would allow us to mark the old methods as deprecated and propose them for removal. We can't simply add new methods with the same name which return a MessageConsumer since the compiler would consider these duplicate methods. Two options have been proposed: Option 1 We could define new methods named createConsumer : MessageConsumer createConsumer(Topic topic, java.lang.String name) MessageConsumer createConsumer(Topic topic, java.lang.String name, java.lang.String messageSelector, boolean noLocal) However there's potential confusion between the first of those methods and the existing method to create an ordinary consumer with a message selector: MessageConsumer createConsumer(Destination destination, java.lang.String messageSelector) The compiler would allow it, but if the user tried to create a durable subscription using a variable which was really a Topic but which was declared as Destination then the wrong method would be called. It could also be argued that removing the word "durable" from the method name would be confusing for users. We could either live with these drawbacks, or we could use: Option 2 We could define new methods named createDurableConsumer : MessageConsumer createDurableConsumer(Topic topic, java.lang.String name) MessageConsumer createDurableConsumer(Topic topic, java.lang.String name, java.lang.String messageSelector, boolean noLocal)
          Hide
          Nigel Deakin added a comment -

          Following a discussion within the JSR 343 expert group I've selected option 2 above.

          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 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 two 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;   
          
          Show
          Nigel Deakin added a comment - Following a discussion within the JSR 343 expert group I've selected option 2 above. 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 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 two 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;
          Hide
          Nigel Deakin added a comment - - edited

          I've changed the summary line for this issue from
          Change Session.createDurableSubscriber() to return a MessageConsumer
          to
          New methods to replace Session.createDurableSubscriber() and return a MessageConsumer.

          This reflects the decision not to change the existing methods (to preserve backwards compatibility) but to add new methods.

          Show
          Nigel Deakin added a comment - - edited I've changed the summary line for this issue from Change Session.createDurableSubscriber() to return a MessageConsumer to New methods to replace Session.createDurableSubscriber() and return a MessageConsumer . This reflects the decision not to change the existing methods (to preserve backwards compatibility) but to add new methods.

            People

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

              Dates

              • Created:
                Updated:
                Resolved: