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) – perhaps email has to be sent from a registered address (even for public feedback)]
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).
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.
- 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 }).
- May as well allow an empty string as a name (ie use *, not +).
- I don't think the reluctant qualifier '?' adds anything.
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/* > */*
James Manger