Hi Bill - I think your revision was nice - and it did help driving the
idea of having get()/post() at the end of the chain - which IMHO
is the major major simplification.
Personally, I kind of like the trunk revision, as I'm not too keen on
seeing API being a bit loose with respect to allowing innocuous but
confusing fluent sequences. But will also try to review your updated one.
I think your new book can focus on top-level interfaces and all of us
can help with describing a bunch of interfaces top-level ones extend :-)
Cheers, Sergey
On 25/08/11 03:23, Bill Burke wrote:
> Before I go further, some observations:
>
> 1) HttpRequest extends RequestHeaders and RequestHeadersBuilder
> 2) HttpResponse extends both ResponseHeaders and ResponseHeaders.Builder
> 3) #1 and #2 are there because interceptors want to be able to both view
> and modify the request and response
> 4) In the current API Invocation interface is unable to view nor modify
> the built HttpRequest. It is quite possible that application code
> consuming an Invocation interface will want to both view and modify the
> http request Invocation represents. For the same reason interceptors
> want to do the same.
> 5) Invocation should probably extend HttpRequest
> 6) Once Invocation extends HttpRequest you start to see that all the
> Builder interfaces just don't make sense at all.
>
>
>
> I took GIT HEAD and made the changes I was arguing about in previous
> emails:
>
> https://github.com/patriot1burke/redhat-jaxrs-2.0-proposals-rev2/tree/master/jax-rs-api-r3/src
>
>
> View the README.txt there for changes.
>
>
> My revision does *not* allow you to do:
>
> client.target().invocation().put().header().invoke()
> client.target().invocation().entity().pathParam().put().invoke();
>
> But it does allow you to do:
>
> client.target().invocation().header().method("PUT").entity(obj).post(obj);
>
> Again, as I stated earlier, I don't think this is a big deal as
>
> * Its pretty much the same as calling type() twice.
> * the method() method will rarely be used anyways
> * Do you really see anybody making this mistake?
>
> To do a "batched" invocation you need to do:
>
> client.target().method("PUT").entity("obj").invoke();
>
> IMO, its not that big a deal to require a "PUT" string here as this is
> basically a reflection-like use of the client API.
>
> To do an async call its:
>
> client.target().putAsync(obj);
>
>
> The changes I'm suggesting, IMO, do not compromise the idea of a fluent
> API, yet greatly simplify the class hierarchy and API. I'm very unhappy
> with the current direction the API design is taking as I feel it will be
> detrimental to first-time users trying to understand the API.
>
> As for Marek's "take it or leave it" ultimatum, I've decided to take the
> "leave it" option and take a long break from suggesting any more API
> modifications or additions. There's really a lot of other things I need
> to get done and you all seem pretty set on continuing down the direction
> you're taking. Good luck!
>
>
>
>
--
Sergey Beryozkin
http://sberyozkin.blogspot.com
Talend - http://www.talend.com