On 08/25/2011 04:23 AM, 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
Yes. I opted for an interface composition as opposed to repeating same long list of method definitions in HttpRequest,
HttpResponse, Invocation.Builder etc. It seemed more effective to work with right now and less error prone. Once the API
is fully stable, we can reconsider the approach, as I wrote earlier.
> 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.
The idea behind decoupling the HttpRequest from the flient client API is that the purpose of the fluent client API is
not to expose a bare request, but to build and execute one in a fluent flow of method invocations that resemble
complete, semantically correct DSL sentences. Also, as the controversial client.request() has been removed, there's not
much one can do with HttpRequest. Any code consuming Invocation should be easily modified to consume Invocation.Builder
instead. It may depend on the particular use case, but it seems to me that most of the code that needs to take
invocation as an input parameter and modify it could be rewrote into a filter resulting in a cleaner app design. That's
however just my gut feeling.
> 5) Invocation should probably extend HttpRequest
If it does you either need to restrict HttpRequest API from supporting path and method mutators or live with the loose
fluent API. The second option is the one I see as problematic from the very beginning.
> 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);
It also still does allow you to do:
client.target().invocation().invoke(); // what did I just invoke?
Additionally, by removing the path mutators from the HttpRequest to make the fluent API more strict you lost the option
of e.g. appending a query parameter to the request in JAX-RS filters.
>
> 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?
>
My understanding is that this is the core of our argument. Unlike you, I feel that in case of fluent API the consistency
is a big deal. A fluent API, the way I understand it, is not just a bunch of chained methods. I feel we need more input
from other EG members in order to resolve this, so I solicited their feedback on the subj. in a separate thread earlier
today.
Marek