On 8/29/11 8:25 AM, Marek Potociar wrote:
> Hi Bill,
>
> On 08/26/2011 10:16 PM, Bill Burke wrote:
>>
>>
>> On 8/26/11 3:05 PM, Bill Burke wrote:
>>>
>>>
>>> On 8/26/11 2:48 PM, Marek Potociar wrote:
>>>> Are you now suggesting we take the generic invocation out??
>>>
>>> Yes. I think many specifications try to incorporate a lot of edge cases
>>> and end up seriously bloating themselves. This may be one of those
>>> scenarios. At the time, it seemed like a good idea that wouldn't affect
>>> the API very harshly. Things have changed.
>>>
>>> I'm pretty sure you could combine Invocation, Invocation.Builder, and
>>> SyncInvoker if you did this. I'll edit your latest stuff and show you.
>>>
>>>
>>
>> Ok, I did this exercise based on latest HEAD:
>>
>> https://github.com/patriot1burke/redhat-jaxrs-2.0-proposals-rev2/tree/master/jax-rs-api-r4
>>
>> * Removed SyncInvoker
>> * Removed Invocation.Builder
>> * removed header methods from Invocation
>> * Invocation extends Configurable<Invocation>, RequestHeaders.Builder<Invocation
>> * Renamed AsyncInvoker to AsyncInvocation
>> * AsyncInvocation extends Configuration<AsyncInvocation>, RequestHeaders.Builder<AsyncInvocation>
>> * moved async() method back to Target. IMO this didn't/doesn't make sense and it was an extra unneeded step:
>>
>> target.request()....async().put()
>>
>> I think this is a good first step in refactoring the API to get to where everybody wants it.
>>
>
> 1. Why would one want to decide sync/async before potentially updating headers? Seems to me that to implement a common
> headers mutator you would need to provide 2 overloaded versions, to accommodate sync/async invocation:
>
> setHeaders(Invocation i);
> setHeaders(AsyncInvocation i);
>
I don't really care too much about this, it just seemed weird at the
time to do:
request()....async()
> 2. Removing the header mutators from the Invocation and extending RequestHeaders.Builder once again decreases
> consistency of the flow context.
>
How does it decrease consistency? I guess you're trying to separate
entity headers from request headers via the Entity class? (BTW, "Link"
is an entity header and can be used in a request or response).
> 3. The ability to produce generic and fully flexible/mutable invocations is completely lost in exchange for interface
> reduction.
>
Interface reduction == easier to read and understand what is going on.
This is the whole point of this exercise.
> 4. The proposed Invocation interface encapsulates multiple concerns reducing the cohesion of its API. It's not the only
> class in JAX-RS with such problem, but it's the most exposed class to the everyday users that has the problem.
>
Well, that's certainly your opinion, not mine. My opinion is that the
most exposed class to everyday users should be the most easiest to use
*and* understand. The class hierarchies you've proposed so far are
spaghetti.
> All of he above in exchange for a reduction by 2 interfaces that are typically invisible to the end user anyway. Why
> would we sacrifice a nice feature (generic invocation) that doesn't cost virtually anything and does not interfere with
> the main API scenarios, while providing a nice low-level flexibilty if needed, is beyond me. But that's just my take on
> it. I'd like to see some feedback from other experts.
>
Well, my previous proposal (Invocation extending HttpRequest) pretty
much has all the flexibility you want, with a reduced understandable
class hierarchy, separation of concerns, with a tiny bit of
inconsistency that nobody outside of this list will care about. I'd
rather suffer a tiny bit of inconsistency instead of having multiple
ways to do the same exact thing.
> FWIW, target.async(...) doesn't read as good, as Target.request()[.async()] IMO, but if people think it's useful, I can
> add such shortcut: AsyncInvoker Target.async(...);
>
request().async().get();
vs.
async().get();
Both are fine for me, I don't really care.
Finally, I did this exercise to show that generic invocations are one of
the things that are seriously complicating the API. (A complication
that wouldn't exist if you weren't so stubborn on the fluent api).
--
Bill Burke
JBoss, a division of Red Hat
http://bill.burkecentral.com