jsr339-experts@jax-rs-spec.java.net

[jsr339-experts] Re: Client API is very complex

From: Marek Potociar <marek.potociar_at_oracle.com>
Date: Mon, 27 Jun 2011 17:26:23 +0200

On 06/27/2011 04:40 PM, Sergey Beryozkin wrote:
> Hi,
>
> I've been getting up to speed with Client API. I've no concrete proposals right now and I'm not sure I can affect what
> has already been written out there, but here are some initial observations. Also, one thing I'd like to clarify is that
> I understand it's much easier for someone like me to pop-up and start criticising :-) and I respect the work the experts
> have done so far - but here I am and have my initial comments.
>
> It's too complex. As simple as that (no pun intended). I appreciate a lot of thought has been given to it, but it's too
> complex. IMHO if we want this API compete with a proxy based API which is a simplicity in its extreme, we should
> simplify the current Client API.

As I said in a separate email, I am open to discussion, but it should be an evolution, not a completely new proposal.
Also, the intent is to provide a low-level, but still restful API, not to compete with a proxy based solutions. FWIW,
there is very little restful about the resource proxy APIs that I have seen so far.

>
> Here are some observations:
> 1. ClientFactory is factory of clients

It was not there, was added based on EG request.

>
> 2. Client is a factory of Links but also a factory of Invocations.

True.

>
> 3. Link **is** effectively a Client even though Links are supposed to be identifiers of resources Clients are supposed
> to work with.

I did have this design at one time, but then I got a feedback that I am missing the instance to hold expensive
initialization.

>
> 4. Link is a factory of Invocations

True. Also factory for sub-resource links.

>
> 5. get().params(...).invoke() just reads wrong; the whole idea is to capture the fact clients are doing HTTP centric
> programming with get()/etc and here get() is just lost in the noise with faceless invoke() finishing the chain.

I guess with fully mutable requests, the method name can get lost any time. Also, when I had a very first proposal where
this was at the end, the proposal was viewed as too complex since there were more builder interfaces involved. Also, for
me, it is a MUST HAVE that a request is *ALWAYS* fully initialized (i.e. it has a URI and method set).

>
> I apologize if the above is totally out of context - but IMHO something needs to be simplified. I'm traveling this week
> but hoping to provide some more constructive feedback, as opposed to just a critique, asap

Cool. Looking forward :)

Marek

>
>
>
> thanks, Sergey
>