I've now made the javadoc changes suggested in this issue. You can read a summary in the JIRA issue:
http://java.net/jira/browse/JMS_SPEC-31
or look at the javadocs directly:
http://jms-spec.java.net/2.0-SNAPSHOT/apidocs/javax/jms/Session.html#createQueue%28java.lang.String%29
http://jms-spec.java.net/2.0-SNAPSHOT/apidocs/javax/jms/Session.html#createTopic%28java.lang.String%29
http://jms-spec.java.net/2.0-SNAPSHOT/apidocs/javax/jms/JMSContext.html#createQueue(java.lang.String)
http://jms-spec.java.net/2.0-SNAPSHOT/apidocs/javax/jms/JMSContext.html#createTopic(java.lang.String)
(Never to late to comment)
Nigel
On 19/04/2012 15:10, Nigel Deakin wrote:
> No-one has objected to this so far. Any more comments?
>
> (Reminder: This is just a change to the javadocs for session.createQueue and createTopic. See the bottom of this email
> for the current and proposed versions)
>
> Thanks,
>
> Nigel
>
> On 10/04/2012 17:51, Nigel Deakin wrote:
>> I'd like to raise this issue which was brought up last July by Clebert
>> http://java.net/jira/browse/JMS_SPEC-31
>> Change javadoc on session.createQueue and createTopic to make clearer the provider may create a physical destination.
>>
>> Clebert proposed: "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."
>>
>> Since we're discussing the creation of queue and topic objects I think now is a good time to review this proposal.
>>
>> I'd like to start by asking Clebert whether he really means to propose that this method may create a physical queue or
>> topic, by contacting the server.
>>
>> 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".
>>
>> I'd like to explore what you had in mind, Clebert, to see whether you were proposing something different. Were you
>> thinking of existing HornetQ behaviour or were you thinking of this as a possibole new feature?
>>
>> Here is the existing javadoc description for Session.createQueue. (The javadoc for createTopic is similar).
>>
>> /** 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. Here is a possible attempt at
>> making it easier to understand:
>>
>> /**
>> * Creates a Queue 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 Queue
>> * 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
>> * typically an administrative task performed by an administrator, though
>> * some providers may create them automatically when needed. In all cases
>> * the way that a physical queue is created is provider-specific.
>> *
>> * @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;
>>
>> Any comments?
>>
>> Nigel
>>