Applying the Web to Enterprise IT

The last posting in this introductory series provided a high level overview of the Jersey client side framework I am working on together with Paul. In this one, we look at some of the details.

At the heart of the framework lies the concept of ViewResources. Conceptually, ViewResources are an extension of the existing Jersey client side WebResource class. A ViewResource is a client side ‘handle’ for an HTTP resource through which HTTP requests to the resource can be performed. While WebResource ‘invocations’ result in ClientResponses or object representations of the response entities ‘invocations’ of ViewResources produce view objects that encapsulate assumptions (including anticipated next transitions).

The choice of view class for a given request completely expresses the assumptions made about the resource and the response. The view class in turn encapsulates these assumptions in a single artifact.

Regarding the examples that follow it is important to keep in mind that the view objects are not to be seen as local proxies for remote ‘objects’ but that the view objects hold application state and provide access to the data contained and a means to activate the controls that are (maybe) embedded in it.

In a subsequent installment of this introductory series we will see how even the entities of error responses constitute application state and can be used to construct corresponding views (possibly with contained application data and/or embedded controls for outgoing state transitions).

GET requests

URI poUri = URI.create("http://foo.org/purchaseOrders/42");
ViewResource vr = client.viewResource(poUri);
PurchaseOrderView pov = vr.get(PurchaseOrderView.class);

For GET requests there is a shorthand removing the need for an intermediate ViewResource object:

URI poUri = URI.create("http://foo.org/purchaseOrders/42");
PurchaseOrderView pov = client.view(poUri,PurchaseOrderView.class);

PUT requests

URI poUri = URI.create("http://foo.org/purchaseOrders/42");
ViewResource vr = client.viewResource(poUri);
PurchaseOrderView pov = vr.put(PurchaseOrderView.class, "some purchase order data");

For the use with PUT requests the build method of the PurchaseOrderView class could be implemented to work with both 200 Ok and 204 No Content responses. In the former case the body woud be interpreted as a representation of the order and in the latter the build method could perform an additional GET on the request URI to obtain a a representation of the order. We will discuss such support for automated transitions in a dedicated posting.

POST requests

URI colUri = URI.create("http://foo.org/purchaseOrders");
ViewResource vr = client.viewResource(colUri);
CreatedView<PurchaseOrderView> cv = new CreatedView(PurchaseOrderView.class);
vr.post(cv, "some purchase order data");
PurchaseOrderView newPoView = cv.getCreated();

This example makes use of the ‘helper’ view class CreatedView<T> provided with the framework. This view class encapsulates the HTTP mechanics related to 201 Created responses and makes the created resource retrievable as a view through the getCreated() method.

Note how this example instantiates the view class outside the framework and supplies the instance directly to the post() invocation.

DELETE requests

URI poUri = URI.create("http://foo.org/purchaseOrders/42");
ViewResource vr = client.viewResource(poUri);
VoidView vv = vr.delete(VoidView.class);

This example uses the framework supplied view class VoidView to handle the (possible empty) response to the DELETE request. Because the VoidView really does not express any kind of expectation its use outside the context of pure examples is rather useless.

Expectations pertaining to the context of a request should be encapsulated inside a view class and not be propagated into the code that actually uses the view. Deal with HTTP mechanics (such as checking response status) inside view classes.

For the past couple of weeks Paul Sandoz and I have been working on a client side framework for Jersey that encourages RESTful design on the client side. After a trial period with frequent code changes, we feel that the code base is now stable enough to go public.

The framework introduces an annotation based approach that enables developers to turn arbitrary classes of the client side code into HTTP response handlers. The framework refers to instances of such classes as ‘views’ (mostly for the lack of a better term).

Views serve three purposes:

1. Build-up state corresponding to the handled response

View classes provide specifically annotated methods that will be invoked by the framework core to handle the response. These ‘build’ methods are intended to build-up the state of the view object from the HTTP response.

2. Present or make accessible the data of the current application state
Usually, users (human or machine) intend to use the information contained in HTTP response bodies. View objects make this information accessible either through GUI elements for human users or through access methods for machine users.

3. Use the hypermedia controls embedded in the response body to turn user (human or machine) actions into HTTP requests.

Both human and machine users interact with RESTful applications through user agent components by activating the controls embedded in the representations of the current application state. View objects provide a means for the user to activate the controls and will then create the corresponding HTTP requests. The means for control activation can be GUI elements in the case of human users or regular methods in the case of machine users.

Enough theory – let’s look at some code.

Suppose we want to develop a view class that is is suitable for Atom Publishing Protocol collections. The following examples step by step show the different aspects of such a view class and how it could be used.

First, we need a build method for handling HTTP success responses to GET requests to collection resources.

public class CollectionView {
 
	private Feed feed;
 
	@GET
	@Status(200)
	@Consumes("application/atom+xml")
	public void build(Feed feed) {
		this.feed = feed;
	}
}

The annotations on the build-method indicate to the framework core that the method applies to responses to GET requests that have a status of 200 Ok and a response body of the media type application/atom+xml. As requested by the method parameter list the framework core will inject the response body as a Feed object to enable access to the body inside the build method.

The code below shows how the CollectionView class might be used. The new view method on the Jersey Client class performs an HTTP GET on the provided URI, instantiates a new object of the provided class and then dispatches to a suitable build method of the created instances (based on the annotations).

public void main(String args[]) {
	URI uri = URI.create("http://example.org/blogs/jim/entries");
	Client client = new Client();
 
	CollectionView cv = client.view(uri, CollectionView.class);
}

Next we need to add to our CollectionView class methods that provide access to information contained in the feed. To keep things simple, we’ll just provide a getter for the title of the feed.

public class CollectionView {
 
	private Feed feed;
 
	@GET
	@Status(200)
	@Consumes("application/atom+xml")
	public void build(Feed feed) {
		this.feed = feed;
	}
 
	public String getFeedTitle() {
		return this.feed.getTitle();
	}
}

Example for using the getFeedTitle() method:

public void main(String args[]) {
	URI uri = URI.create("http://example.org/blogs/jim/entries");
	Client client = new Client();
 
	CollectionView cv = client.view(uri, CollectionView.class);
	System.out.println("Feed title is " + cv.getFeedTitle());
}

The third purpose of view classes mentioned above is to provide users (human or machine) with a means to activate the controls embedded in the response entities. RFC 5005 defines (among others) the ‘next’ link relation that can be used to tell a consumer of the feed document where the next page of the feed representation is located. We will use this link relation to demonstrate how a view class can expose a hypermedia control to the user.

One possibility to make ‘next’ links accessible to the user is to provide some getNextPageUri() method on the view class that can be called by the user to retrieve the URI of the next page. However, we can also provide a design that matches better the usual intent of the user of a feed: to iterate over the contained entries.

The code below shows an iterateEntries() method that processes all entries in the feed document of the view and follows any ‘next’ link to subsequent feed pages. The EntryHandler interface acts as a callback class.

public interface EntryHandler {
 
	public boolean handleEntry(Entry e);
 
}

public class CollectionView {
 
	private Client client;
	private Feed feed;
 
	@GET
	@Status(200)
	@Consumes("application/atom+xml")
	public void build(Feed feed, @Context Client client) {
		this.client = client;
		this.feed = feed;
	}
 
	public String getFeedTitle() {
		return this.feed.getTitle();
	}
 
	public void iterateEntries(EntryHandler entryHandler) {
 
		List<Entry> entries = this.feed.getEntries();
		for (Entry entry : entries) {
			boolean proceed = entryHandler.handleEntry(entry);
			if (!proceed) {
				return;
			}
		}
 
		Link link = this.feed.getLink("next");
		if (link == null) {
			return;
		}
 
		URI nextUri = link.getHref().toURI();
		CollectionView v = this.client.view(nextUri, CollectionView.class);
 
		v.iterateEntries(entryHandler);
	}
 
}

Note that we have added an annotated parameter to the build method to inject the client:

public void build(Feed feed, @Context Client client) {

This is necessary because the iterateEntries() method constructs a view for the next page if a ‘next’-link is found.

The CollectionView class can now be used to iterate over all entries in a feed as follows:

public void main(String args[]) {
	URI uri = URI.create("http://example.org/blogs/jim/entries");
	Client client = new Client();
 
	CollectionView cv = client.view(uri, CollectionView.class);
 
	 cv.iterateEntries(new EntryHandler() {
 
		private int count = 0;
 
		public boolean handleEntry(Entry entry) {
			this.count++;
			System.out.println("Entry #" + this.count + ": " + entry.getTitle());
 
			// limit the number of processed entries to 200
			return (this.count <= 200);
		}
	});
 
}

(You can find a similar example in the Jersey sources at experimental/view-client/jersey-view-client-samples/atompub-simple-view-client-sample)

The CollectionView example class demonstrates the three purposes of a view:

• Handle HTTP responses
• Present or make accessible application state
• Provide a means for the user to activate hypermedia controls

Interactions with resources never occur without assumptions about the resources (for example that it is a Web page, an image or an Atom Publishing Protocol collection). View classes are manifestations of such assumptions and the choice of a specific view class for a given interaction expresses which assumptions are being made.

From a code structuring and maintenance perspective view classes nicely bundle up all the elements that pertain to such assumptions and act as a single point of documentation.

There are a number of issues we have not covered in this first blog. Among them are

• Support for several response body media types
• Error handling
• Constructing requests other than GET
• Performing a sequence of automated requests
• Using ‘existing’ client side classes as view classes

We will talk about those and other features in follow up postings.

Instructions for Obtaining the Code

Unfortunately there are currently issues obtaining the latest SNAPSHOT artifacts from the java.net maven repository. Until this is resolved it is necessary to obtain and build Jersey yourself. The new client side framework is located in experimental/view-client.

Use SE 6 with maven version 2.2.0 or 2.2.1.

Join the Jersey project as an Observer at https://jersey.dev.java.net.

Check out the trunk source:


svn checkout \
https://jersey.dev.java.net/svn/jersey/trunk/jersey \
jersey --username <username>


Clean and install:

mvn clean install

If you want to do this a bit quicker you can skip the tests

mvn -Dmaven.test.skip=true clean install

You may need to set the following maven options (which can be set using the MAVEN_OPTS environment variable):

-Xmx1048m -XX:PermSize=64M -XX:MaxPermSize=128M

Discussion

Please send comments to the jersey users list.