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