Foo is the controller, and when the method get is invoked, it returns the model "FOO" and a reference to the view (the template) "index", both of which are encapsulated in the Viewable instance.

The template reference "index" is a relative so Jersey will resolve it to an absolute template reference, using the fully qualified class name of Foo, to the following:

"/com/foo/Foo/index"

Then Jersey will search the registered template processors (more detail on this later) to find a template processor that can resolve it further to a processable template reference. If a template processor is found then the processable template is processed using the model.

If instead the get method is as follows:

@GET public Viewable get() { return new Viewable("/index", "FOO") }

Jersey will not resolve the template reference as it is considered resolved, since it begins with "/". The reference will however be resolved to a processable template reference as previously described.

All HTTP methods may return Viewable instances. Thus a POST method may return a template reference to a template that produces a view that is the result of processing a form.

Implicit MVC

A resource class can have templates implicitly associated (this is the style used by Hudson). For example, given the following resource class:

if there exists a template reference "index" that resolves to an absolute template reference "/com/foo/Foo/index" that in turn resolves to a processable template reference then a @GET method will be implicitly added to the Foo controller that performs the equivalent of the following explicit resource method:

@GET public Viewable get() { return new Viewable("index", this) }

Notice that the model is the controller. In this case the template reference "index" is special, it is the template reference associated with the controller itself.

Implicit sub-resources are also allowed, for example, if there is a template reference "bar" that resolves to an absolute template reference "/com/foo/Foo/bar" that in turn resolves to a processable
template reference then a @GET method will be implicitly added to the
Foo controller that performs the equivalent of the following explicit sub-resource method:

If using the class or package scanning techniques then such a provider will get automatically registered. In addition such a component can be managed by a registered IoC framework and injection of standard JAX-RS and Jersey components is possible.

If i recall correctly (from the Jersey users list) a developer successfully plugged in Freemarker support in a couple lines in addition to supporting JAXB to XSLT translations. One interesting aspect of using template engines such as Freemarker or Velocity is it is possible to write a set of resource classes that provide their own templates, thus potentially allowing easy way to plug-in extensions to a web application (ala the Hudson style).

When writing template processors it is recommend that you use an appropriate unique suffix for the processable
template references. Then it is possible to easily intermix multiple template processors without any conflict.

The implementation of the JSP template processor is presented at the end of this blog entry.

Sounds interesting. How are content-types related to views? I only skimmed through the Jersey docs, so I might have missed the important piece, but I got the impression that template processors are not selected with taking the content-type or to content negotiation into account, right? I actually expected to have an MVC-like approach underlying to abstract representations for all methods. But it seems that resources have to be annotated in a hard-coded fashion with the mime-types it can produce and/or consume. Is this really the best way to implement RESTful services?

In my understanding of REST, resources are independent of their representation/rendering, i.e. they are so to say normalized and can be rendered into all kind of representation. In Java such a normalized resource could be simply a object, and it could be up to the view layer to decide which processor should render the representation. This way resources are decoupled from representations and representation processors can be added like plugins later in the development process. Such a processor has of course to be capable of a bi-directional transformation (marshalling/unmarshalling). That way, GET and PUT are always idempotent, even if a GET has returned another representation as the PUT received, as long as the state information has been the same. Imagine requesting the state of resource in JSON but updating its state with XML. The same applies to POST, the processor translates the request into the normalized format that can then be used to create a resource, etc.

So, am I reinventing the wheel and it's already there? Otherwise I think this is a more flexible/extensible way to map resources to java methods (using an MVC approach). What do you think?

I should of mentioned that the template processing depends on another layer of MVC (that is not template oriented that most people might understand in terms of Web applications), using the MessageBodyWriter, a standard JAX-RS interface, that operates given a media type and a Java type (in the case of templates that is the Viewable type). A template processor operates given a template reference and a model (see later on media type).

It is possible say for a resource method to return a JAXB bean that may be serialized as XML, JSON or FastInfoset as determined by the @ProduceMime on the resource method, one or more MessageBodyWriter's annotated with @ProduceMime, and when the client makes a request what it declares is are media types for the returned representation, using the Accept header. (The same is possible the other way using @ConsumeMime and MessageBodyReader).

The @ProduceMime acts as an identifier for the method selection mechanism, an identifier to select a MessageBodyWriter, and also for the runtime to determine that nothing is acceptable and it should return a 406 (Not Acceptable) response. Further this information is really useful for creating documentation and machine processable representations like WADL.

In reality resources will only implement a set of supported representations. Using @ProduceMime does not really hard-code things, it can be modified, new resource methods added as and when use-cases require it (one can also support things dynamically if need be). When implementing a service you need to ask "what media types will i support?", and the use of certain Java types will also depend on this (e.g. JAXB beans or Abdera Atom types etc). The important thing is whether you can modify and adapt the resources to support new requirements as and when required. IMHO with JAX-RS this is possible when using @ProduceMime.

In terms of explicit/implicit MVC with media types, it is something i need to work on. I think it is a matter of allowing @ProduceMime on the template processor to declare what media types it produces (just like MessageBodyWriter). This requirement has been less pressing as the motivation has been focused around templates that produce (X)HTML.

Thank you for this blog post, it helps a lot understanding what happens with the TemplateProcessor.

What I still don't get is why a specific TemplateProcessor is used. I can see in the source code that the JSPTemplateProcessor is added to the Singletons list, in the configuration bean, but I don't understand why (for instance, if I would like to replace the JSPTemplateProcessor by my implementation).

What I would like to do is to add a prefix to the resolved path for JSP: I really would like to put my JSP in WEB-INF/jsp/, so that it wouldn't be accessible directly by users. Is there a simple way to do this, instead of explicitly returning Viewable ?