[jsr339-experts] Re: Low-level JAX-RS client API proposal
Great. :-)
> -----Original Message-----
> From: Marek Potociar [mailto:marek.potociar_at_oracle.com]
> Sent: Montag, 9. Mai 2011 17:14
> To: jsr339-experts_at_jax-rs-spec.java.net
> Cc: Markus KARG
> Subject: [jsr339-experts] Re: Low-level JAX-RS client API proposal
>
> Hi Markus,
> Thanks for great and detailed feedback!
>
> In the next few days I am going to process your email and create
> additional subtasks from your comments as appropriate.
> Once that's done I'll try to provide a detailed response with pointers
> to the new tasks.
>
> Thanks again,
> Marek
>
> On 05/07/2011 06:04 PM, Markus KARG wrote:
> > Marek,
> >
> > looks promising so far, but as it is a rather lot of classes and
> methods you possible might have expected correctly already that I will
> have a lot of comments to post... ;-) So here they are.
> >
> > * As we are heavily using Java EE, we are running our clients in Java
> EE Application Client Containers, and the web resource is located in
> the same domain's server container. So it is very annoying that the
> client application must provide the URI of the web resource. With JAX-
> WS it gets the end point injected. It would therefore be really good to
> get injected a WebResource into the client. Handling of the Client must
> be provided by the Java EE Application Client Container in that case.
> For Java EE Fat Client vendors this would be a highly appreciated
> feature, which got already discussed between Paul Sandoz and the Java
> EE team AFAIK. This certainly enforces that a Java EE compliant
> Application Client Container MUST provide an implementation of the JAX-
> RS Client API. Obviously it makes sense to extend this to all Java EE
> containers, as any Java EE component could be a client in turn.
> >
> > * How to install custom providers (MessageBodyReader,
> MessageBodyWriter, ContextProvider, ExceptionHandler)?
> >
> > * Reverse exception handling (i. e. transforming 404
> FileNotFoundException etc.) seems to be not possible, but would be
> great. Just as a server can turn FileNotFoundException into 404 by pure
> declaration of a provider, it should be possible the reverse way on a
> client.
> >
> > * Why not having a Client.create(Class) or Client.create(Class,
> String method) way to create WebResource? This would allow to obtain
> URI information from annotated ResourceClasses. That way a vendor could
> provide a JAR with those to the client application developer reducing
> the need to know the pattern of the URIs. This is particularly useful
> if server and client application are implemented by the same team, as
> it might be the case for in-house applications. Obtaining the correct
> URI pattern is a real pain with JAX-RS 1 currently, so this could be
> rather useful.
> >
> > * Support for HTTP/1.1 sessions: I did not find information in the
> JavaDoc how an application can tell whether a HTTP call shall run in
> the same or in a different HTTP/1.1 session against the same
> WebResource (since WebResource is not called WebResourceSession, I
> expect that it handles sessions internally).
> >
> > * Client Side Caching, see separate discussion in this forum.
> >
> > * Why not splitting the actual Client from the ClientFactory to make
> clear the different use cases (creating a Client vs. creating a
> WebResource)? Also, instead of using delegates, we could provide a
> ClientProvider class that creates ClientFactories. This makes more
> clear to the user what class is for what use and it allows to reduce
> the spec on the level of interfaces while currently the Client class
> contains actual implementation code.
> >
> > * JavaDocs do not explain how a caller should know the name of a
> Feature or a Property. Either the property names should be told, or it
> should be told that this information is provider specific. Also it is
> unclear, what Properties and Features are good for particularly at
> ClientRequest and ClientResponse -- what are those good for?
> >
> > *JavaDocs of Client.resource() says "Creates a Web resource", which
> is misleading, as it does not create a Web resource. It creates an
> instance of the WebResource class, which is nothing but a connection
> handle TO a Web resource. Users could expect that method to do HTTP
> POST, which it actually doesn't do.
> >
> > * For me it is not clear whether ClientConfiguration is allowed to be
> implemented by a calling application, since the JavaDocs only mention
> modification of an obtained default configuration. JavaDocs should
> clear tell whether this is allowed or forbidden.
> >
> >
> > * For me it is not clear why there are both, getClasses and
> getSingletons to get providers. On the server side, getClasses returns
> resources, and getSingletons returns Providers. But how does that work
> on the Client? What is the intention of providing two ways of
> providers? Since both must not be null, it looks like one has to
> provide an instance AND its class, but the class can be obtained from
> the instance in turn. So what is getClasses good for actually?
> >
> > * I'm not a big friend of abstract classes since it reduces the
> freedom of the provider. Why not just providing an interface for
> ClientFilter? I doubt that anybody is unable to write that single code
> line that keeps the "next" reference. Also, as a WebResource is only to
> be created by a builder and the builder is to be provided by a JAX-RS
> implementation, I do not see a need to provide more than the
> WebResource's interface as part of the spec. It should be completely up
> to the implementation how WebResource works internally and what it
> extends from.
> >
> > * I'm not a mathematical expert, but WebResourceBase's .hashCode()
> implementation looks rather complex. I think "return
> this.getClass().hashCode() ^ this.uri.hashCode()" would do and would be
> much simpler? Looks like some black magic currently. ;-)
> >
> > * Why naming it "ClientFilter"? I expect that JAX-RS providers server
> filters too and I do not see a need for a making a difference in both,
> as both handle requests and responses. We could share the same
> interface for that.
> >
> > * JAX-RS 1 is able to detect providers automatically. The JavaDocs do
> not say that a client will do so. Why?
> >
> > * Why insisting on ClientRequest being Cloneable?
> >
> > * Is it essential to keep the ordering of cookies? If not, why then
> returning List<NewCookie> instead of just Collection<NewCookie>?
> >
> > * It might happen that a client does not know the entity type a
> server is sending. It then will inspect the Content-Type header to know
> the MediaType. But when it wants to get the entity as a JAXB instance,
> how shall it know the Class to provide to
> ClientResponse.getEntity(Class)? To solve that it would be good to have
> ClientResponse.getEntity() method that just doesn't expect to get a
> Class, and which just returns the Object instance created by the
> particular MessageBodyReader.
> >
> > * Can you provide a use case when a user will apply the
> ClientResponse.bufferEntity() method?
> >
> > * The current proposal seems to expect that a WebResources get
> filtered ever or never, but it might be the case where filtering is
> dependend of the current session. So the question is where we need to
> support that. Currently it won't work as removing a filter while an
> asynchrounous request is pending might lead to unknown behaviour.
> >
> > * I am the maintainer of the WebDAV package for JAX-RS and so I am
> heavily interested in providing a WebDAVMethodInvoker as a replacement
> for the HttpMethodInvoker. But I did not find a way how a calling
> application could register interest is that. How to do that?
> >
> > * A GUI might be heavily interested in getting updated after
> receivering another HTTP chunk. I didn't find a way how an application
> could register for such events. This is essential to show a progress
> bar with long-lasting downloads.
> >
> > * Side note: My Eclipse shows a lot of warnings. Style should be
> fixed in the final release.
> >
> >> -----Original Message-----
> >> From: Marek Potociar [mailto:marek.potociar_at_oracle.com]
> >> Sent: Dienstag, 3. Mai 2011 18:46
> >> To: jsr339-experts_at_jax-rs-spec.java.net
> >> Subject: [jsr339-experts] Low-level JAX-RS client API proposal
> >>
> >> Hello experts,
> >>
> >> I have just published the low-level client API proposal page[1] on
> our
> >> project wiki. I have also pushed the initial
> >> client API code (including javadoc) to the public git repository.
> >> Please consider it to be an initial draft to start the
> >> EG discussion that should lead to the final proposal.
> >>
> >> The proposal wiki page[1] summarizes what has been done so far. It
> also
> >> lists some open questions we are aware of that
> >> still need to be addressed. Thanks to Santiago the page also
> contains
> >> an UML class diagram of the initial API classes as
> >> well as pointer to the client API samples wiki page[2].
> >>
> >> Please, read through at the proposal wiki page, look at the sample
> >> usages, checkout the source code and browse through
> >> the javadoc to familiarize yourselves with the proposal. We are
> looking
> >> forward to your feedback!
> >>
> >> Let the fun begin, :)
> >> Marek
> >>
> >>
> >> [1] http://java.net/projects/jax-rs-spec/pages/Low-levelClientAPI
> >> [2] http://java.net/projects/jax-rs-spec/pages/Low-
> >> levelClientAPISamples
> >