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

Somehow, I managed to escape without a specific action item to update
the URI spec, although I know I agreed to it.

I have attached the HTML form of the edits, and will be submitting the
text and XML forms on Monday, barring any comments, or any hold-up with
Roland's attempts to contact Oracle.

Before I submit, depending on what happens with Roland's efforts, we
clearly have to update the list at the beginning that identifies BEA, as
appropriate.

-Eric.

Eric Johnson wrote:
> 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
>
>