SeamFramework.orgCommunity Documentation

Chapter 4. Templating support

4.1. Creating JAX-RS responses using templates
4.1.1. Accessing the model
4.2. Built-in support for templating engines
4.2.1. FreeMarker
4.2.2. Apache Velocity
4.2.3. Pluggable support for templating engines
4.2.4. Selecting preferred templating engine

Seam REST allows to create HTTP responses based on the defined templates. Instead of being bound to a particular templating engine, Seam REST comes with a support for multiple templating engines and support for others can be plugged in.

REST-based web services are often expected to return multiple representations of a resource. The templating support is useful for producing media formats such as XHTML and it can be also used instead of JAXB to produce domain-specific XML representations of a resource. Besides, almost any other representation of a resource can be described in a template.

To enable templating for a particular method, decorate the method with the @ResponseTemplate annotation. Path to a template file to be used for rendering is required.

The @ResponseTemplate annotation offers several other options. For example, it is possible for a method to offer multiple representations of a resource, each rendered with a different template. In the example below, the produces member of the @ResponseTemplate annotation is used to distinguish between produced media types.

There are several ways of accessing the domain data within a template.

Firstly, the object returned by the JAX-RS method is available under the "response" name by default. The object can be made available under a different name using the responseName member of the @ResponseTemplate annotation.

Secondly, every bean reachable via an EL expression is available within a template.


Note that the syntax of the expression depends on the particular templating engine and mostly differs from the syntax of EL expressions. For example, ${university.students} must be used instead of #{university.students} in a FreeMarker template.

Last but not least, the model can be populated programmatically. In order to do that, inject the TemplatingModel bean and put the desired objects into the underlying data map. In the following example, the list of professors is available under the "professors" name.

Seam REST currently comes with built-in templating providers for FreeMarker and Apache Velocity.