On Aug 10, 2007, at 8:04 AM, Paul Sandoz wrote:
> A bunch of observations on the API made while implementing are
> included in the comments of the impl [3].
>
Inlined below for reference:
> I don think we need an encode option. This will open us up to bugs
> because
> the client may say that the string is already encoded but may not be.
> The only reliable solution is to check the string regardless and
> encode as
> necessary.
>
While that would simplify the API I think it would make it difficult
for applications that work in "encoded space". If developers include
illegal characters and specify encode=false then they'll end up with
an invalid URI, I'm not sure how much effort we should expend to try
to prevent that.
On a related note should the build methods throw a
URISyntaxException ? On the one hand that seems like the right thing
to do, on the other hand that checked exception makes working with
the URI class quite awkward. It might be better to require
implementations to check the value of each parameter for illegal
chars when encode=false and throw an appropriate exception but that
could impact performance.
>
> For the following methods are template values expected to be
> encoded or not:
>
> public abstract URI build(Map<String, String> values);
> public abstract URI build(String... values);
>
Good point. If we keep the encode option, we need to add alternate
methods with an encode parameter and make the existing methods
equivalent to specifying encode=true.
>
> For the following:
>
> public abstract URI build(String... values);
>
> What do we do for a repeating template such as:
>
> /{a}/foo/{a}
>
> is it expected to supply one or two values. Two values don't make
> any sense
> since there is really one one value. So the values correspond to
> the number
> and order of unique templates.
>
I think your suggestion sounds like the best choice.
>
> Specify a value of -1 as no port?
>
> public abstract UriBuilder port(int port);
>
So then you can "unset" the port after constructing a builder from a
URI with a specified port ? Sounds reasonable to me.
>
> What happens if a path segment contains a '/' for:
>
> public UriBuilder path(String... segments)
>
My preference would be to allow it such that path("foo/bar") is
equivalent to path("foo", "bar").
>
> What happens to the matrix parameters when a path is replaced, i
> presume they
> are removed.
>
> public UriBuilder replacePath(String path, boolean encode) {
>
Agreed.
>
> Change:
>
> public UriBuilder path(Class resource) {
>
> to
>
> public UriBuilder path(Class<?> resource) {
>
> so that it is easier to get access to an annotation.
>
OK.
>
> What about null segment values, and queryParam/matrixPath names ?
Should we make null equivalent to "" for those ?
Marc.
---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.