Re: UriBuilder <was> Re: How to create URIs?

From: Dhanji R. Prasanna <>
Date: Tue, 14 Aug 2007 21:25:14 +1000

On 8/14/07, Paul Sandoz <> wrote:
> Marc Hadley wrote:
> >>
> > 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.

nooo. % is a special character..

+1 to removing encode.* already has an encoder/decoder utility.

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

They should throw a public unchecked analog of URISyntaxException (maybe
UriBuilderException?) because:

a) A malformed URI to the builder represents a programmer bug (validation
failure or lack thereof)
b) A checked exception is meant for expected, recoverable errors in the
framework behavior (example socket-failure).
c) IllegalArgumentException is non-descript for a framework artifact

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

I think it is ok to fail at the build() step. That is the expected contract
of the builder pattern anyway. Static protections ought to suffice for the
Idea for kitchensink: a URL integral data type in java =P

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

Yea this is the old Integer.valueOf(..) debate, NumberFormatException imo is
thrown correctly unchecked as it is a programmer bug that the string was not
validated as convertible.
My guess is most use cases will fall back on regex validation (ugh but

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

This is not an assumption we should force from the framework. How about the
builder bootstrap itself, something like:


Note that a character encoding needs to be specified too. How would we
handle that?

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

How about an unsetPort() method?

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

I like IAE being thrown on null, again it represents programmer error. But
appending "" should be idempotent (and redundant) to the construction
anyway, so why bother?