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

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

I'm attempting to update my proposal to deal with the following:
 * Comments from "Alfred" sent to the authors listed on the
Internet-Draft (I-D)
 * Subject of the action item - removing context, and addressing replyTo
in the context of queue & topic variants

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 three variants, "jndi",
"queue", and "topic".

-----------------
Section 3.3

Change:
    jms-uri = "jms:" jms-variant ":" jms-dest
        [ "?" param  *( [ "&" param ] ) ]

.. to ..

    jms-uri = "jms:" jms-variant ":" jms-dest
        [ "?" param *( "&" param ) ]

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

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

.. to ..

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

~~~~
Also change the example:

   jms:context:SomeContextName?timeToLive=1000

.. to ..

   jms:queue:ExampleQueueName?timeToLive=1000

----------------
Section 4.1.3.

Change:

and corresponds to the JMS message header
   "JMSPriority".

.. to ..

and corresponds to the JMS message header field
   "JMSPriority".

----------------
Section 4.3 & 4.3.1 --> REPLACE with the following:

4.3. 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.3.1. Treatment of replyToName parameter

When used with the "queue" and "topic" variants, the replyToName
parameter, specified in section 4.1.4, always refers to a name of a JMS
queue to look up via the Session.createQueue() method.  For either
variant, if a JMS topic is instead required as a response destination, a
JMS URI can emply the "topicReplyName" parameter.  This parameter
defines a name to look up with the Session.createTopic() method.

A JMS URI MUST NOT specify both a "topicReplyName" and a "replyToName"
paramter.

4.3.2. 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.3.3.  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.

----------------
Section 8.4

Replace the second paragraph of this section with:

The "queue" and "topic" variants are subject to the same concerns as the
JNDI variant.  In addition, because the destination names are vendor
defined, URIs employing these two variants may employ special characters
that significantly change the meaning of the URI.  It is possible that
the introduction of a single character - difficult for a human to notice
- might dramatically change the intended meaning of a URI.  In
situations where this might be an issue, users of this URI should
strongly consider the "jndi" variant instead.

----------------
Section 9

Change:
   o  URI scheme name: "jms" is requested
   o  Status: Permanent is requested

.. to ..
   o  URI scheme name: jms
   o  Status: Permanent

as well as changing:

   o  References See References section

.. to ..

   o  References: See References section

Received on Tuesday, 30 September 2008 04:55:48 UTC