Chapter 20. MVC Templates

There is no need to use Viewable every time you want to bind a model to a template. To make the resource method more readable (and to avoid verbose wrapping of a template reference and model into Viewable) you can simply annotate a resource method with @Template annotation. An updated example, using @Template, from previous section is shown in Example 20.2, “Using @Template on a resource method” example.

package com.example;

@Path("foo")
public class Foo {

    @GET
    @Template(name = "index.foo")
    public String get() {
        return "FOO";
    }
}

In this example, the Foo JAX-RS resource class is still the controller as in previous section but the MVC model is now represented by the return value of annotated resource method.

The processing of such a method is then essentially the same as if the return type of the method was an instance of the Viewable class. If a method is annotated with @Template and is also returning a Viewable instance then the values from the Viewable instance take precedence over those defined in the annotation. Producible media types are for both cases, Viewable and @Template, determined by the method or class level @Produces annotation.

A resource class can have templates implicitly associated with it via @Template annotation. For example, take a look at the resource class listing in Example 20.3, “Using @Template on a resource class”.

@Path("foo")
@Template
public class Foo {

    public String getFoo() {
        return "FOO";
    }
}

The example relies on Jersey MVC conventions a lot and requires more explanation as such. First of all, you may have noticed that there is no resource method defined in this JAX-RS resource. Also, there is no template reference defined. In this case, since the @Template annotation placed on the resource class does not contain any information, the default relative template reference index will be used (for more on this topic see Section 20.3, “Absolute vs. Relative template reference”). As for the missing resource methods, a default @GET method will be automatically generated by Jersey for the Foo resource (which is the MVC Controller now). The implementation of the generated resource method performs the equivalent of the following explicit resource method:

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

You can see that the resource class serves in this case also as the model. Producible media types are determined based on the @Produces annotation declared on the resource class, if any.

In the following example, the MVC controller represented by a JAX-RS @GET sub-resource method, is also generated in the resource class annotated with @Template:

@GET
@Path("{implicit-view-path-parameter}")
public Viewable get(@PathParameter("{implicit-view-path-parameter}") String template) {
    return new Viewable(template, this);
}

This allows Jersey to support also implicit sub-resource templates. For example, a JAX-RS resource at path foo/bar will try to use relative template reference bar that resolves to an absolute template reference /com/foo/Foo/bar.

In other words, a HTTP GET request to a /foo/bar would be handled by this auto-generated method in the Foo resource and would delegate the request to a registered template processor supports processing of the absolute template reference /com/foo/Foo/bar, where the model is still an instance of the same JAX-RS resource class Foo.

Relative reference is any path that does not start with a leading '/' (slash) character (i.e. index.foo). This kind of references is resolved into absolute ones by pre-pending a given value with a fully qualified name of the last matched resource.

Consider the Example 20.3, “Using @Template on a resource class” from the previous section, the template name reference index is a relative value that Jersey will resolve to its absolute template reference using a fully qualified class name of Foo (more on resolving relative template name to the absolute one can be found in the JavaDoc of Viewable class), which, in our case, is:

"/com/foo/Foo/index"

Jersey will then search all the registered template processors (see Section 20.7, “Writing Custom Templating Engines”) to find a template processor that can resolve the absolute template reference further to a "processable" template reference. If a template processor is found then the "processable" template is processed using the supplied data model.

Let's change the resource GET method in our Foo resource a little:

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

In this case, since the template reference begins with "/", Jersey will consider the reference to be absolute already and will not attempt to absolutize it again. The reference will be used "as is" when resolving it to a "processable" template reference as described earlier.

Absolute template references start with leading '/' (i.e. /com/example/index.foo) character and are not further resolved (with respect to the resolving resource class) which means that the template is looked for at the provided path directly.

Note, however, that template processors for custom templating engines may modify (and the supported ones do) absolute template reference by pre-pending 'base template path' (if defined) and appending template suffix (i.e. foo) if the suffix is not provided in the reference.

For example assume that we want to use Mustache templates for our views and we have defined 'base template path' as pages. For the absolute template reference /com/example/Foo/index the template processor will transform the reference into the following path: /pages/com/example/Foo/index.mustache.

@ErrorTemplate can be used in also with Bean Validation to display specific error pages in case the validation of input/output values fails for some reason. Everything works as described above except the model is not the thrown exception but rather a list of ValidationErrors. This list can be iterated in the template and all the validation errors can be shown to the user in a desirable way.

@POST
@Produces({"text/html”})
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
@Template(name = "/short-link”) @ErrorTemplate(name = "/error-form")
@Valid
public ShortenedLink createLink(@NotEmpty @FormParam("link") final String link) {
    // ...
}

<c:forEach items="${model}" var="error">
    ${error.message} "<strong>${error.invalidValue}</strong>"<br/>
</c:forEach>

Support for Bean Validation in Jersey MVC Templates is provided by a jersey-mvc-bean-validation extension module. The JAX-RS Feature provided by this module (MvcBeanValidationFeature) has to be registered in order to use this functionality (see Section 20.5, “Registration and Configuration”).

Maven users can find this module at coordinates

<dependency>
    <groupId>org.glassfish.jersey.ext</groupId>
    <artifactId>jersey-mvc-bean-validation</artifactId>
    <version>2.29.1</version>
</dependency>

and for non-Maven users the list of dependencies is available at jersey-mvc-bean-validation.

An integration module for Mustache-based templating engine.

Mustache template processor resolves absolute template references to processable template references represented as Mustache templates as follows:

Thus the absolute template reference /com/foo/Foo/index would be resolved as /com/foo/Foo/index.mustache, provided there exists a /com/foo/Foo/index.mustache Mustache template in the application.

Available configuration properties:

Maven users can find this module at coordinates

<dependency>
    <groupId>org.glassfish.jersey.ext</groupId>
    <artifactId>jersey-mvc-mustache</artifactId>
    <version>2.29.1</version>
</dependency>

and for non-Maven users the list of dependencies is available at jersey-mvc-mustache.

An integration module for Freemarker-based templating engine.

Freemarker template processor resolves absolute template references to processable template references represented as Freemarker templates as follows:

Thus the absolute template reference /com/foo/Foo/index would be resolved to /com/foo/Foo/index.ftl, provided there exists a /com/foo/Foo/index.ftl Freemarker template in the application.

Jersey will assign the model instance to an attribute named model. So it is possible to reference the foo key from the provided Map (MVC Model) resource from the Freemarker template as follows:

<h1>${model.foo}</h1>

Available configuration properties:

Maven users can find this module at coordinates

<dependency>
    <groupId>org.glassfish.jersey.ext</groupId>
    <artifactId>jersey-mvc-freemarker</artifactId>
    <version>2.29.1</version>
</dependency>

and for non-Maven users the list of dependencies is available at jersey-mvc-freemarker.

An integration module for JSP-based templating engine.

JSP template processor resolves absolute template references to processable template references represented as JSP pages as follows:

Thus the absolute template reference /com/foo/Foo/index would be resolved to /com/foo/Foo/index.jsp, provided there exists a /com/foo/Foo/index.jsp JSP page in the web application.

Jersey will assign the model instance to the attribute named model or it. So it is possible to reference the foo property on the Foo resource from the JSP template as follows:

<h1>${model.foo}</h1>

or

<h1>${it.foo}</h1>

To include another JSP page in the currently processed one a custom include tag can be used. Mandatory parameter page represents a relative template name which would be absolutized using the same resolving resource class as the parent JSP page template.

<%@page contentType="text/html"%>
<%@page pageEncoding="UTF-8"%>

<%@taglib prefix="rbt" uri="urn:org:glassfish:jersey:servlet:mvc" %>

<html>
    <body>

    <rbt:include page="include.jsp"/>

    </body>
</html>

Available configuration properties:

Maven users can find this module at coordinates

<dependency>
    <groupId>org.glassfish.jersey.ext</groupId>
    <artifactId>jersey-mvc-jsp</artifactId>
    <version>2.29.1</version>
</dependency>

and for non-Maven users the list of dependencies is available at jersey-mvc-jsp.