UriBuilder Questions

From: Marc Hadley <Marc.Hadley_at_Sun.COM>
Date: Thu, 30 Aug 2007 14:41:48 -0400

Here are three questions related to UriBuilder[1] we'd like some
input on:

(i) Setting automatic encoding status from the UriTemplate.encode

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 ? resets
the state to blank to avoid a deep-copy of the builder contents to
prevent subsequent modifications from affecting the returned
Response. Since 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.



Marc Hadley <marc.hadley at>
CTO Office, Sun Microsystems.