________________________________
From: Santiago Pericas-Geertsen <Santiago.PericasGeertsen_at_oracle.com>
To: Sastry Malladi <m_sastry_at_yahoo.com>
Cc: "jsr339-experts_at_jax-rs-spec.java.net" <jsr339-experts_at_jax-rs-spec.java.net>
Sent: Friday, December 23, 2011 7:11 AM
Subject: Re: [jax-rs-spec users] [jsr339-experts] Re: Re: Re: Re: Re: New to the group - comments on the current draft
On Dec 22, 2011, at 5:45 PM, Sastry Malladi wrote:
Yes, it should not be exclusive to browsers, but browsers are a bit more lenient in this regard. What I mean is that, if we send this extra metadata as part of the response, they are not going to choke. But the programmatic clients (thick or thin) may choke if we just send this data unconditionally, since their deserialization of the response may fail.
>
>
>That's why the suggestion is :
>
>If Resource developer annotated the resource methods like I showed in the example (@Linkable with template classes) AND
>
> - If the request is an OPTIONS request, always send the metadata (browsers typically don't send OPTIONS request)
>
> - if the request is a GET request, then if either User-Agent is a browser OR if the Accept header value contains text/html, send the metadata.
With the advent of HTML5, UI controller logic is being pushed into the browser (think GWT). As a result, I see less use for text/html and more use of application/json (or application/xml) in XHR browser interactions with JAX-RS resources. IMO, using a templating technology (like JSP) in JAX-RS to generate HTML only makes sense to send the presentation once (and even in that case, I don't think JAX-RS is the best technology for this), but after that it should all be XHR/json. This is one reason why I think MVC in JAX-RS is doomed for any non-trivial web app.
It should be easy to generate an OPTIONS request using something like jQuery, and this is why don't see as much value in your GET proposal.
Sastry > My GET proposal covers the scenario (which is the most common at the moment, IMO) where the user types in the resource URL in the browser and the browser does a GET - Today, browsers send the accept header by default containing text/html . I know that any JS running in the browser or programmatic clients typically always use application/json (or sometimes xml) and that case is covered as well. The basic point is that, if the requested format is text/html, it is harmless to send this extra metadata, since as there will be no serialization/deserialization issues. In our internal implementation, if the format is is text/html, we also return the relevant documentation for the resource being accessed, which is something that people love as it as provides a very friendly user experience.
In any case if we are not doing automatic updates to the DTOs in this version of the spec, perhaps this discussion is moot. Based on our user and developer interactions, this is something they would love to see, however.
Either way, the returned data is in the "link" attribute - It can be sent as a Link header (the disadvantage here is that browsers don't show this) or as an implicit added attribute in the payload - Perhaps this should be configurable.
In this first iteration, we will not do any automatic updates on the DTOs. However, Link will be supported in DTOs, so developers will be able use them. See [1] for an example.
-- Santiago
[1]
http://java.net/projects/jax-rs-spec/sources/git/content/src/examples/src/main/java/jaxrs/examples/link/ResourceExample.java?rev=91732486e642b371aeaf51d2d1021efe84f9af1f
From: Santiago Pericas-Geertsen <Santiago.PericasGeertsen_at_oracle.com>
>To: Sastry Malladi <m_sastry_at_yahoo.com>
>Cc: "jsr339-experts_at_jax-rs-spec.java.net" <jsr339-experts_at_jax-rs-spec.java.net>
>Sent: Thursday, December 22, 2011 12:28 PM
>Subject: Re: [jax-rs-spec users] [jsr339-experts] Re: Re: Re: Re: New to the group - comments on the current draft
>
>
>
>
>On Dec 22, 2011, at 2:20 PM, Sastry Malladi wrote:
>
>Do you have an alternate mechanism in mind that you intend to propose/include in the spec ?
>>
>>Note that the metadata will only be returned if either the caller is a browser or asked for text/html or sent an OPTIONS request, so it may not be too bad.
>>
>>The main point is the simplicity on the part of the resource developer and the consumer.
>
> The use of OPTIONS seems interesting to me; ideally it shouldn't be exclusively for browsers, but I haven't put much thought into this. Is this something that you'd be interesting in exploring more and proposing some options?
>
>
>-- Santiago
>
>
>From: Santiago Pericas-Geertsen <Santiago.PericasGeertsen_at_oracle.com>
>>To: Sastry Malladi <m_sastry_at_yahoo.com>
>>Cc: "jsr339-experts_at_jax-rs-spec.java.net" <jsr339-experts_at_jax-rs-spec.java.net>
>>Sent: Thursday, December 22, 2011 5:30 AM
>>Subject: [jax-rs-spec users] [jsr339-experts] Re: Re: Re: New to the group - comments on the current draft
>>
>>
>>Sastry,
>>
>>
>> Right, that was my understanding. As I said, for complex DTOs, this a bit too much information for a link attribute, especially when serialized as a link header or in XML. I think a different mechanism is needed to convey this information.
>>
>>
>>-- Santiago
>>
>>
>>On Dec 21, 2011, at 5:42 PM, Sastry Malladi wrote:
>>
>>The example is like this.
>>>Suppose I've an Item resource, whose attributes are represented by a class called ItemDto (basically the response from a GET). When a user does a GET, in addition to returning the normal ItemDto response, it can also return the metadata, by adding a @Linkable with the template class name on the PUT method. Please see the highlighted lines. Something similar to this - Basically a declarative way to specify the metadata to be returned. The Jayway folks can perhaps explain this better, but this is what I understand.
>>>
>>>
>>>
>>>
>>>
>>> @GET
>>> @Path("/{id}")
>>> @Produces(MediaType.APPLICATION_JSON)
>>>
@Consumes(MediaType.APPLICATION_JSON)
>>> @Linkable(LinkableIDS.ITEM_GET_ID)
>>> public Response getItemByID(@PathParam("id") String id) {
>>>
>>> return Response.ok(getSingleItem(id))
>>> .selfLink(LinkableIDS.ITEM_GET_ID, id)
>>> .selfLink(LinkableIDS.ITEM_UPDATE_ID, id).build();
>>> }
>>>
>>>
>>> @PUT
>>> @Path("/{id}")
>>> @Produces(MediaType.APPLICATION_JSON)
>>> @Consumes(MediaType.APPLICATION_JSON)
>>> @Linkable(value = LinkableIDS.ITEM_UPDATE_ID, templateClass = ItemDto.class)
>>> public Response updateItemByID(@PathParam("id") String id, ItemDto itemDto) { ...}
>>>
>>>
>>>A GET on this item resource, can then return data like this (sample)
>>>
>>>
>>>
>>>{links :
>>> * * -
{
>>> * rel : "self"
>>> * href : "280794129251"
>>> * method : "GET"}
>>> * -
{
>>> * rel : "self"
>>> * href : "280794129251"
>>> * -consumes : [
>>> * "application/json"
]
>>> * method : "PUT"
>>> * -template: {
>>> * name : null
>>> * id : null
>>> * category : null
>>> * listingType : null
>>> * condition : null
>>> * sellerName : null
>>> * price : 0.0
>>> * itemURL : null}}
]
>>> * name : "Apple iPad 2 32GB, Wi-Fi + 3G (Verizon), 9.7in - Black (Latest Model) New sealed"
>>> * id : "280794129251"
>>> * category : "171485"
>>> * listingType : "FixedPrice"
>>> * condition : "New"
>>> * sellerName : "chasoncros"
>>> * price : 649.0
>>> * itemURL : "280794129251?pt=US_Tablets"
>>>
>>>________________________________
>>> From: Santiago Pericas-Geertsen <Santiago.PericasGeertsen_at_oracle.com>
>>>To: Sastry Malladi <m_sastry_at_yahoo.com>
>>>Cc: "jsr339-experts_at_jax-rs-spec.java.net" <jsr339-experts_at_jax-rs-spec.java.net>
>>>Sent: Wednesday, December 21, 2011 1:02 PM
>>>Subject: Re: [jax-rs-spec users] [jsr339-experts] Re: Re: New to the group - comments on the current draft
>>>
>>>
>>>
>>>
>>>On Dec 16, 2011, at 9:09 PM, Sastry Malladi wrote:
>>>
>>>You mean something like WADL? Agreeing on the right "description language" would take another EG! Somewhat unfortunate, perhaps, this is not in the scope for JAX-RS 2.0.
>>>>
>>>>Sastry > I was thinking something simple like what the Jayway folks have implemented, where a template class is specified on the resource method's Linkable annotation and the jax-rs container returns the HTTP method name and the fields in the template class, including any validation contraints (e.g NotNull) etc.
>>>
>>> I haven't seen an example of this, but it seems the idea is to include a JSON representation in the template link attribute? Seems too much for an attribute. This should be conveyed by an entity --using OPTIONS or something similar?
>>>
>>>
>>>-- Santiago
>>>
>>>
>>>
>>>
>>
>>
>>
>
>
>