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.List({
   @ExceptionMapping(exceptionType = NoResultException.class, status = 404,
          message = "Requested resource does not exist."),
   @ExceptionMapping(exceptionType = IllegalArgumentException.class, status = 400,
          message = "Illegal argument value.")
})
@ApplicationPath("/api")
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.

@POST
@Path("/myservice")
@ValidateRequest
public void post(Task task, @Valid @Form MyForm form)

Try it now!

[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:exceptionMappings>
        <s:value>
            <rest:ExceptionMapping exceptionType="javax.persistence.NoResultException" statusCode="404">
                <rest:message>Requested resource does not exist.</rest:message>
            </rest:ExceptionMapping>
        </s:value>
        <s:value>
            <rest:ExceptionMapping exceptionType="java.lang.IllegalArgumentException" statusCode="400">
                <rest:message>Illegal parameter value.</rest:message>
            </rest:ExceptionMapping>
        </s:value>
</rest:exceptionMappings>

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"?>
<error>
    <message>Requested resource does not exist.</message>
</error>

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 {
    @NotNull
    @Size(min = 1, max = 100)
    private String name;
...
}

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

@PUT
@ValidateRequest
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"?>
<error>
    <messages>
            <message>Name length must be between 1 and 100.</message>
    </messages>
</error>

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.

<dependency>
    <groupId>org.jboss.seam.rest</groupId>
    <artifactId>seam-rest</artifactId>
    <version>3.0.0.Alpha1</version>
</dependency>

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