Integrating JBoss RESTEasy and Spring MVC

• Controller - Controlling the flow between the HTTP request, the Model and the View
  • ContactsResource.java - a RESTful Controller with JAX-RS annotations and some traditional HTML controller methods. It will be annotated with Spring's @Controller and @Autowired annotations as well.

• Model - the domain model and service objects in our case. In our case, we have 2 domain objects: Contact and Contacts; and 1 Service object: ContractService

  • Contact.java - a JAXB domain object with contact information
  • Contacts.java - a JAXB wrapper object that wraps a Contact List
  • ContactService.java - a Map based repository of Contact instances

• View - How the domain model is transformed for consumer use. JAX-RS performs automated conversion to XML based on annotations on our domain model. We'll be using JSP for object to HTML conversion.

  • contacts.jsp - a bare bones HTML view of our Contacts
• Test - JAX-RS provides quite a bit of functionality, we're writing quite a bit of code, and all of that is wrapped in quite a bit of configuration. This article will focus on testing our code, configuration and deployment in an automated JUnit test.
  • ContractTest.java - a RESTEasy ReSTful Unit test for the ContractsResource functionality, embedded server included

Core RESTEasy/Spring MVC artifacts

web.xml

Spring MVC's entry point is the DispatcherServlet. There are two parts in setting up the DispatcherServlet, the first is to map the servlet to the URL pattern which must follow the rules specified in Section 11.2 of Servlet API Specification. The next step is configure the behavior of the the servlet by providing the configuration file which we call 'springmvc-servlet.xml'. By default, DispatcherServlet looks for a configuration file at "WEB-INF/{servlet-name}-servlet.xml" to find it's configuration, but we're going to use a Spring configuration from the classpath so that the configuration can be reused later in our junit test case.

<?xml version="1.0"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
        "http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>

    <servlet>
        <servlet-name>springmvc</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <init-param>
            <param-name>contextConfigLocation</param-name>
            <param-value>classpath:springmvc-servlet.xml</param-value>
        </init-param>
    </servlet>

    <servlet-mapping>
        <servlet-name>springmvc</servlet-name>
        <url-pattern>/contacts/*</url-pattern>
    </servlet-mapping>

 

<web-app>

All requests will be forwarded to the Spring MVC DispatcherServlet. One can get much more sophisticated, but this is one of the simplest simplest web.xml you can create to integrate with Spring. Note that there isn't any reference here to a RESTEasy servlet. Other JAX-RS/Spring integrations require you to have an implementation specific Servlet to serve XML or JSon and a separate Spring MVC DispatcherServlet mapping to server HTML requests. RESTEasy integrates with DispatcherServlet to allow Spring MVC to direct the URL to either RESTEasy Resources or Spring MVC Controllers.

Next, let's take a look at the Spring MVC configuration.

springmvc-servlet.xml

In our basic project, there are five things we need to do in the springmvc-servlet.xml file.

1. Register the Spring <context/> namespace
2. Register the package(s) to scan for Spring MVC annotations.
3. Configure the context annotation processor.
4. Import the springmvc-resteasy.xml configuration file which specifies the default RESTEasy/Spring MVC integration Spring beans.
5. Configure the ViewResolver bean to configure the presentation layer to use JSP.

Let's inspect the springmvc-servlet.xml file and focus on each of the above items. The springmvc-servlet.xml file itself is pretty short and shows off some of the features from Spring 2.5:

<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:context="http://www.springframework.org/schema/context"
  xsi:schemaLocation="
        http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-2.5.xsd
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">
  <context:component-scan base-package="org.jboss.resteasy.examples.springmvc" />
  <context:annotation-config />
  <import resource="classpath:springmvc-resteasy.xml" />
  <bean id="viewResolver"
    class="org.springframework.web.servlet.view.InternalResourceViewResolver">
    <property name="viewClass" value="org.springframework.web.servlet.view.JstlView" />
    <property name="prefix" value="/WEB-INF/" />
    <property name="suffix" value=".jsp" />
  </bean>
</beans>

Demystifying the Spring Configuration

Spring allows for custom namespaces to reduce the verbosity of the configuration files. We make use of the <context/> namepsace by registering it in lines 3 and 4. Line 6 (component-scan) informs spring about which package(s) we want to scan and create the custom component object instances, such as controllers and service objects. We tell Spring about the packages we're interested in by using the <context:component-scan/> custom namespace and set the base-package attribute with the packages we're interested in (org.jboss.resteasy.examples.springmvc ). Later on, you'll see that we're going to be using two Spring annotations that allow the Spring runtime to glean Dependency Management information directly from the object itself: @Controller and @Service. 

Line 7 (annotation-config) tells Spring that our application will be using annotations on how to configure the beans created by the (component-scan) operation of line 6. Spring looks for annotations such as Spring's @Autowired and @Required; JEE's @Resource; and JPA's @PersistenceContext and @PersistenceUnit to describe dependencies between bean instances. annotation-configSpring also looks for life-cycle annotations such as JSR 250's @PostConstruct and @PreDestroy. Our environment requires a dependency between our Controller and Service objects, and the annotation-config declaration will assist us to configure that relationship in Java code.

Lines 9-14 tell Spring how we intend to handle the rendering of our presentation layer. In our case, we want to use JSTL views that translate view names (such as "contact") to a JSP page found in the /WEB-INF/ directory (specifically /WEB-INF/contacts.jsp in our case). For more information about setting up Spring views, take a look at the spring documentation.

Next, let's take a look at how you can mix and match Spring and JAX-RS annotations in a Controller/Resource.

ContactsResource.java

MVC Controllers control the flow between the Model and the View. Resource is REST's equivalent to Controllers, and we'll be using the term Resource and Controller interchangably. In our case, our resource handles requests to /contracts and /contracts/{id}. Our ContractsResource must perform quite a few functions on those two URL templates:

• Retrieve all Contacts - Display the results in either HTML, XML or JSon. For clarity, we'll break out the data oriented functionality (XML and JSon) from the user oriented functionality (HTML) into two distinct URLs - /contacts for HTML and /contacts/data for XML and JSon. REST allows a client to select which format it prefers to receive the data in through a process called Content Negotiation. Content Negotiation can happen through HTTP headers, URI or query parameters. Our ContractsResource will use different URIs to differentiate between data oriented and user views, and will use HTTP headers to differentiate between XML and JSon data views.
• Save a Contact - Create or Updating data is a pretty standard requirement. The Save a Contact functionality mirrors the Content Negotiation needs of Retrieve all Contacts. User oriented data exchange comes in the form of HTML form data, and data oriented exchange usually occurs in XML and JSon. These differing requirements require ContractResource to have two distinct JAX-RS Java methods; we'll also separate the URLs for clarity purposes.
• View a Contact - We'll create a single view for viewing a single contact that returns XML or JSon. We leave the user oriented view as an exercise for the reader.

Here's another view of our requirements:

Note that we mixed and matched HTML and data oriented functionality in this requirement. Now that we have our requirements in place, let's take a look at the ContactsResource code. There are quite a few new Spring and JAX-RS annotations which we'll explain right after the code:

@Controller
@Path(ContactsResource.CONTACTS_URL)
public class ContactsResource
{
  public static final String CONTACTS_URL = "/contacts";
  @Autowired
  ContactService service;

  @GET
  @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
  @Path("data")
  public Contacts getAll() {
    return service.getAll();
  }

  @GET
  @Produces(MediaType.TEXT_HTML)
  public ModelAndView viewAll() {
    // forward to the "contacts" view, with a request attribute named
    // "contacts" that has all of the existing contacts
    return new ModelAndView("contacts", "contacts", service.getAll());
  }

  @PUT
  @POST
  @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
  @Path("data")
  public Response saveContact(@Context UriInfo uri, Contact contact)
      throws URISyntaxException {
    service.save(contact);
    URI newURI = UriBuilder.fromUri(uri.getPath()).path(contact.getLastName()).build();
    return Response.created(newURI).build();
  }

  @POST
  @PUT
  @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
  @Produces(MediaType.TEXT_HTML)
  public ModelAndView saveContactForm(@Form Contact contact)
      throws URISyntaxException {
    service.save(contact);
    return viewAll();
  }

  @GET
  @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
  @Path("data/{lastName}")
  public Contact get(@PathParam("lastName") String lastName) {
    return service.getContact(lastName);
  }
}

@Service
public class ContactService
{
   private Map<String, Contact> contactMap = new ConcurrentHashMap<String, Contact>();

   public void save(Contact contact){ contactMap.put(contact.getLastName(), contact); }
   public Contact getContact(String lastName){ return contactMap.get(lastName); }
   public Contacts getAll() { return new Contacts(contactMap.values()); }
}

• Notice the use of Spring's @Service annotation. Do you remember the component-scan directive that was used in the Spring configuration section? The combination of the directive and the annotation tell Spring that a singleton instance of ContractService must be created at startup. Spring has a more generic @Component, but the use of @Service allows for more precise definition of bean usage and also allows for future upgrades that involve AoP to create more precise targeting.
• Notice the use of ConcurrentHashMap. It's a JDK 1.5 addition that adds performance in multi-threaded environments. It's an easy way to boost performance in distributed REST applications

contacts.jsp

We've explored the Model and Controller aspects of MVC. The last piece to the puzzle is the View. Most JAX-RS based interactions perform a more automated conversion of objects like our Contact to a data-oriented view, such as XML or JSon. Traditionally, Java EE MVC has been done with a more manual View management with languages such as JSP. Our JSP will take a Contracts instance created in ContractsResources.viewAll() and render it in basic HTML:

<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>
<html>
<body>
  <h2>Hello Contacts!</h2>
  <div id="contact-data" class="contacts">
    <c:forEach var="contact" items="${contacts.contacts}">
      <span class="contact">Hello <a href="/contacts/data/${contact.lastName}">${contact.firstName} ${contact.lastName}</a></span>
    </c:forEach>
  </div>

  <p>Save a contact, save the world:</p> 
  <form action="/contacts" method="post">
    First Name: <input type="text" name="firstName" /><br>
    Last Name: <input type="text" name="lastName" /><br>
    <input type="submit" value="submit"/>
  </form>
</body>
</html>

This JSP loops over all contacts and adds links to their data-oriented View. It also creates a simple HTML form for creating a new Contact. While this JSP is simple, it will help us exercise three of our ContactsResource Controller: viewAll(), .saveContactForm(), and get(). It could also be a spring board for more complicated AJAX/JSon interaction, but that's beyond the scope of this article.

The code and configuration is now complete, so let's run this project!

Jetty

Running Jetty is rather simple. You've seen most of the details of the pom.xml when we previously discussed it. Running jetty through maven involves running the following command:

mvn jetty:run

That command will launch Jetty, and allow you to browse our project at http://localhost:8080/contacts. Add a few contacts, and view them either as a group at /contacts in HTML, as a group in XML at /contact/data, or individually as XML by following the links found at /contacts.

ContractTest.java

RESTEasy provides a mechanism for easily launching a Spring MVC/RESTEasy application. RESTEasy also comes with a robust REST client framework. This article will cover bits and pieces of the test, but you can view the entire code in the RESTEasy SVN.

To start, we're going to set up an interface that the RESTEasy client can use to create a client for our application. It consists of abstract methods annotated with JAX-RS annotations:

  @Path(ContactsResource.CONTACTS_URL)
  public interface ContactProxy {
    @Path("data") @POST @Consumes(MediaType.APPLICATION_XML)
    Response createContact(Contact contact);

    @GET @Produces(MediaType.APPLICATION_XML)
    Contact getContact(@ClientURI String uri);

    @GET
    String getString(@ClientURI String uri);
  }

All methods on ContactProxy inherit the ContactsResource.CONTACTS_URL path ("/contacts") as the root URL, just like a server-side JAX-RS resource. This interface's has three methods:

• Create a contact - the createContact method maps to a POST to "/contacts/data". The method accepts a Contact object which will be converted to XML before it's sent to the server. The result is a JAX-RS Response object which contains the response status and headers. One of those headers includes the LOCATION of the new contact
• Get an XML Contact - Given a URL to a Contact, such as the URL returned by the createContact method's response's LOCATION header, GET an XML response and create a Contact object from it.
• Get a Response as a String - Given a URL, such as a Contact URL or anything else on the server, retrieve a String result.

This interface will be used by RESTEasy to construct a concrete instance that uses the JAX-RS annotations to perform the actual HTTP calls. Next, let's create the embedded server and use RESTEasy to create that instance of a ContactProxy:

  private static ContactProxy proxy;

  private static TJWSEmbeddedSpringMVCServer server;
  public static final String host = "http://localhost:8080/";

  @BeforeClass
  public static void setup() {
    server = new TJWSEmbeddedSpringMVCServer("classpath:springmvc-servlet.xml", 8080);
    server.start();

    RegisterBuiltin.register(ResteasyProviderFactory.getInstance());
    proxy = ProxyFactory.create(ContactProxy.class, host);
  }

  @AfterClass
  public static void end() {
    server.stop();
  }

JUnit invokes methods annotated by @BeforeClass before any test methods run. Methods annotated by @AfterClass are triggered by JUnit before after all test methods are complete. In our case, the setup method will instantiate a server that contains a SpringMVC Servlet on port 8080 that is configured by the same Spring XML configuration file we used in Jetty. It also invokes the two lines of code required to create a RESTEasy client. RegisterBuiltin sets up the RESTEasy run time, and must be run one time per client. ProxyFactory.create tells RESTEasy to read the annotations on the ContactProxy interface and to create a Java Proxy instance that knows how to perform the HTTP requests we'll need for our test:

  @Test
  public void testData() {
    Response response = proxy.createContact(new Contact("Solomon", "Duskis"));
    String duskisUri = (String) response.getMetadata().getFirst(HttpHeaderNames.LOCATION);
    Assert.assertTrue(duskisUri.endsWith(ContactsResource.CONTACTS_URL + "/data/Duskis"));
    Assert.assertEquals("Solomon", proxy.getContact(duskisUri).getFirstName());
    ...
  }

This test creates a new Contact, checks the server's response to make sure that the URL is consistent with the test's expectations. It then re-retrieves the Contact and confirms that the firstName is indeed what was sent sent in. While this is a pretty trivial looking test, it performs quite a bit of HTTP activity and business logic.

Conclusion

This article discussed quite a bit of philosophy and design considerations in building a RESTful web application with RESTEasy and Spring MVC. We also built an end to end application with RESTEasy, Spring MVC, Maven, Jetty and JUnit. Even though the content in this article was significant, the code presented here is relatively short compared to other Java alternatives. We touched on subjects like designing REST Applications, creating Spring applications, the RESTEasy client infrastructure and testing RESTful applications. Each of those subjects merit their own articles. There were also other subjects that we simply couldn't fit into this article (as long as it is), including JavaScript to the toolkit to allow closer integration between the browser and your RESTful application, integrating with Flex and more. The code presented in this article can serve as a spring board (again, no pun intended) for all of those ideas.

Solomon Duskis