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