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.
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
>
--
Bill Burke
JBoss, a division of Red Hat
http://bill.burkecentral.com