jms-spec
  1. jms-spec
  2. JMS_SPEC-31

change javadoc on session.createQueue and createTopic to make clearer the provider may create a physical destination

    Details

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

      Description

      Most users have been asking us to add a flag to just create the server's side queue with some default values.

      If I add the flag the configuration won't be spec compliant in some people's interpretation as the javadoc says the createQueue / createTopic is not for the physical creation itself.

      I'm not sure what to make on the javadoc, the current version says this:

      "Note that this method is not for creating the physical queue. The physical creation of queues is an administrative task and is not to be initiated by the JMS API. The one exception is the creation of temporary queues, which is accomplished with the createTemporaryQueue method."

      My proposal is to change it to something permissive where the provider may or not create the physical queue. That would be a design choice.

        Activity

        Hide
        clebertsuconic added a comment -

        This is a simple change. We should simply remove the text about physical creation of the queues. I believe most experts will agree this is already currently allowed on the spec.

        Show
        clebertsuconic added a comment - This is a simple change. We should simply remove the text about physical creation of the queues. I believe most experts will agree this is already currently allowed on the spec.
        Hide
        rdohna added a comment -

        +1

        But I think that it must be configurable to either throw an exception or to create a new destination. If you have hundreds of queues, I'd rather have an exception than go search around who created this strange new queue. So IMHO at least this behaviour should be required by the spec. Automatically generating destinations should be mentioned as one legal alternative, when so configured... even if it's the default.

        Show
        rdohna added a comment - +1 But I think that it must be configurable to either throw an exception or to create a new destination. If you have hundreds of queues, I'd rather have an exception than go search around who created this strange new queue. So IMHO at least this behaviour should be required by the spec. Automatically generating destinations should be mentioned as one legal alternative, when so configured... even if it's the default.
        Hide
        Nigel Deakin added a comment -

        This issue will be considered by the expert group for inclusion in the JMS 2.0 public draft. Tagging accordingly.

        Show
        Nigel Deakin added a comment - This issue will be considered by the expert group for inclusion in the JMS 2.0 public draft. Tagging accordingly.
        Hide
        Nigel Deakin added a comment - - edited

        My feeling is that we should keep this method as it was originally intended, which is as a way to convert a provider-specific queue name to a javax.jms.Queue object which can be used in the JMS API, and not as a mechanism for creating the physical queue in the server.

        However I do think we need to clarify that this method is NOT expected to throw a JMSException if the physical queue does not exist. I think this is pretty clear already but should be clarified: the 1.1 javadoc refers to "if the session fails to create a queue". Given that the javadoc states that this method does not create the physical queue then this error can only mean "fails to create a Queue object".

        I know that some JMS providers (Apache ActiveMQ and Oracle GlassFish MQ) allow the queue to be created automatically in the server when the first message is sent to it (or perhaps when a producer or consumer is created). However they don't create the queue when createQueue is called, and do don't violate the statement "this method is not for creating the physical queue".

        Here is the existing javadoc description for the createQueue method on Session:

              /** Creates a queue identity given a <CODE>Queue</CODE> name.
              *
              * <P>This facility is provided for the rare cases where clients need to
              * dynamically manipulate queue identity. It allows the creation of a
              * queue identity with a provider-specific name. Clients that depend
              * on this ability are not portable.
              *
              * <P>Note that this method is not for creating the physical queue.
              * The physical creation of queues is an administrative task and is not
              * to be initiated by the JMS API. The one exception is the
              * creation of temporary queues, which is accomplished with the
              * <CODE>createTemporaryQueue</CODE> method.
              *
              * @param queueName the name of this <CODE>Queue</CODE>
              *
              * @return a <CODE>Queue</CODE> with the given name
              *
              * @exception JMSException if the session fails to create a queue
              *                         due to some internal error.
              * @since 1.1
              */
        
            Queue createQueue(String queueName) throws JMSException;
        

        I think this is basically correct, though the phrase "queue identity" is a bit mysterious. I've now reworded it as follows:

        	/**
        	 * Creates a <code>Queue</code> object which encapsulates a specified
        	 * provider-specific queue name.
        	 * <p>
        	 * The use of provider-specific queue names in an application may render the
        	 * application non-portable. Portable applications are recommended to not
        	 * use this method but instead look up an administratively-defined
        	 * <code>Queue</code> object using JNDI.
        	 * <p>
        	 * Note that this method simply creates an object that encapsulates the name
        	 * of a queue. It does not create the physical queue in the JMS provider.
        	 * JMS does not provide a method to create the physical queue, since this
        	 * would be specific to a given JMS provider. Creating a physical queue is
        	 * provider-specific and is typically an administrative task performed by an
        	 * administrator, though some providers may create them automatically when
        	 * needed. The one exception to this is the creation of a temporary queue,
        	 * which is done using the <code>createTemporaryQueue</code> method.
        	 * 
        	 * @param queueName
        	 *            A provider-specific queue name
        	 * @return a Queue object which encapsulates the specified name
        	 * 
        	 * @throws JMSException
        	 *             if a Queue object cannot be created due to some internal
        	 *             error
        	 */
        	Queue createQueue(String queueName) throws JMSException;
        

        I've made this change to the createQueue method on Session and, mutatis mutandis, to the createTopic method on Session and the createQueue and createTopic methods on JMSContext.

        The new javadocs may be browsed here

        I've also updated the change list in the draft spec to refer to this change. See section B.5.18 "Clarification: Session methods createQueue and createTopic".

        The draft spec may be downloaded here (you need to log in to java.net first)

        Show
        Nigel Deakin added a comment - - edited My feeling is that we should keep this method as it was originally intended, which is as a way to convert a provider-specific queue name to a javax.jms.Queue object which can be used in the JMS API, and not as a mechanism for creating the physical queue in the server. However I do think we need to clarify that this method is NOT expected to throw a JMSException if the physical queue does not exist. I think this is pretty clear already but should be clarified: the 1.1 javadoc refers to "if the session fails to create a queue". Given that the javadoc states that this method does not create the physical queue then this error can only mean "fails to create a Queue object". I know that some JMS providers (Apache ActiveMQ and Oracle GlassFish MQ) allow the queue to be created automatically in the server when the first message is sent to it (or perhaps when a producer or consumer is created). However they don't create the queue when createQueue is called, and do don't violate the statement "this method is not for creating the physical queue". Here is the existing javadoc description for the createQueue method on Session : /** Creates a queue identity given a <CODE>Queue</CODE> name. * * <P>This facility is provided for the rare cases where clients need to * dynamically manipulate queue identity. It allows the creation of a * queue identity with a provider-specific name. Clients that depend * on this ability are not portable. * * <P>Note that this method is not for creating the physical queue. * The physical creation of queues is an administrative task and is not * to be initiated by the JMS API. The one exception is the * creation of temporary queues, which is accomplished with the * <CODE>createTemporaryQueue</CODE> method. * * @param queueName the name of this <CODE>Queue</CODE> * * @return a <CODE>Queue</CODE> with the given name * * @exception JMSException if the session fails to create a queue * due to some internal error. * @since 1.1 */ Queue createQueue(String queueName) throws JMSException; I think this is basically correct, though the phrase "queue identity" is a bit mysterious. I've now reworded it as follows: /** * Creates a <code>Queue</code> object which encapsulates a specified * provider-specific queue name. * <p> * The use of provider-specific queue names in an application may render the * application non-portable. Portable applications are recommended to not * use this method but instead look up an administratively-defined * <code>Queue</code> object using JNDI. * <p> * Note that this method simply creates an object that encapsulates the name * of a queue. It does not create the physical queue in the JMS provider. * JMS does not provide a method to create the physical queue, since this * would be specific to a given JMS provider. Creating a physical queue is * provider-specific and is typically an administrative task performed by an * administrator, though some providers may create them automatically when * needed. The one exception to this is the creation of a temporary queue, * which is done using the <code>createTemporaryQueue</code> method. * * @param queueName * A provider-specific queue name * @return a Queue object which encapsulates the specified name * * @throws JMSException * if a Queue object cannot be created due to some internal * error */ Queue createQueue(String queueName) throws JMSException; I've made this change to the createQueue method on Session and, mutatis mutandis , to the createTopic method on Session and the createQueue and createTopic methods on JMSContext . The new javadocs may be browsed here I've also updated the change list in the draft spec to refer to this change. See section B.5.18 "Clarification: Session methods createQueue and createTopic". The draft spec may be downloaded here (you need to log in to java.net first)
        Hide
        Nigel Deakin added a comment -

        For the final wording see the API docs to accompany the JMS 2.0 public draft.

        Show
        Nigel Deakin added a comment - For the final wording see the API docs to accompany the JMS 2.0 public draft.

          People

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

            Dates

            • Created:
              Updated:
              Resolved: