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