mhadley's Blog

Bumper Crop of WADL Tools

Last week saw the release of three new WADL frameworks:

Python

WADLLib

C#

WADL#

Ruby

Ruby client for the Web Application Description Language

Earlier I had committed, but failed to blog about, changes to wadl2java that enable the latest version to read both the current and prior versions of WADL files. This is driven by an XSLT stylesheet filter that updates the previous version to the latest version while leaving the current version intact.

Declarative HTTP Link Headers

I've extended the declarative hyperlinking module to support the HTTP Link header. It works similarly to the @Link annotation I described earlier except you annotate the response entity class with @LinkHeader (or @LinkHeaders if you need more than one Link header) instead of annotating response entity fields with @Link. Here's a complete example that shows both annotations in action:

@LinkHeader(value=@Link(resource=WidgetResource.class), rel="self")
@XmlAccessorType(XmlAccessType.NONE)
@XmlElement(name="widget")
public class WidgetRepresentation {

  @Link(resource=WidgetResource.class)
  @XmlAttribute
  private String href;
    
  String id;
    
  public WidgetRepresentation(String id) {
    this.id = id;
  }
  
  public String getId() {
    return id;
  }
}

Given a resource class:

@Path("widgets/{id}")
public class WidgetResource {

  @GET
  @Produces("application/xml")
  WidgetRepresentation getWidget(@PathParam("id") String id) {
    return new WidgetRepresentation(id);
  }
}

A GET request for /application/widgets/10 will result in:

HTTP/1.1 200 OK
Server: GlassFish v3
Link: </application/widgets/10>;rel="self"
Content-Type: application/xml
Content-Length: xxx
Date: Thu, 18 Mar 2010 21:04:04 GMT

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<widget href="/application/widgets/10"/>

where the bold text is created by the new linking annotations.

Declarative Hyperlinking in Jersey

One of the areas I'm keen to improve in the next version of JAX-RS is link creation. JAX-RS already offers UriBuilder but I think an annotation driven approach could save a lot of repetitive coding.

I've been experimenting with a couple of annotations that I think would be useful and I just checked in an experimental extension that partially implements what I have in mind. Suppose you have a resource like this:

@Path{"widgets"}
public class WidgetsResource {
  ...
}

and you want to include a URI to this resource in a representation. Using the new extension you can just annotate a field in your representation class like this:

@Link(resource=WidgetsResource.class)
URI link;

and then Jersey will build the appropriate URI and inject it into the representation before the representation is serialized by a message body writer.

If the URI template contains parameters, their values are obtained by looking for a bean property or field by the same name in the representation. E.g. consider the following representation class:

public class WidgetRepresentation {
  @Link("widgets/{widgetId}")
  URI link;
  
  String getWidgetId() {...}
}

After processing by the extension, if the getWidgetId method returned "abc123", the value of the link field would be /context/widgets/abc123 where context is the deployment context.

The optional style property of the @Link annotation can be used to select between absolute URIs, absolute path and relative path depending on requirements.

Using the Extension

In order to try out the extension you have to:

• Declare a dependency on the new jersey-server-linking module which is available in Jersey trunk under the experimental directory.
• Install the response filter in your application using an init-param in the web.xml like this:

  <servlet>
    <servlet-name>Jersey Web Application</servlet-name>
    <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
      <init-param>
          <param-name>com.sun.jersey.config.property.packages</param-name>
          <param-value>your application packages here</param-value>
      </init-param>
      <init-param>
          <param-name>com.sun.jersey.spi.container.ContainerResponseFilters</param-name>
          <param-value>com.sun.jersey.server.linking.LinkFilter</param-value>
      </init-param>
      <load-on-startup>1</load-on-startup>
  </servlet>

Next Steps

The Javadoc of the @Link annotation describes a couple of things that I plan to implement next:

• Support for the @Binding annotation already sketched out in the code. This will allow the values of template parameters to be pulled from alternate sources including differently named properties of the representation and resource.
• Support for EL expressions in link templates. This will allow a little more expressivity for templates that don't already exist as values of @Path annotations.

HATEOAS with WADL

Craig asked me how you would describe something like the Sun Cloud APIs with WADL and I thought others might be interested in the answer. A key feature of the cloud APIs is that they make good use of hypertext as the engine of application state or HATEOAS for (relatively) short. What this means is that rather than documenting a set of URIs and URI templates and relying on the client to construct URIs to access the resource they need, the cloud APIs only publish a single "root" URI and then document where to find additional URIs in representations that clients can use to traverse the service. This is much closer to how a browser user traverses links in web pages. In a recent blog entry Craig describes the advantages of HATEOAS.

So, how to describe this kind of Web application in WADL ? The key is to:

1. Use resource types to describe each kind of resource,
2. Parameterize representations to identify links embedded within them,
3. Define the types of resource each embedded link identifies.

To illustrate I'll use the Sun cloud APIs and the root level representation of the VDC. In WADL we describe this top level resource as follows:

<resources base="http://example.com/">
  <resource path="/" type="#vdc"/>
</resources>

The above declares a top level resource of type "vdc" at the URI "http://example.com/". Next we need to describe the resource type "vdc":

<resource_type id="vdc">
  <method name="GET">
    <response status="200">
      <representation mediaType="application/vnd.com.sun.cloud.compute.Vdc+json">
        <parameter name="attach" path="vms[].attach" style="plain">
          <link resource_type="#button"/>
        </parameter>
        <parameter name="detach" path="vms[].detach" style="plain">
          <link resource_type="#button"/>
        </parameter>
        <parameter name="backup" path="vms[].backup" style="plain">
          <link resource_type="#button"/>
        </parameter>
        ...
      </representation>
    </response>
  </method>
</resource_type>

The above says that a representation of resources of type "vdc" can be obtained with GET and that such representations contain links to other types of resources. I've shown three links here but in reality a VDC document contains many more. Each link is contained within a parameter that describes where in the representation the link can be found. In this case each link is to the same type of resource that essentially acts like a push button, here's the description of that resource type:

<resource_type id="button">
  <method name="POST">
    <response status="204">
  </method>
</resource_type>

The above says that resources of type "button" only support POST and return an empty 204 response on success.

I've glossed over one important issue related to the use of JSON for the representation of a VDC. If the representation used XML then the value of the path attribute of the parameter element is an XPath and it has semantics for selecting a set of nodes. For JSON theres no such standard path language (that I'm aware of) so I've had to improvise. The "vms" property of the vdc JSON object is an array and the "[]" in the path attribute values is meant to signify that the path will match multiple properties of the JSON object, if anyone has a better idea then let me know.