I've reviewed [1] and I'm happy with most of the proposed changes. I
think it looks OK.
The only slight concern is Target.prepare() or actually the whole
Invocation thing but I'll comment on it as well as on some other minor
issues in a sep thread in order to not to overload this heads-up thread...
I guess Target.prepare() is good in that it lets delegate the control to
a batch-able Invocation - but something is there that makes me think
it won't really work in the reality - comments to follow...
IMHO overall [1] is a good step forward compared to the over-complicated
*user-level* API of prev revisions...
I'd really not want to have prepare() or request() or whatever being
enforced on users for them be able to simple gets/etc...
I'd also like to get back to Bill's comments about custom config
factories participating in the flow, I thought his comments made sense
at a time - will try to comment on that asap...
Thanks, Sergey
On 25/08/11 10:11, Marek Potociar wrote:
> Dear experts,
>
> over the last few days we've been debating about the recent update of the client API proposal[1] and the alternative
> proposal submitted by Bill Burke[2]. (FWIW, as I finished this email I have noticed that Bill sent out a revised
> proposal[3], but I did not have the time to look at it in detail yet. --Marek)
>
> C1: Both proposals are shooting for allowing the fluent API with the HTTP verb at the end of the invocation chain, e.g.:
>
> client.target(uri).request().accept("text/plain").get();
>
> The main discussion evolves around fluent API simplicity vs. fluent context conistency.
>
> Oracle position is that a major attribute of any fluent API is to be able to detect as many semantic errors statically
> as reasonable at expense of an increased complexity in the class hierarchy. We believe that by introducing additional
> intermediate builder interfaces the fluent API should actively prevent users from writing inconsistent or semantically
> incorrect code, e.g.:
>
> C2: client.target(uri).request().accept("text/plain").invoke(); // what method is invoked?
> C3: client.target("http://someuri").request().path("http://otheruri").get() // fluently switching target uri in request?
> C4: client.target(uri).request().method("PUT").type("text/plain").entity("Hello").get(); // should this be legal?
>
> We believe that intermediate interfaces in the fluent API should also actively support IDE code completion in suggesting
> only meaningful methods in the given fluent context - once you use "method("GET")" it should not offer you method
> "put()" as a follow up, once you are done crafting the request uri and move to specifying headers, you should not be
> able to go back to the uri crafting again in a single fluent invocation chain. We also believe that such API is better
> described in examples as opposed to plain list of documented classes and methods, since most of the intermediate classes
> and even methods might not make much sense outside the fluent invocation context. A good example of such API is a Google
> Guice Binder API[4].
>
> In contrast with the position described above, Bill is leaning towards the simplicity of the fluent API class hierarchy
> that can be sufficiently described by a simple javadoc. The fluent API should be able to cover semantically meaningful
> invocations such as in the code example C1. He argues that the fluent API should however not care too much about
> statically preventing errors such as C2, C3, C4, since the larger problem cannot be fully solved anyway without
> dramatically increasing the class hierarchy complexity. IOW, the code examples C2, C3, C4, should compile without any
> errors (this statement might not fully apply to the revised Bill's proposal[3] --Marek).
> Bill: Hope I have accurately described your high-level position regarding the client API. Feel free to elaborate on your
> position if my description is incomplete or inaccurate.
>
> As you can see, we are coming from completely opposing directions. To resolve this situation we need your feedback.
> Please kindly step up and share your opinion with us!
>
> Many thanks,
> Marek& Santiago
>
> [1] http://java.net/projects/jax-rs-spec/sources/git/show/src/jax-rs-api/src/main/java/javax/ws/rs/client/
> [2] https://github.com/patriot1burke/redhat-jaxrs-2.0-proposals-rev2
> [3] https://github.com/patriot1burke/redhat-jaxrs-2.0-proposals-rev2/tree/master/jax-rs-api-r3/src
> [4] http://google-guice.googlecode.com/svn/trunk/javadoc/com/google/inject/Binder.html
--
Sergey Beryozkin
http://sberyozkin.blogspot.com
Talend - http://www.talend.com