I've created Issue 389 to track this in the future:
http://restlet.tigris.org/issues/show_bug.cgi?id=389
As the current Reference class is already mutable, as opposed to JDK's URI
> class, and as the request is for a lighter approach than Reference (which is
> already quite light actually), I think that the only way to significantly
> improve the performance is to build the reference in a progressive process,
> from left to right, in order to be able to internally use a StringBuilder
> instead of having to compose multiple String parts stored in the builder.
It wasn't my intention to gain any performance from this new class, merely
convenience and ease of use. I don't think that building URI strings is a
performance problem for most people.
My intention was that the new class be very high level in terms of building
a URI string and I hope that the attached patch reflects that intention.
Kevin
On Nov 30, 2007 5:42 AM, Jerome Louvel <[EMAIL PROTECTED]> wrote:
> Hi all,
>
> 1) "append" versus "set/insert" approach
>
> As the current Reference class is already mutable, as opposed to JDK's URI
> class, and as the request is for a lighter approach than Reference (which is
> already quite light actually), I think that the only way to significantly
> improve the performance is to build the reference in a progressive process,
> from left to right, in order to be able to internally use a StringBuilder
> instead of having to compose multiple String parts stored in the builder.
>
> new ReferenceBuilder() -> ""
> appendScheme("http") -> "http:"
> appendAuthority("myhost.com") -> " http://myhost.com";
> appendSegment("dir") -> "http://myhost.com/dir";
> appendSegment("file") -> " http://myhost.com/dir/file";
> appendQueryParam("a", "1") -> "http://myhost.com/dir/file?a=1";
> appendQueryParam("b", "2") -> "http://myhost.com/dir/file?a=1&b=2";
>
> We could also provide an exhaustive set of static constructor methods such
> as:
>
> ReferenceBuilder.create("http", "myhost.com")
>
> I don't this that this build order constraint would be a limitation,
> otherwise people can always use Reference directly.
>
> 2) Checked exceptions
>
> I don't have strong opinion on this yet. For reasons I couldn't theorize,
> I tend to prefer RuntimeException which I find less intrusive for the
> programmer and still allow him to detect coding errors (like NPE, etc). To
> signal an inappropriate build order, we could just use IllegalStateException
> for example.
>
> 3) In addition to the Reference class, maybe the methods of Uniform class
> should accept URI instance as well, for URI provided via third party code?
>
> Best regards,
> Jerome
>
>
> 2007/11/30, Kevin Conaway <[EMAIL PROTECTED]>:
>
> > Since URISyntaxException is checked, I see no reason why the
> > ReferenceBuilder shouldn't throw a checked exception as well.
> >
> > I propose the following:
> >
> > ReferenceBuilder(Protocol, host, port, authority)
> > // Convenience constructors
> >
> > ReferenceBuilder appendPath(String unencodedPath);
> > ReferenceBuilder appendParameter(String name, String value);
> >
> > String toString();
> > Reference toReference() throws URISyntaxException;
> >
> > I see no real reason to use the java.net.URI class as the Restlet
> > framework doesn't make much use of it, particularly the Client.get()
> > methods which is where the builder class will be particularly useful
> >
> > Kevin
> >
> > On Nov 29, 2007 8:19 PM, Tim Peierls <[EMAIL PROTECTED]> wrote:
> >
> > > On Nov 29, 2007 7:58 PM, Paul J. Lucas <[EMAIL PROTECTED]> wrote:
> > >
> > > > On Nov 29, 2007, at 4:52 PM, Tim Peierls wrote:
> > > > > Abstractly, though, would you rather see ReferenceBuilderException
> > > > checked or unchecked in the following:
> > > > >
> > > > > try {
> > > > > Reference ref = ReferenceBuilder.appendBar
> > > > ("myBar").appendFoo("myFoo");
> > > > > // do something with ref
> > > > > } catch (ReferenceBuilderException e) {
> > > > > // myBad: foo must come before bar
> > > > > // clean up
> > > > > // ? throw e;
> > > > > }
> > > > >
> > > > > Programmer was wrong -- this should be unchecked, right?
> > > >
> > > > How do you know the programmer was wrong? How does the implementor
> > > > of ReferenceBuilder know whether the data was supplied by the
> > > > programmer or
> > > > the user of the program? If the latter, it's the user who is wrong in
> > > > which
> > > > case the programmer must deal with that. Therefore: checked exception.
> > >
> > >
> > > Yes -- sorry, got it backwards in my example.
> > >
> > > Unchecked exceptions are appropriate when the programmer can't
> > > reasonably be expected to handle the exception completely. Canonical
> > > example: If I'm out of memory, the best I can hope for is to flush file
> > > handles and try to clean up in a finally block. For some specific
> > > unchecked
> > > exceptions with special clean-up needs, *maybe* I'd catch and rethrow.
> > > But I
> > > can't think of a case where you would swallow an unchecked exception.
> > >
> > > I stick to the claim that verbs implying order in a Builder-style API
> > > may be appropriate in some settings.
> > >
> > >
> > >
> > > > In general, IMHO, you've got to have a really, really good reason to
> > > > make an exception unchecked. "Because it's easier" isn't a good reason.
> > > >
> > >
> > > Pretty much the point I was making on the "Exceptions in general"
> > > thread.
> > >
> > > But the "Because it's easier" argument is stronger you might think:
> > > I've come to regret the fact that Callable.call throws Exception. When
> > > the JSR 166 EG was designing Callable and friends, we had trouble deciding
> > > which way to go on this; we ended up with a conservative approach that in
> > > my
> > > (subsequent) experience tends to make things harder for the programmer
> > > with
> > > no real benefit.
> > >
> > > --tim
> > >
> >
> >
>
