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

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

From: Sergey Beryozkin <sberyozkin_at_talend.com>
Date: Thu, 07 Jul 2011 11:59:30 +0100

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