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!
--
Bill Burke
JBoss, a division of Red Hat
http://bill.burkecentral.com