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
>