On Jun 16, 2008, at 11:35 PM, Manger, James H wrote:
>
> 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.
>
A use case you might not have considered is generating URI templates
from JAX-RS classes. Keeping the JAX-RS templates a strict subset of
the URI templates draft makes this relatively straightforward.
Assuming URI templates catch on (which I think they will) this seems
useful.
> @Path varnames matching the Java identifier rule might be interesting.
> A @PathParam value could default to the name of the identifier
> that it annotates.
Unfortunately the names of method parameters are not available at
runtime so you need the @*Param value in that case. It would be
possible to support an empty value for class fields and bean
properties, definitely something to consider and I've added issue 44
to track this.
https://jsr311.dev.java.net/issues/show_bug.cgi?id=44
> 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.
>
That's a good point, the spec needs tightening up on this issue.
> 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]
>
Fixed, thanks.
Marc.
>
> -----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.
>
---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.