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

[jsr339-experts] Re: [Client API] Refactoring Link and Invocation

From: Sergey Beryozkin <sberyozkin_at_talend.com>
Date: Thu, 07 Jul 2011 15:48:41 +0100

How about me saying I'm supporting your latest proposal, but with:

1. Link becoming a plain bean, a holder of URI plus associated metadata,
     extending Configurable only but not driving the creation of
Invocation, rather let put this responsibility on Client. It has no any
setters, preparing HttpRequest is the job of Invocation

2. Client uses URI, UriBuilder or Link to create Invocations as opposed
to Client and Links creating Invocations.

3. Ideally, rename Invocation to something more 'friendlier'

It's effectively what my proposal is about too, except that I chose
making Invocation & Link (renamed to WebResource) HTTPRequests,

Sergey

Bill Burke wrote:
> From what I understand of your proposal, again, I believe it will not
> work. I may be misunderstanding it. Please provide example code which
> uses Link to make multiple requests that:
>
> a) use different query parameters
> b) uses a URI template with different path parameters per request
> c) uses different headers and/or header values per request
> d) all of the above
>
> On 7/7/11 9:07 AM, Sergey Beryozkin wrote:
>> If you think about it, the main thing I propose is to treat Link as
>> WebResource which can do invocations. It's effectively what Invocation
>> does in your proposal (extends HttpRequest).
>>
>> I actually think our proposals are similar.
>>
>> We can start from your proposal and modify it further:
>>
>> 1. Strip Links of all the factory methods, have only getURI, etc. Make
>> Link a URI wrapper only.
>>
>> 2. Client has only request() factory methods, no link(). This is because
>> Invocation has become a builder in your proposal. These request factory
>> methods will accept URI, UriBuilder and Links
>>
>> 3. Rename Invocation to something like WebResource, I just don't like
>> the name "Invocation".
>>
>> Thus we'd only have:
>>
>> Client->Invocation/Webresource->get
>>
>> Link would be used to initialize Invocation/Webresource.
>>
>> That would be nearly the same what I propose:
>>
>> Client->WebResource(which is now Link)-GET
>> or
>> Client->WebResource(which is now Link)-Invocation-GET
>> with a *new* Link having getters only.
>>
>> I thought we can just keep the generic part (Invocation) separately, but
>> may be we can effective have Invocation+Link = WebResource, and much
>> simpler Link
>>
>> Sergey
>>
>>
>> Sergey Beryozkin wrote:
>>> Bill Burke wrote:
>>>> Again, with your model, you'd have to create a Link per-request you
>>>> want to make. You wouldn't be able to reuse link, and you'd have to
>>>> do things like set security options per link if they were different.
>>>>
>>> No, that is not the case,
>>> in the proposed model the same Link (WebResource) instance will be
>>> able to do multiple invocations against the same remote web resource,
>>> or will be able to spawn invocations (get/post/etc) specific though
>>> I'm not sure why, but that would be possible. Link itself won't be
>>> generically Invocable but it can delegate to Invocation but only if
>>> really needed.
>>>
>>>> BTW, with the current model, Link *would* become a central piece of
>>>> the API if it gets integrated with a Hypermedia API like what
>>>> Restfulie has.
>>>>
>>> Please, review my proposal :-). IMHO Link acting as factory of
>>> Invocations and duplicating HttpRequest is not a true Link. As I said
>>> I'd like Link be renamed to WebResource. Or I can propose it
>>> differently: lets introduce new WebResource class which will do what I
>>> proposed Link will do and have current Link have only getters (URI,
>>> metadata, etc) with Client or WebResource using it,
>>>
>>> Sergey
>>>
>>>> On 7/7/11 8:10 AM, Sergey Beryozkin wrote:
>>>>> Hi,
>>>>>
>>>>> Bill Burke wrote:
>>>>>> The problem with this approach is that link objects are not reusable.
>>>>>> Sure, it looks great for the simple case of link.get(), but once you
>>>>>> start wanting to add headers, use URI templates with path params, set
>>>>>> query params, all in one request chain, it totally falls apart.
>>>>> As I clarified in my last response, with Link extending HttpRequest,
>>>>> and
>>>>> hopefully renamed to WebResource/etc, it can start managing all the
>>>>> request parameters, finalizing cleanly with get(). And optionally
>>>>> letting users to move to working with Invocation but see 4-6 below.
>>>>>
>>>>> I thought that what you did with Invocation in the latest refactoring
>>>>> (re get(), etc) should be basically moved to Link.
>>>>>
>>>>> I think the 'real' Link can only identify URI + metadata (point 9) and
>>>>> it will be the job of Client to use that would-be Link to initialize
>>>>> new
>>>>> WebResources or generic Invocations.
>>>>>
>>>>> To be honest, I don't think I'm proposing a major refactoring. Some
>>>>> renaming, making Invocation a generic Invocation, eliminating the
>>>>> duplication between Link and HttpRequest, and treating Link
>>>>> (Webresource) as the central piece.
>>>>>
>>>>> cheers, Sergey
>>>>>
>>>>>> Maybe I am not understanding your proposal. Some example code might
>>>>>> help clarify things.
>>>>>>
>>>>>> On 7/7/11 6:59 AM, Sergey Beryozkin wrote:
>>>>>>> Hi
>>>>>>>
>>>>>>> Here are some thoughts based on the current API draft and Bill's
>>>>>>> version
>>>>>>> [1].
>>>>>>>
>>>>>>> IMHO some simplification is needed. Here is the proposed list of
>>>>>>> changes:
>>>>>>>
>>>>>>> 1. Client should have factory methods only for creating Links (things
>>>>>>> that identify web service Resources). IMHO, Link needs to be named
>>>>>>> differently - but more about it later.
>>>>>>> ClientFactory->Client-Link is minimal and functional.
>>>>>>>
>>>>>>> ClientFactory->Client-Link and ClientFactory->Client-Invocation is
>>>>>>> the
>>>>>>> source of confusion and duplication IMHO.
>>>>>>>
>>>>>>> 2. Link must extend Configurable and HttpRequest<Link>.
>>>>>>> The removes the duplication between Link and HttpRequest.
>>>>>>> HttpRequest.Builder<Invocation> extension needs to be dropped.
>>>>>>> Effectively Link becomes the thing which manages the invocation
>>>>>>> itself.
>>>>>>> Link needs to have methods like
>>>>>>>
>>>>>>> HttpResponse get()
>>>>>>> T get(Class<T>)
>>>>>>>
>>>>>>> etc, as well as
>>>>>>>
>>>>>>> invoke(String httpMethod)
>>>>>>>
>>>>>>> Link is a builder (path params, queries, etc) and the final invoker.
>>>>>>>
>>>>>>> 3. Link has a single factory method for creating Invocation:
>>>>>>> Link.invocable(String httpMethod)
>>>>>>>
>>>>>>> I don't think it's a big problem, as far as this specific proposal is
>>>>>>> concerned, to have a String parameter given that I'm trying to
>>>>>>> make Link
>>>>>>> the central piece of API and Link will have its typed get(), etc. If
>>>>>>> needed we can have Invocation.Builder (instead of
>>>>>>> HttpRequest.Builder)
>>>>>>> introduced that will have methods like getRequest(),
>>>>>>> postRequest(), etc,
>>>>>>> returning Invocation initialized with GET, etc, to avoid confusion
>>>>>>> with
>>>>>>> Link's own get()/etc methods.
>>>>>>>
>>>>>>> 4. Invocation stays as is - it manages ***only generic invoke() and
>>>>>>> async queue()***. Invocation.Builder as suggested in 3. may get
>>>>>>> introduced at the expense of HttpRequest.Builder.
>>>>>>>
>>>>>>> 5. Link becomes the central piece of this API.
>>>>>>>
>>>>>>> 6. The only path from Client to Invocation is via Link. However,
>>>>>>> in most
>>>>>>> cases, users won't even need to do Invocation-centric programming,
>>>>>>> they
>>>>>>> will just work with Link. Invocation will only be used for async or
>>>>>>> generic invoke() cases - which would be quite specific. If really
>>>>>>> really
>>>>>>> needed Client may also implement Invocation.Builder (as suggested
>>>>>>> in 3
>>>>>>> and 4) or a variation of it for Invocation being minimally but fully
>>>>>>> initialized from the get-go, ex, Client.getRequest(requestURI)
>>>>>>>
>>>>>>> 7. Having a dedicated AsyncInvocation looks good - but I'm quite
>>>>>>> happy
>>>>>>> with a single Invocation offering generic invoke or async options.
>>>>>>> Either option works for me.
>>>>>>>
>>>>>>> 8. I believe that what is called Link now should be renamed to
>>>>>>> WebResource or Resource or similar. WebResource acts as a "proxy",
>>>>>>> manages the interaction with remote Resources identifiled by
>>>>>>> ***links***, where links are edges as Markus said.
>>>>>>>
>>>>>>> 9. IMHO Link should act as String, unmodifyiable thing. Link should
>>>>>>> wrap:
>>>>>>> URI
>>>>>>> relation if any
>>>>>>> metadata if any
>>>>>>> base if any
>>>>>>> etc
>>>>>>>
>>>>>>> IMHO Link is a URI with associated metadata and that is all. If we
>>>>>>> rename what is currently called Link to WebResource then we can have
>>>>>>> Client.resource(URI.create("http://foo"))
>>>>>>> Client.resource(new Link(...))
>>>>>>>
>>>>>>> etc. Link is URI and it can be shared, passed around and will fit
>>>>>>> nicely
>>>>>>> into the whole hypermedia effort
>>>>>>>
>>>>>>> Thanks, Sergey
>>>>>>>
>>>>>>> [1] https://github.com/patriot1burke/redhat-jaxrs-2.0-proposals-rev2
>>>>>>>
>

-- 
Sergey Beryozkin
http://sberyozkin.blogspot.com
Talend - http://www.talend.com