On Jul 22, 2008, at 10:15 PM, Manger, James H wrote:
> > (a) Remove the encode and isEncode methods
>
> Great.
> The @Path encode attribute should similarly be removed (but not
> @Encoded of course).
>
Yes.
>
> > (c) Similar to (a), the build method will encode characters that
> are not allowed in the relevant URI components
>
> Will ‘/’ be %-escaped for limited placeholders?
With the change to allow regex specification for a parameter the
limited/unlimited distinction goes away (we'll remove the limited
property).
> When is the “relevant URI component” a segment (‘/’ not allowed so %-
> escaped) and when is it a path (‘/’ allowed so not escaped)?
>
> Possible solutions:
> • %-escape all non-unreserved chars in values passed to build(…) –
> but then supporting unlimited placeholders is not trivial.
> • Rename path(String… segments) to segment(String… segments) and
> state that ‘/’ chars are %-escaped. A static fromSegment(String)
> method might also be needed. This would make it clear what the
> “relevant URI component” is.
> • Nothing (other than documenting that the relevant URI component
> is a segment for limited @Path placeholders, a path for unlimited
> @Path placeholders, and a path for fromPath(String) and
> path(String…) methods). Programmers need to explicitly call
> quote(String) (or replaceAll(“/”, “%2F”)) when they want a single
> segment and when filling a Map to pass to build() (though they won’t
> always bother).
>
> How about replacing the existing fromResource, fromPath and 4 path
> methods with:
> static UriBuilder fromResource(Class);
> UriBuilder resource(Class);
> UriBuilder resource(Class, String method);
> UriBuilder resource(Method…);
>
> static UriBuilder fromPath(String);
> UriBuilder path(String);
>
> static UriBuilder fromSegment(String…);
> UriBuilder segment(String…);
>
> Those make it clearer what the relevant URI component is, for the
> arguments and for placeholders they contain.
>
I like the current methods that all allow '/' but I'm open to adding a
new pathSegment(String ...) method that will encode embedded '/'
characters. I think it would also be useful to rename the segments
parameter in the existing methods to make it clear that each value is
a path rather than a path segment.
Marc.
>
> _____________________________________________
> From: Marc.Hadley_at_Sun.COM [mailto:Marc.Hadley_at_Sun.COM]
> Sent: Wednesday, 23 July 2008 1:58 AM
> To: users_at_jsr311.dev.java.net
>
> OK, I'm convinced. Here's what I propose we do:
>
> (a) Remove the encode and isEncode methods, all methods that add URI
> components will perform contextual encoding of characters that are
> not allowed in the relevant URI component with the following
> exceptions:
> { and }. % chars followed by two hex digits (the rfc pct-encoded
> production) will not be encoded, other % chars will.
>
> (b) Add a static method that will encode any characters not part of
> the rfc 3986 unreserved production.
>
> (c) Similar to (a), the build method will encode characters that are
> not allowed in the relevant URI components. I.e. any embedded { or }
> will be encoded unlike when adding URI components in (a).
>
> The above will allow creation of any valid URI. The only case that
> developers will have to be careful with is when an input string
> contains a literal % character coincidentally followed by two hex
> digits. The method added by (b) can be used to fix this although it
> won't work if the same string also contains pct-encoded chars - I
> don't think this a big issue since any string obtained from @*Param
> is either encoded or not, you won't get a mixture.
>
---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.