Representation builder

What is a representation

Kauri has a flexible system for producing resource representations. For developer's familiar with other frameworks, this is similar to what is often called the "view", the V in the MVC pattern.

Here is a nice description of what a representation is:

"REST components perform actions on a resource by using a representation to capture the current or intended state of that resource and transferring that representation between components. A representation is a sequence of bytes, plus representation metadata to describe those bytes. Other commonly used but less precise names for a representation include: document, file, and HTTP message entity, instance, or variant." (Fielding)

So for example, a representation is both the HTML page transferred to your browser when doing a GET request, as well as the body of a form posted towards the server.

The representation builder system described here focuses on the production of representations served towards the client, and not handling of representations submitted towards the server.

The need for a representation builder module

In the core Restlet API, a resource class is responsible for creating the response representation and setting it on the response object. This is done by creating an instance of a subclass of Representation.

For very simple and very complex cases, it makes sense to do this directly in the resource class. In a typical web application, you will often produce representations using a template. In Kauri, this means the resource class should have a handle to (= dependency on) the TemplateService and use that to create a TemplateRepresentation.

This works just fine. However, it is a very 'manual', hardcoded and somewhat laborous way of constructing the representation. It would be easier if the resource class only needs to return a logical representation name and the data objects. The mapping of the logical name to the real implementation can than be done somewhere else, outside of the concern of the resource class. And this is exactly what Kauri's representation module provides.

For people familiar with Spring MVC, this is similar to the ModelAndView and the ViewResolver. For people familiar with Apache Cocoon, this is similar to the sendPage call. For people familiar with JAX-RS, this is somewhat the same role as the MessageBodyWriter providers.