Marc Hadley's Blog

WADLing in Jersey

For a long time you've been able to retrieve a WADL document that describes the set of resources that make up a Jersey application. However, the returned WADL was generated at compile time and would only include resources that were statically known. In recent weeks we've switched many parts of Jersey including the WADL subsystem to use a shared abstract resource model that is built at runtime. This has allowed us to add some additional functionality that I'll describe here.

The main new feature is that you can now retrieve a WADL for an individual resource. The resource can be a static resource which is described in the application WADL or it can be a resource for which you've received a link in some returned representation. For an example, consider the Simple Console example in the Jersey distribution. This example has two resource:

http://127.0.0.1:9998/resources/form
http://127.0.0.1:9998/resources/form/colours

If you retrieve the "global" WADL (available at http://127.0.0.1:9998/resources/application.wadl) you get the following:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application xmlns="http://research.sun.com/wadl/2006/10">
	<resources base="http://localhost:9998/resources/">
		<resource path="/form">
			<method name="GET">
				<response>
					<representation mediaType="text/html" />
				</response>
			</method>
			<method name="POST">
				<request>
					<representation mediaType="application/x-www-form-urlencoded" />
				</request>
				<response>
					<representation mediaType="text/html" />
				</response>
			</method>
			<resource path="colours" />
		</resource>
	</resources>
</application>

From this you can see that you can get the "form" resource and post a HTML form to it and both will return some HTML. Also notice that there's a resource element with path colours but no other information about that resource. This is due to the "colours" resource being dynamically created by the subresource locator in Form.java:

@Path("/form")
@ProduceMime("text/html")
public class Form {
    
    @Path("colours")
    public Colours getColours() {
        return coloursResource;
    }
    
    ...
}

With the latest changes to Jersey you can now get information on such dynamic resources by GETing the resource with an Accept: application/vnd.sun.wadl+xml header that specifies that you want WADL rather than another representation. The Jersey runtime will inspect the object returned by the subresource locator and dynamically generate a WADL description. Thus:

GET /resources/form/colours
Accept: application/vnd.sun.wadl+xml

will return:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application xmlns="http://research.sun.com/wadl/2006/10">
	<resources base="http://localhost:9998/resources/">
		<resource path="form/colours">
			<method name="GET">
				<request>
					<param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="query" name="match" />
				</request>
				<response>
					<representation mediaType="text/plain" />
				</response>
			</method>
			<method name="GET">
				<request>
					<param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="query" name="match" />
				</request>
				<response>
					<representation mediaType="application/json" />
				</response>
			</method>
		</resource>
	</resources>
</application>

which corresponds to the resource class Colours.java.

The above works except in the case that the resource supports the GET method but does not declare the supported media types (equivalent to @ProduceMime("*/*")). In this case the resource GET method will be invoked for any value of the Accept including WADL so we've added an alternate way of getting the WADL. Rather than GETing the resource you can use a HTTP OPTIONS request. The body of the returned response will be a WADL describing the resource.

All of the above is currently implemented in the trunk and will be included in the forthcoming 0.5 snapshot release.

Comments

This work is licensed under a Creative Commons License.