Marc,
I still feel that implying a link between @Path values and W3C URI templates
will cause more confusion than clarity. It is an unnecessary coupling.
@Path varnames only need to match @PathParam values. This is internal to
a single *.class file (or perhaps between *.class files in a hierarchy).
It is quite different to W3C varnames which need to be agreed to by
separate parties (eg a web site authoring a template, and each client app
that is processing the template). W3C varnames will be defined by other
standards (eg "searchTerms" in OpenSearch), whereas @Path varnames don't
need to be.
@Path varnames matching the Java identifier rule might be interesting.
A @PathParam value could default to the name of the identifier
that it annotates. Or even simpler, any un-annotated resource method
arguments whose name matches a @Path varname could use that value.
@PathParam would not be needed at all!
[Consistency with the other @XxxParam annotations may be a sufficient
reason to keep @PathParam.]
Using the field name as the default value for all @XxxParam annotation
would be a nice simplification --
assuming field names are available at runtime.
Java allows Unicode in identifiers. The following annotations would
be an intuitive way add JAX-RS to this class.
@Path("widget/{âge}")
public class A {
@GET
public String birthday(@PathParam("âge") int âge)
{ return "..."; }
}
The proposed @Path varname restriction wouldn't allow this.
It might be hard to diagnose as JAX-RS would treat the @Path as
"widget/%7B%C3%A2ge%7D", not an error. Requests would just get routed
to another resource method, or return 404.
Finally, the W3C spec, including the varname syntax, is far from finalized.
Some people want to be able to use URIs as varnames, for instance.
TYPO: @UriParam instead of @PathParam
[in §3.4.1 Sub Resources, page 12, line 20]
[in §3.5 Declaring Media Type Capabilities, page 13, lines 8 & 13]
James Manger
-----Original Message-----
From: Marc.Hadley_at_Sun.COM [mailto:Marc.Hadley_at_Sun.COM]
Sent: Tuesday, 17 June 2008 1:13 AM
To: users_at_jsr311.dev.java.net
Subject: Re: URI templates (resend2)
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.