Re: [apps-discuss] apps-team review of draft-merrick-jms-uri-10

[Eric Johnson <[e-mail]>]

Hi Tim,

Alexey Melnikov asked that I recreate the full email response that I 
managed to delete/fail to send the first time around.

In any case, just as an overview, this is the URL that manages to 
capture the changes mostly specific to your feedback:
http://tools.ietf.org/rfcdiff?difftype=--hwdiff&url2=draft-merrick-jms-uri-11.txt


On 12/16/10 4:01 PM, Tim Bray wrote:
> I have been selected as the Applications Area Review Team reviewer for
> this draft (for background on apps-review, please see
> http://www.apps.ietf.org/content/applications-area-review-team).
> Please resolve these comments along with any other Last Call comments
> you may receive. Please wait for direction from your document shepherd
> or AD before posting a new version of the draft.
>
> Document: draft-merrick-jms-uri-10
> Title: URI Scheme for Java(tm) Message Service 1.0
> Reviewer: Tim Bray
> Review Date: Dec 16, 2010
> Summary: The draft has some mechanical issues which are not
> show-stoppers. I have questions whether this ought to be an RFC since
> there seems very modest expectation of interoperability between
> implementations; why, then, an IETF RFC, which suggests that the
> resulting URIs should be useful for identification of resources on an
> internetworked scale.
> Major Issues:
>
> 1. the draft suggests that given a “jms:” URI, there is little
> expectation that, without checking on the value of the “variant” and
> for the presence of vendor-specific parameters, it can be used
> interoperably in more than one implementation. In which case, I have
> to wonder about the appropriateness of using a *Uniform* resource
> identifier for whatever purposes are contemplated for these things;
If nothing else, we're trying to bring uniformity to syntax and 
semantics for "jms" schemes that exist in the wild, and register 
*something*.
> no
> motivations or use-cases are provided.

Perhaps you missed the references in section 6? The draft itself cites 
two other standards efforts using the JMS URI - SOAP/JMS - where the 
"jms" URI scheme will be used in the same place an HTTP URI might 
appear, and the OASIS SCA Bindings TC, where the URI indicates the 
destination of an SCA reference using a JMS binding.

> The last paragraph of section 1 is troubling. For convenience, I quote:
> <<<<<
> As a consequence of building upon an API, rather than a protocol, the
> utility of a "jms" URI depends on the context in which it is used.
> That context includes agreement on the same JMS provider or underlying
> protocol, agreement on how to look up endpoints (JNDI), and when using
> serialized Java object messages, sufficiently similar Java Class
> environments that serialized objects can be appropriately read and
> written. Users of this scheme need to establish the necessary shared
> context parts as just enumerated - a context which can span the globe,
> or merely a small local network. With that shared context, this URI
> scheme enables endpoint identification in a uniform way, and the means
> to connect to those endpoints.
> Given this, what are the advantages of having a *Uniform* resource
> identifier, if there is not much expectation of uniformity in
> implementations?
Some answers:

    * One can deploy a "bridge" between two JMS providers, thus
      providing interoperability between two JMS implementation, such
      that one client is unaware that the other client is not using the
      same JMS provider.
    * Via the JCP, JMS cements an API.  We're looking to establish
      interoperability at the level above that API, not at the level of
      the implementation of that API. That the implementations are not
      the same underneath that API ought not prevent standards efforts
      on top of the API that has been cemented by the JCP.

We're stuck, in that our use-cases demand a URL (for example, in the 
place of HTTP scheme URIs in WSDL), but we're building upon an API 
rather than an actual protocol. In the end, we think it a better idea to 
register the scheme than not.

> 2. Section 3.3 says “ If users plan switching between JMS vendors,
> they might also need to plan on regenerating resources that contain
> URIs in this vendor specific form”; this sharpens my concerns about
> the lack of interoperability...
>
> I’m getting the impression, reading this, that “jms:jndi” is probably
> quite interoperable, but the variants are maybe a back-door for vendor
> abuse.

Originally, we wrote the spec to only accommodate the JNDI approach.  We 
eventually exposed three broad reasons for the variants:

    * The JMS API itself.  The original 1.0 spec of JMS had two ways of
      establishing Destination objects, neither of which used JNDI (our
      "topic" and "queue" variants). The 1.1 version of the spec
      introduced the JNDI approach, and that's the obviously preferred
      method.
    * Broadest possible compatibility with existing uses of "JMS" URI
      schemes. In the early days of JMS, vendors defined their own ways
      to establish JMS Destinations, and we want to make sure that the
      proposed URI encompasses those possibilities, so that clients of
      the JMS scheme can look at the variant and know unambiguously that
      theh *don't* understand, rather than attempting to work with a
      "jms" URI, not working, and not knowing why.
    * Future proofing. Some JMS messaging products are based on
      documented protocols. Should they establish a better way of
      identifying JMS Destinations, and write up a new variant for doing
      so, this enables accessing said destinations, without revisiting
      the JMS URI scheme.

None of the authors working on the scheme anticipate registering any new 
variants.

Originally, we did not want an IANA registry to allow for additional 
variants, but previous feedback pushed us in that direction.

> Minor Issues:
>
> 1. Section 1. Need references for terms like javax.jms.Destination for
> people who aren’t familiar with Java pathname voodoo.

I added [REF-JMS] here.

> 2. Section 4 para beginning “Each variant can have query
> parameters...” - did you consider separating the variant prefix from
> the rest of the parameter name with “.” or some other syntax marker? I
> note that you use “jndi-” for another class of parameter names below.

We considered a lot of options here. Realistically, I can probably come 
up with any sort of post-hoc rationalization. Using the "jndi" prefix 
for the "jndi" variant, without any such separator worked out naturally 
based on the initial proposals we started from, followed by introducing 
the variants.

> 3. Same paragraph. Should the variant be used as a prefix even if it’s
> a vendor-supplied one starting with “vnd.”? An example of this would
> be nice.
Excellent point.  I added an example of "vnd.example.exParameter."
> 4. 4.1.1 and so on, should the draft impose any constraints on the
> syntax of these parameter values? Perhaps they are inherited from the
> referenced sections in the JMS 1.1 spec? If so, please say so. Ah, I
> see that 4.1.3 does specify some syntax, albeit loosely; there are a
> lot of different syntaxes which may be used to specify “ number
> between 0 and 9, inclusive”. Are you OK with 0x3 or, for timeToLive,
> “1,500”?

4.1.1 - says "PERSISTENT" or "NON_PERSISTENT".

4.1.2 & 4.13 - now indicate an expectation of decimal syntax.

> 5. 4.2.1 Perhaps a note prior to launching into all the parameters on
> syntax constraints, with, I’m assuming, normative references into the
> JMS spec?

In section 4.2.1.1, I added a reference to the Java Language 
Specification.  Excellent catch.  Thank you.

> 6. 4.2.2 includes great gobs of Java code illustrating how to use such
> an endpoint. Does this not contradict with the assertion at the top of
> section 4 which says “ Operations available on JMS destinations are
> fully and normatively defined by the JMS specification and as such,
> are out of scope for this URI specification”?

I changed the title of the section to read "Example of," clarified that 
this was an example specifically using Java, and that one "might start" 
with the approach that follows.

> In any case, 4.2.2 needs a bit of preparatory language explaining what
> it is. Is it normative behavior for implementations? Is it there for
> illustrative purposes? Is it required to use Java, or could I code
> something equivalent in C# or Ruby? A few paragraphs in there’s a
> passing reference to “the following (non-normative) code...”

I think I addressed that with the additions I noted just above.

> 7. 4.3.1, see comments on 4.2.2 above. Is this description of
> programming practice normative, illustrative, or what?

I added the phrase "or its equivalent" to highlight that the Java 
methods were not the only way - especially since some vendors provide 
non-Java APIs.

> 8. Section 6, 3rd para: I haven’t ever seen anything like the note
> about what an OASIS TC might be doing in an RFC before, but possibly
> I’ve just missed the examples.

Since this section discusses the actual use cases, I can't really do 
much but note where those use cases stem from.

> 9. Section 7, last para: “As described in Section 4, others can define
> additional variants”... there is no description in Section 4 of how to
> define additional variants. Also, while the language in the opening of
> the draft suggests that the set of variants is open-ended, this is the
> first explicit mention of this possibility that I encountered. Is
> there a registry?
>
> Oh, there it is in section 9.2. OK, I think that the beginning of the
> doc needs to say that the set of variants is open-ended and
> vendor-extensible. It also smells like a big huge honking
> interoperability hole.

I added a sentence in the introduction: "Vendors defining additional 
variants are strongly encouraged to register them with IANA as 
documented in Section 9.2.1."

As for the interoperability hole, I believe I addressed that above.
> Nits:
>
> 1. Section 4 para 3, superfluous comma after “Both the variant”.

Replaced much of this text based on other feedback.
> 2. Section 4 para beginning “Each variant can have query
> parameters...” - did you consider separating the variant prefix from
> the rest of the parameter name with “.” or some other syntax marker? I
> note that you use “jndi-” for another class of parameter names below.

See my comment to item #2 of yours above.
> 3. Section 4.1 I assume “shared” means “available in all variants”? If
> so, why not say so?

Added clarifying text.

> 4. Section 4.1 first para, the word “property” suddenly appears for
> the first time. Is this a synonym of “parameter”?

Added clarifying text, which I think clears up the distinction between 
the parameters (in the URI), and the JMS Message properties.

> 5. Section 4.1.1 Lots of references here need to be turned into RFC
> style with square brackets
We already reference the JMS specification, and tried to avoid repeating 
references when they were referenced by acronyms already defined (JMS).
> 5. Same section, missing full stop after “following shared parameters”.

Fixed with new text.

> 6. 4.1.1 Probably more idiomatic of normative text to say, instead of
> “This MUST be”, “The value of this parameter MUST be...”

Fixed.
> 7. 4.1.1 Missing full-stop at end.

Fixed.

> 8. 6, 2nd para: What’s an “SPI”?
Added a parenthetical indicating the abbreviation.

As I've said before, thank you very much for the wonderfully thorough 
review.


-Eric.