users@jersey.java.net

Re: [Jersey] Hypermedia on the server. was Re: [Jersey] Re: Hypermedia for JAX-RS/Jersey clients and server

From: Marc Hadley <Marc.Hadley_at_Sun.COM>
Date: Wed, 13 Jan 2010 10:24:02 -0500

On Jan 13, 2010, at 5:39 AM, gerard davison wrote:
>
> I have been reading your updates to this in your wiki page which are really useful, like the example model:
>
> http://wikis.sun.com/display/Jersey/Hypermedia+Examples
>
> In the section "Serialization By Reference" you have an annotation that breaks references to object. The only problem with this that I see is that perhaps it doesn't give a consistent programming model. When I have been playing in this area I have explicitly used the resources in the model so you example becomes:
>
> public class CustomerBean
> {
> public List<AddressResource> addresses;
> }
>
I like the idea of not having to repeat the URI but I think some kind of annotation to mark fields that are subject to special processing (i.e. link generation) is a good idea. IOW, I think link generation should be requested by the developer rather than completely automatic.

As an alternative to the markup in the wiki:

@XmlUri("http://foo.com/customers/${this.id}/addresses/${that.id}")

we could do something like:

@Link(resource=AddressResource.class, bindings = {
    @Binding(name="customer_id", value="${this.id}"),
    @Binding(name="address_id", value="${that.id}")
  })

That way you don't have to repeat the URI template in an annotation in the model, instead you can extract it from the resource class controller.

What scopes do we need for the EL that defines the value of a URI template parameter ? I can think of three:

(i) The representation bean (model)
(ii) The annotated field instance for a collection (model.field[i])
(iii) The resource that returned the representation

Are there any others ?

> It would them be up to the address resource to specify how the URI is built, but I was thinking along the same lines but making use of Path parameters:
>
> @Path("/{parent}/{address}"):
> @PathParamEL("this.id","customer.id")
> public class AddressResource
> {
> @GET
> public Address getAddress()
> {
> ...
> }
> }
>
> The advantage here is that you don't assume that Customer and Address are on the same machine. For example it is perfectly possibly that the addresses could like in a different space. It does though restrict your server side design though, and does bring into question whether AddressResource should be a class/ interface / both. (I guess that is what I was getting at in http://kingsfleet.blogspot.com/2009/10/proxy-client-based-on-jersey-with-bit.html, but I haven't written up the server side yet)
>
I have to think about that some more, not sure how you would get the correct base URI for a resource on a different machine.

Marc.

>
> On 11/12/2009 19:31, Santiago Pericas-Geertsen wrote:
>> Gerard,
>>
>> Added section to [1] about use cases. Also, started new wiki [2] to develop a complete example that includes some exploration (mostly braindumping) of ideas/solutions.
>>
>> -- Santiago
>>
>> [1] http://wikis.sun.com/display/Jersey/Hypermedia+and+Client+APIs
>> [2] http://wikis.sun.com/display/Jersey/Hypermedia+Examples
>>
>> On Dec 11, 2009, at 12:56 PM, gerard davison wrote:
>>
>>>
>>>
>>> On 11/12/2009 14:21, Santiago Pericas-Geertsen wrote:
>>>> Hi Gerard,
>>>>
>>>> A few questions about your e-mail,
>>>>
>>>>> 1. Implicit / Derived links
>>>>>
>>>>> 1.1 Implicit (aka Legacy services)
>>>>>
>>>>> ...
>>>>> 1.2 Derived
>>>>>
>>>>> ...
>>>>> 2. Explicit links
>>>>>
>>>>> ...
>>>>
>>>> I think (1) and (2) are clear.
>>>>
>>>>> 3. Out of band links.
>>>>>
>>>>> 3.1 HTTP-Headers
>>>>>
>>>>> For example using HTTP Header Linking:
>>>>>
>>>>> http://www.mnot.net/drafts/draft-nottingham-http-link-header-00.txt
>>>>>
>>>>> Of course this binds your implementation to HTTP in a way you might live to regret at a later stage. Think of all the work that goes into supporting SOAP over non HTTP protocols.
>>>>
>>>> How would the representation of an <employee> look like using HTTP headers in your view?
>>>
>>> I don't have a good example unfortunately. I only came across them more recently.
>>>
>>>>
>>>>> In general it should be possible for a generic client to support of all these options
>>>>
>>>> Do you consider supporting all these options a goal?
>>>
>>> I would guess the goal would be to create as flexible a design as possible. Given that all the listed variants have some level of use out there it would seem a good idea to at least be sure we are not excluding them even if we don't have explicit support.
>>>
>>>>
>>>>> ...
>>>>> * Use cases *
>>>>>
>>>>> It would be good to have a list of use cases that we are trying to support.
>>>>
>>>> Yes, shall we use a wiki for that? I can start it.
>>>
>>> That would be good.
>>>
>>>>
>>>>> "The client of the API would like a static interface with which to program againsts. For the clients point of view this enabled them to use existing coding tools that understand java interfaces and beans."
>>>>
>>>> +1
>>>>
>>>>> "The publisher of the API would like to define a subset of the WADL/IDL for a client to use in a particular case. This would allow them to help guide client in Java through a particular route in the API. "
>>>>
>>>> Is this related to HATEOAS or a more general issue?
>>>
>>> More of a general issue; but it seems to be made worse with HATEOAS in some ways as the user can end up with too many options.
>>>
>>>>
>>>>> "The client of the API should be able to deal with the evolution of server data model"
>>>>
>>>> +1
>>>>
>>>> All these UCs should help us derive a list of requirements (which we sort of started already, but it's likely incomplete).
>>>>
>>>>> entity => m0 or instance data
>>>>> wadl => m1 or meta data
>>>>> links in http headers => is this m0 or m1? I am not sure we it contains both instance references and information about the structure of the model
>>>>
>>>> m0.5? :)
>>>
>>> Perhaps, I did have a think about this over night. I guess there is no difference between a link header and a link in the entity. So for the moment I am coming down in the side of it being m0. My thinking is that the state transition are the data rather than describing the data in some way. I could if course be very wrong! :-)
>>>
>>> Gerard
>>>
>>>
>>>>
>>>> -- Santiago
>>>>
>>>>
>>>> ---------------------------------------------------------------------
>>>> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
>>>> For additional commands, e-mail: users-help_at_jersey.dev.java.net
>>>>
>>>
>>> --
>>> Gerard Davison | Senior Principal Software Engineer | +44 118 924 5095
>>> Oracle JDeveloper Web Service, Spring, Weblogic SCA 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 Twitter kingsfleet
>>>
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
>>> For additional commands, e-mail: users-help_at_jersey.dev.java.net
>>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
>> For additional commands, e-mail: users-help_at_jersey.dev.java.net
>>
>
> --
> Gerard Davison | Senior Principal Software Engineer | +44 118 924 5095
> Oracle JDeveloper Web Service, Spring, Weblogic SCA 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 Twitter kingsfleet
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
> For additional commands, e-mail: users-help_at_jersey.dev.java.net
>