A couple of additional questions have arisen during implementation:
(i) We'd like to restrict the use of URI template parameters to be
within a given component of a URI. It is difficult to apply correct
encoding rules when the value of a template parameter spans multiple
URI components since its not always clear whether a character is part
of the current URI component or is a component separator. E.g.
consider the following:
UriBuilder.fromPath("{arg1}").build("foo#bar");
In the above its not clear whether the '#' character should be
treated as a part of the path that needs to be encoded or as the
separator between the path and the fragment identifier. With the
restriction we propose the above would result in encoding of the '#'
such that the "foo#bar" becomes a path segment "foo%23bar" whereas:
UriBuilder.fromPath("{arg1}").fragment("{arg2}").build("foo", "bar");
would result in "foo#bar".
(ii) Related to (i), we'd like to remove the authority method since
we already have methods to set the components of authority separately
and, as described above, parsing the authority with URI template
parameters in place is difficult.
Thoughts ?
Marc.
On Aug 30, 2007, at 2:41 PM, Marc Hadley wrote:
> Here are three questions related to UriBuilder[1] we'd like some
> input on:
>
> (i) Setting automatic encoding status from the UriTemplate.encode
> property
>
> The fromResource(Class), path(Class) and path(Method) all point
> (indirectly) to a UriTemplate from which the value is extracted.
> You can specify whether a UriTemplate value should be automatically
> encoded via the encode property. Similarly you can control
> automatic encoding by the builder using the encode method. When
> adding the value of a UriTemplate to a UriBuilder it makes sense to
> use the value of UriTemplate.encode to determine whether encoding
> is required or not. The question is whether the value of
> UriTemplate.encode should stick with the UriBuilder or not.
>
> On the one hand it seems convenient to have the value of the
> template encode stick with the builder - if an application is
> written in "encoded space" (i.e. encode=false) then its likely that
> other strings will also already be encoded so forcing the developer
> to write the extra .encode(false) seems wrong.
>
> On the other hand, if the template encode value sticks with the
> builder, then toggling a UriTemplate.encode value will also require
> a change to all uses of that template within a builder and could
> lead to unexpected bugs if any occurrences are missed.
>
> I'm not sure which is the lesser of the two evils.
>
> (ii) UriBuilder state after a call to .build(...)
>
> Should the state be maintained after a call to build or should the
> builder be reset back to blank state ? Response.Builder.build
> resets the state to blank to avoid a deep-copy of the builder
> contents to prevent subsequent modifications from affecting the
> returned Response. Since UriBuilder.build returns a URI we don't
> have that problem so we can either reset or maintain the current
> state.
>
> (iii) What to do about null parameter values
>
> We touched on this earlier in the discussion about a URI builder
> but I don't think think we came to any conclusion. Lots of the
> builder methods take a String where a value of "" or null could be
> meaningful. Should we treat the two values as equivalent or should
> null generate a NullPointerException ? E.g. path("") would
> presumably add an empty path segment, should path(null) do the same
> or should it be an error ?
>
> On the one hand it seems like treating the two the same could be
> convenient, on the other hand null is often used to indicate
> something different to "" so we might not be doing developers a
> favor by masking the difference.
>
> Thanks,
> Marc.
>
> [1] https://jsr311.dev.java.net/nonav/javadoc/index.html?javax/ws/
> rs/core/UriBuilder.html
>
> ---
> Marc Hadley <marc.hadley at sun.com>
> CTO Office, Sun Microsystems.
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe_at_jsr311.dev.java.net
> For additional commands, e-mail: dev-help_at_jsr311.dev.java.net
>
---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.