dev@jsr311.java.net

UriBuilder <was> Re: How to create URIs?

From: Paul Sandoz <Paul.Sandoz_at_Sun.COM>
Date: Tue, 14 Aug 2007 11:42:01 +0200

Marc Hadley wrote:
>> 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.
>

OK. I was incorrectly assuming that encoding was idempotent.

The currently implementation needs some rework in this area and should
probably work consistently in encoded space.


> 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.

Indeed. URI.create() throws an IllegalArgumentException. Perhaps we can
use the same?


> 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.
>

Should we fail at the earliest opportunity to give a meaningful stack
trace to the source of error?

Using table look up it should be fairly efficient to validate encoded
characters. Although, validation will be performed again by URI.


>>
>> 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.
>

Is it likely that a developer would mix encoded/decoded space per a
UriBuilder or would a UriBuilder be used consistently in encoded or
decoded space?


>>
>> 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.
>

That is how i implemented it.


>>
>> 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").
>

That is how i implemented it.


>>
>> What about null segment values, and queryParam/matrixPath names ?
>
> Should we make null equivalent to "" for those ?
>

Currently a path(null)/path("") results in nothing appended to the path:

     UriBuilder.fromPath("/a/b/c").append("").build().
         toString().equals("/a/b/c");
     UriBuilder.fromPath("/a/b/c").append(null).build().
         toString().equals("/a/b/c");

but i am not sure if a '/' should be appended.

Should an IllegalArgumentException be thrown for null or "" query/matrix
names?

Paul.


-- 
| ? + ? = To question
----------------\
    Paul Sandoz
         x38109
+33-4-76188109