Proposed resolution to Action-33: revision to URI scheme for queue and topic schemes

As per my action item #33:
   http://www.w3.org/2002/ws/soapjms/tracker/actions/33

Based on the email to the list:
http://lists.w3.org/Archives/Public/public-soap-jms/2008Sep/0017.html

I propose the edits to the current draft of the URI scheme:
http://www.ietf.org/internet-drafts/draft-merrick-jms-uri-03.txt

Section 1, last paragraph, revise to:

While the "jndi" variant provides compatibility, vendors may define 
additional variants.  This specification defines four variants, "jndi", 
"context", "queue", and "topic".

-----------------
Section 4, 2nd paragraph, change:

The two recognized variants (jms-variant above) are "jndi", and "context".

-->

The four recognized variants (jms-variant above) are "jndi", "context", 
"queue", and "topic".

-----------------
Section 4.4 --> renumber to section 4.5

----------------
Insert new section 4.4 (and 4.4.1, 4.4.2)

4.4. Vendor Destination Names - Variants "queue" And "topic"

The JMS Session object provides a means to directly access queues and 
topics.  Specifically, it has the methods Session.createQueue(String 
name), and Session.createTopic(String name).  These methods can be used 
to "create" the Java representation of an existing JMS Topic or Queue.

Since the Session interface requires external knowledge about whether a 
given name relates to a queue or topic, rather than introducing one new 
variant, this section defines two variants.  A JMS URI can indicate 
which of these methods to use by specifying the appropriate variant - 
either "queue" or "topic". For example:
   jms:queue:ExampleQueueName

to identify a JMS queue Destination, and
   jms:topic:ExampleTopicName

to identify a JMS topic Destination.

JMS only specifies one way to obtain the names used by these APIs.  With 
a JMS Queue or Topic available, an implementation can call 
Queue.getQueueName(), or Topic.getTopicName(), respectively, both of 
which return a String object.  To create a correct corresponding URI, 
the resulting string must use standard URI escape mechanisms so that the 
resulting characters conform to "jms-dest".

4.4.1. Obtaining a Session via JNDI

Using the Session.createQueue(), and Session.createTopic() methods 
assumes that a client program has already obtained a Session object. 
Where does that Session object come from - how does a client get it?

One way to get a Session object is to simply revert to using JNDI.  That 
is, if a Session is not available to client from some other context, the 
"queue" and "topic" variants MAY reuse the URL parameters specified in 
section 4.2.1, JNDI Parameters.  Via JNDI, those parameters will 
identify a ConnectionFactory, which can then be used to obtain a Session 
object.

Combining the "queue" and "topic" variants with JNDI lookup for an 
implementation of ConnectionFactory raises an important consideration 
for JMS URI clients.  Once clients are using JNDI for one part of 
discovering a Destination, they almost certainly could use a 
vendor-neutral JNDI lookup for a Destination object, rather than a 
vendor-specific means.  As a result, clients should carefully consider 
alternatives to this approach.

4.4.2  Limitations of "queue" and "topic"

The JMS specification clearly identifies the two methods on the Session 
interface as returning vendor specific names for destinations. 
Consequently, users of the JMS URI scheme should carefully consider when 
these two variants should be applied.  If users plan switching between 
JMS vendors, they should also plan on regenerating resources that 
contain URIs in this vendor specific form.

A JMS vendor may provide alternate ways to obtain the names that can be 
passed to Session.createQueue(), and Session.createTopic().  When using 
those alternate means, users of this URI specification should verify 
that the obtained names work as expected in all circumstances.

Received on Tuesday, 23 September 2008 00:56:44 UTC