On Jun 15, 2008, at 8:20 PM, Manger, James H wrote:
> Comments on JAX-RS 1.0-public-review-draft (April 18, 2008).
> Sorry this feedback is after the 2 June deadline. I hope it can
> still help.
> [resending (fixing a few typos) now that I have subscribed to the
> list]
>
> First off, this looks like a great specification that is well
> written. Thanks.
>
> 1. Calling @Path values "URI Templates"
>
> I assume the phrase "URI template" is intentionally the same as the
> current W3C efforts to write a URI Templates specification (M Hadley
> is an editor of both).
> A W3C URI template is designed to BUILD a URI from a collection of
> parameters
> parameters --> URI
> JAX-RS @Path values, in contrast, are designed to MATCH a URI and
> parse it into parameters
> parameters <-- URI
>
> Though these operations are not totally unrelated to each other,
> they do operate in different directions. The need different
> syntaxes. Only in the simplest special cases can one syntax fulfill
> both purposes. The current W3C draft says:
> "While URI Templates use a notation that is similar to some URI path
> matching notations in web frameworks, URI Templates were not
> designed for that use case, nor are they appropriate for that
> purpose."
>
> Consequently, JAX-RS should NOT call @Path values "URI Templates".
> A better term might be "URI Path Patterns" -- particular as @Path
> values are converted to regular expressions (eg
> java.util.regex.Pattern).
>
The plan is to use a profile of the URI templates specification that
would work in the reverse direction. Admittedly, given the direction
the URI template specification has taken, it will now have to be quite
a narrow profile but I think its worth maintaining the link.
> 2. Template variable regular expression
>
> The regular expression to match a @Path template variable is not
> quite right [§3.7.3 Converting URI Templates to Regular Expressions;
> footnote 4; page 17].
> It currently is
> \{([\w-\. ∼]+?)\}
> I suggest using
> \{([^}]*)\}
> That is, a template is any string in squiggly braces.
> There doesn't seem to be any reason to restrict the characters in a
> variable name, other than being able to notice when the name ends.
I'd prefer to keep parity with the varname production in the URI
template specification.
>
> - A hyphen in a character class needs to be the first character,
> otherwise it indicates a range.
> - A dot does not need to be escaped in a character class.
> - There is a space in the character class (before the ~) -- at least
> when I cut-n-paste from the PDF. I assume this was not the intention
> (though I think all chars, including space, should be allowed,
> except }).
The space is an artifact of the formatting, i'll fix it.
>
> - May as well allow an empty string as a name (ie use *, not +).
That would make it difficult to refer to the variable by name.
>
> - I don't think the reluctant qualifier '?' adds anything.
>
I'll replace the existing regexp with: \{([a-zA-Z0-9][-\w.]*)\}
>
> 3. MIME type ordering consistency
>
> Page 17 line 20 says: x/y < x/* < */*
> Page 18 line 13 says: n/m > n/* > */*
>
> It would be better to pick one convention for the whole doc and
> adjust the algorithm descriptions accordingly.
> It is probably easiest to change step 3(b) in §3.7.2 on page 17
> (adding “descending order” and adopting the page 18 ordering) to
> say:
> (b) Sort M (descending order) as follows:
> * The primary key...
> * The secondary key...
> Sorting of the media types follows the general rule: n/m > n/*
> > */*
>
OK
Thanks,
Marc.
---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.