Skip navigation

Seam REST 3.0.0.Alpha3

Posted by jharting Jan 21, 2011

Seam REST 3.0.0.Alpha3 has been released. This is the last stop before moving to the Beta phase. Thus, the main focus is now on stabilizing the API.

What's new?


The Seam Catch integration has been finished. See my previous blog post or the reference documentation for how to handle exceptions using Seam Catch.


The API for declarative exception mapping has changed. We have dropped the support for configuration through ExceptionMapping objects and switched to annotation-based configuration.

   @ExceptionMapping(exceptionType = NoResultException.class, status = 404,
          message = "Requested resource does not exist."),
   @ExceptionMapping(exceptionType = IllegalArgumentException.class, status = 400,
          message = "Illegal argument value.")
public MyApplication extends Application {



In addition, the API for validation of JAX-RS method parameters has also changed to comply with convention. From now on, the entity body parameter is validated by default. Other parameters (such as parameter objects) can be added to the validation process by using the @Valid annotation.

public void post(Task task, @Valid @Form MyForm form)


Try it now!


[Combined JAR]  [Distribution]  [JIRA]  [API docs]  [Reference guide]  [Release Notes]

Just in time for holidays, Seam REST 3.0.0.Alpha2 was released. It's been a while since Alpha1 and therefore this release brings a lot of new features.

Seam Catch integration

Seam Catch provides an infrastructure for robust and unified exception processing. When both Catch and REST modules are deployed, Seam REST hooks into the JAX-RS runtime and catches unhandled exceptions. Subsequently, these exceptions are routed through Catch and can be handled using the Catch handler methods.


public void handleException(@Handles @RestRequest CaughtException<NoResultException> event,
   @RestResource Builder builder)
   builder.status(404).entity("The requested resource does not exist.");



With the @RestRequest qualifier, exceptions can be filtered based on their origin (e.g. NoResultException that occurs during JAX-RS invocation will be handled by this method while an exception of the same type that is thrown within JSF processing will not.)


The @RestResource enables resources like Response or ResponseBuilder, which are needed to handle the exception, to be injected.


RESTEasy Client framework integration

The RESTEasy Client Framework is a framework for writing clients for REST-based web services. It reuses JAX-RS metadata for creating HTTP requests. Take the following interface as an example:


public interface TaskService
    Task getTask(@PathParam("id") long id);

The interface describes a remote JAX-RS service. With Seam REST, it is possible to simply @Inject a client for this service without implementing the interface:


@Inject @RestClient("")
private TaskService taskService;


Task task = taskService.getTask(1);


RESTEasy takes care of proxying the interface. Every method invocation on the interface is translated to an HTTP request and sent to the server. RESTEasy also converts the HTTP response to a Java object.


Integration with the RESTEasy Client Framework is optional and only available when RESTEasy is available on classpath.


Templating support

Seam REST allows HTTP responses to be created using templates. Instead of being bound to a particlar templating engine, Seam REST comes with support for multiple templating engines and support for others can be plugged in.


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.


public Task getTask(@PathParam("taskId") long taskId) {


The template can be written in various templating engine's formats. Seam REST comes with support for FreeMarker and Apache Velocity. An SPI for extending the set of suported templating engines is provided.


What makes Seam REST's templating support even more interesting is that you can use EL names within the templates. Therefore, there is no need for an extra effort to make your objects reachable from within the template.

Migration to Seam Solder

The Weld Extensions project has been renamed to Seam Solder recently. Seam REST has been migrated to Seam Solder.


What's next?

For the next release, we are going to focus on:

  • overal stability and code cleanup improvements
  • completing documentation and examples
  • improving Bean Validation integration [SEAMREST-9]
  • and more...


Check it out


[Combined JAR] [Distribution] [JIRA] [API docs] [Reference guide] [Release Notes]

Seam REST is a lightweight module that provides additions to the Java API for RESTful web services (JAX-RS) such as further integration within the Java EE platform as well as integration with third-party technologies. Seam REST is independent of CDI and JAX-RS implementations and thus fully portable between Java EE 6 environments.


Declarative exception mapping

Occasionally, an exception may occur during invocation of a JAX-RS web service. The Seam REST module provides an elegant way of dealing with exceptions. The following xml snippet shows how an exception type can be mapped to an HTTP response:


            <rest:ExceptionMapping exceptionType="javax.persistence.NoResultException" statusCode="404">
                <rest:message>Requested resource does not exist.</rest:message>
            <rest:ExceptionMapping exceptionType="java.lang.IllegalArgumentException" statusCode="400">
                <rest:message>Illegal parameter value.</rest:message>


As a result, the following HTTP response is returned when the NoResultException appears:


HTTP/1.1 404 Not Found
Content-Type: application/xml
Content-Length: 123

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <message>Requested resource does not exist.</message>


Bean Validation integration

Bean Validation (JSR-303) is a specification introduced as a part of Java EE 6. It aims to provide a standardized way of validating the domain model across all application layers. The Seam REST module integrates with the Bean Validation specification. This allows message bodies of HTTP requests to be validated using this standardized mechanism.


public class Task {
    @Size(min = 1, max = 100)
    private String name;


The validation is triggered by annotating the JAX-RS method or class with the @ValidateRequest annotation.


public void updateTask(Task incommingTask)


By default, the message body (the parameter with no annotations) is validated. If the object is valid, the web service method is executed. Otherwise, the ValidationException exception is thrown.


The ValidationException exception is a simple carrier of constraint violations found by the Bean Validation provider. The exception can be handled by an ExceptionMapper .


Seam REST comes with a built-in ValidationExceptionMapper which is registered by default. The exception mapper converts the ValidationException to an HTTP response with 400 (Bad request) status code. Furthermore, messages relevant to the violated constraints are sent within the message body of the HTTP response.


HTTP/1.1 400 Bad Request
Content-Type: application/xml
Content-Length: 129

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
            <message>Name length must be between 1 and 100.</message>


Furthermore, it is possible to explicitly select the validation group to be used for validation and thus use multiple set of constraints for the domain model.


@ValidateRequest(groups = PartialUpdateGroup.class)


Check it out!

The easiest way to get started is to check out the documentation and pull the bits from the jboss maven repository.




The distribution package is available as well. If you find a bug or miss a feature, feel free to report it in the Seam REST JIRA project.


Future plans

The main areas to work on for future releases are:

  • Further Bean Validation integration
  • Better client support for consuming remote web services
  • Response templating

Filter Blog