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