users@jersey.java.net

Re: Re: [Jersey] Client java stubs with Jersey

From: gerard davison <gerard.davison_at_oracle.com>
Date: Mon, 07 Sep 2009 13:48:27 +0100

On 19:59, Paul Sandoz wrote:
> [deletia]
>> I can see the argument against it; but in many cases your "basic
>> work-a-day" developer is not going to understand the finer
>> distinctions in REST and wants a simple API to program against. This
>> is the same thing we see with JAX-WS/WSDL where most user appear to
>> treat it as a black box.
>>
>> Now with Jersey, as it currently stands, we can at least generate
>> some JAXB files for the user if we expose the grammar using the WADL
>> extension. I do wonder if this should be the default as it would make
>> tooling much each to write. What is the reasoning behind not making
>> this a default feature of the WADL generator?
>>
>
> Time and TLC in this area :-)

Out of interest how much work do you think would be in this area before
it would be the default? (Just so if I can argue to apply some time to
this problem) Even if we ignore the "proxy" issue for the moment this
would still be a big help to any client to be able to have some
description of the data model. There seem to be a feeling that you can
do without a data model design when doing REST; but from my rather
limited understanding so far this is not the case.

Also in this area is supporting a default transform such as
http://aruld.info/jersey-103-improves-wadl-support/ be possible as it
makes WADL so much easier to read. Is this just a lack of time thing again?

>
>
>> As to the client interface, I guess this along with HATEOAS is
>> something for JAX-RS 2.x, I do like how RESTEasy present these client
>> interfaces:
>>
>> http://jboss.org/file-access/default/members/resteasy/freezone/docs/1.1.GA/userguide/html/RESTEasy_Client_Framework.html
>>
>>
>> I am not saying this should be the only way to talk to a service; but
>> it is certainly a nice model to present to developer who want
>> something more concrete.
>
> I avoided a proxy-based approach because JAX-RS artifacts do not
> translate to the client side in all cases e.g. returning of Response
> for example, or sub-resource locators. Which is why RESTEasy has to
> deviate and have a class such as ClientResponse. I am not really
> criticizing here just making an observation. RESTEasy is doing it's
> best to work around the fact that JAX-RS 1.x was designed for
> server-side only.
>
> In general this approach can create the illusion that one can define a
> set of interfaces that you implement on the server side and can reuse
> on the client side. This approach can be limiting for a number reasons:
>
> 1) It makes it harder to implement the service. HTTP is the interface,
> there is no need to define interfaces for your
> resources unless it is required for some sort of internal
> architectural detail.
>
> 2) If the client is also depending on those interfaces it may make it
> harder to evolve the server side. With JAX-RS
> it is possible to do all sorts of refactorings while from a HTTP
> perspective the client will not notice anything,
> in addition to adding more sub-resources or support for more
> media types.
>
> 3) I get the impression that for a fully fleshed out client API to a
> service a proxy-based approach or the builder
> approach is not wholly sufficient and it is better to provide a
> library. This is in fact what the Sun Cloud team
> have done, using the Jersey API underneath to make it easier for
> them to implement this API.
>
>
> I can see the merit in some cases for a proxy-based approach if the
> artifacts are independent from the server implementation and created
> by the consumer or by the provider.

This was definitely my thinking. They should never in the real world
share the same interfaces. The client would be generated entirely from
the WADL have no compile time dependency on any server artifact.

>
> But, even then in terms of LOC you can achieve similar results using a
> fluent-based API. And in terms of reuse i deliberately designed
> WebResource to be reusable and for child resources to be easily
> created, so you can be DRY.
>
> I think the one clear advantage of a proxy-based approach is it can
> act as a form of documentation in code and it makes it easier to write
> code when using an IDE. (Fluent APIs are harder to document with
> JavaDoc.)
>
> Even though i am somewhat cold to lukewarm on the idea of proxies for
> clients i suspect any JAX-RS 2.x effort will likely specify a solution
> in addition to a fluent-based API.

I think you have hit the nail on the head with the IDE issue. For some
groups of customers, particularly 4GL users, they definitely need this
kind of compile time structure that described the service. (And most
likely won't want to have to learn how to read WADL) I personally prefer
the fluent API; but that is not everybody's cup of tea I guess.

>
>
> What i would really like to see is the following tooling: having docs
> and code completion with the Jersey client API based on dynamic
> analysis of WADL obtained from the service. It could even provide
> snippets of template Jersey client code that one could copy and paste.
> The nice thing about this is it will work with any service that
> provides WADL (e.g. Zembly uses WADL a lot for consuming services and
> that WADL could be reused).

Now that is very interesting and very doable as fluent APIs are
particularly readable from a tooling point of view. This could be
possible, the only problem is there is currently no connection between
the WADL the and Client Code insight for a particular WebResource. You
would need to have "eyes" on the creation of the Client or the
@WebResourceRef that contains the resource URL and then the tool could
then just call "OPTIONS" to get the structure of the
resource/application in question. Would this generally work for REST
services or just for Jersey implemented applications?

Taking this further you can make sure the bean objects you pass in as
types map to the correct schema types defined in the WADL grammar if
available. It would make the fluent API verifiable at development/build
time which might make people who want the proxy interface happier.

Thanks for the thoughts,

Gerard


>
> Paul.
>
>> It is also something we can easily give the users to get them going.
>> I have looked at the wadl2java project; but would prefer from a
>> simplicity point of view to be able to point users at some part of
>> the Jersey project.
>>
>> Cheers,
>>
>> Gerard
>>
>>
>> On 19:59, Paul Sandoz wrote:
>>> <div class="moz-text-flowed" style="font-family: -moz-fixed">On Sep
>>> 2, 2009, at 9:31 AM, xworker wrote:
>>>>
>>>> Hi
>>>>
>>>> I'm using Jersery for ws in my project. I've got a JPA backend with
>>>> lots of
>>>> entitys. Question:
>>>>
>>>> How do I generate java POJO stubs from my Jersey ws? For SOAP I was
>>>> able to
>>>> generate client-side stubs, but not for REST?
>>>
>>> I advise against creating Java client stubs from Java server
>>> artifacts because they make a tight coupling between client and
>>> server-side code (but see later).
>>>
>>>
>>>>
>>>> Frontend is a backingbean with JSF pages.
>>>>
>>>> <code>
>>>> wr =
>>>> client.resource("http://localhost:8080/pe-backend/resources/activities");
>>>>
>>>> activityList = wr.get(new GenericType<List<Activity>>() {
>>>> });
>>>> </code>
>>>>
>>>> How shouold my backingbean know what Activity is?
>>>>
>>>
>>> Human readable documentation of the service to be read by the
>>> developer. Because the client is separated from the server you can
>>> also do:
>>>
>>> wr =
>>> client.resource("http://localhost:8080/pe-backend/resources/activities");
>>>
>>> activityArray = wr.get(Activity[].class);
>>>
>>> or perhaps use a different version of Activity (JAXB is somewhat
>>> flexible in terms of consuming documents with additional XML it does
>>> not understand). Or use some XPath on DOM.
>>>
>>> WADL can be used to help create the human readable documentation
>>> that can be served as part of the service. Jersey dynamically
>>> creates a WADL description of the service, see also here:
>>>
>>> http://wikis.sun.com/display/Jersey/WADL
>>>
>>> If you really want static client stubs you could use the wadl2java
>>> facility available from:
>>>
>>> https://wadl.dev.java.net/
>>>
>>> Paul.
>>> </div>
>>>
>>
>> --
>> Gerard Davison | Senior Principal Software Engineer | +44 118 924 5095
>> Oracle JDeveloper Web Service Tooling Development
>> Oracle Corporation UK Ltd is a company incorporated in England & Wales.
>> Company Reg. No. 1782505.
>> Reg. office: Oracle Parkway, Thames Valley Park, Reading RG6 1RA.
>>
>> Blog http://kingsfleet.blogspot.com
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
>> For additional commands, e-mail: users-help_at_jersey.dev.java.net
>>
>
> </div>
>

-- 
Gerard Davison | Senior Principal Software Engineer | +44 118 924 5095
Oracle JDeveloper Web Service Tooling Development
Oracle Corporation UK Ltd is a company incorporated in England & Wales.
Company Reg. No. 1782505.
Reg. office: Oracle Parkway, Thames Valley Park, Reading RG6 1RA.
Blog http://kingsfleet.blogspot.com