RESTful Services with Maven, Spring and Jersey

REST (REpresentational State Transfer) is an architecture style that describes how to use HTTP to access web services. JAX-RS (JSR 311) is a Java API to support implementation/access of REST web services using Java. This style was first documented by Ron Fielding. Note: Jan 10th 2012: Blog updated. Code moved into Maven project structure.

REST…

requires that all services be treated as resources that can be accessed via a URI.
requires the services be stateless.
does NOT describe any common data exchange formats. The producer and consumer are free to choose whatever format they want.
services in many cases are cacheable.
uses existing HTTP methods to define actions to be done on the server.

Used over HTTP the following HTTP methods can be used:

GET to retrieve data.
DELETE to delete.
POST to add new data
PUT to update data.

Now compare all of this to SOAP based web services where you use a WSDL to advertise your interface. We have the SOAP envelope that wraps the payload. Then we have document-style vs. rpc style. SOAP Faults. Marshalling and un-marshalleing the soap headers, envelope and fault. SOAP Web Services also provide many services such as transaction, security, addressing, etc (basically the WS-* baggage). And last but not the least we have the payload – finally. All that’s great, but often we just need to access a simple service without the need for all of the SOAP complexity. That is where the RESTful architecture style comes in. On the Java side JAX-RS was introduced to provide a common API to implement/access REST based services in Java. Jersey is the open source reference implementation of REST. Lets get to an example and see how this works. I will implement my usual time service. Call a service to get time of the day in XML, plain text or JSON format. First the Maven pom.xml file:

&lt;project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"&gt;
    &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
    &lt;groupId&gt;com.aver&lt;/groupId&gt;
    &lt;artifactId&gt;rest&lt;/artifactId&gt;
    &lt;version&gt;0.0.1-SNAPSHOT&lt;/version&gt;
    &lt;packaging&gt;war&lt;/packaging&gt;
    &lt;name&gt;jaxrs-jersey&lt;/name&gt;

    &lt;properties&gt;
        &lt;spring.version&gt;3.1.0.RELEASE&lt;/spring.version&gt;
        &lt;jersey-version&gt;1.11&lt;/jersey-version&gt;
    &lt;/properties&gt;

    &lt;dependencies&gt;
        &lt;dependency&gt;
            &lt;groupId&gt;com.sun.jersey&lt;/groupId&gt;
            &lt;artifactId&gt;jersey-server&lt;/artifactId&gt;
            &lt;version&gt;${jersey-version}&lt;/version&gt;
        &lt;/dependency&gt;
        &lt;dependency&gt;
            &lt;groupId&gt;com.sun.jersey.contribs&lt;/groupId&gt;
            &lt;artifactId&gt;jersey-spring&lt;/artifactId&gt;
            &lt;version&gt;${jersey-version}&lt;/version&gt;
        &lt;/dependency&gt;
        &lt;dependency&gt;
            &lt;groupId&gt;com.sun.jersey&lt;/groupId&gt;
            &lt;artifactId&gt;jersey-json&lt;/artifactId&gt;
            &lt;version&gt;${jersey-version}&lt;/version&gt;
        &lt;/dependency&gt;
        &lt;dependency&gt;
            &lt;groupId&gt;org.springframework&lt;/groupId&gt;
            &lt;artifactId&gt;spring-core&lt;/artifactId&gt;
            &lt;version&gt;${spring.version}&lt;/version&gt;
        &lt;/dependency&gt;
        &lt;dependency&gt;
            &lt;groupId&gt;org.springframework&lt;/groupId&gt;
            &lt;artifactId&gt;spring-context&lt;/artifactId&gt;
            &lt;version&gt;${spring.version}&lt;/version&gt;
        &lt;/dependency&gt;
        &lt;dependency&gt;
            &lt;groupId&gt;org.springframework&lt;/groupId&gt;
            &lt;artifactId&gt;spring-context-support&lt;/artifactId&gt;
            &lt;version&gt;${spring.version}&lt;/version&gt;
        &lt;/dependency&gt;
        &lt;dependency&gt;
            &lt;groupId&gt;org.springframework&lt;/groupId&gt;
            &lt;artifactId&gt;spring-beans&lt;/artifactId&gt;
            &lt;version&gt;${spring.version}&lt;/version&gt;
        &lt;/dependency&gt;

    &lt;/dependencies&gt;

    &lt;build&gt;
        &lt;finalName&gt;jaxrs&lt;/finalName&gt;
        &lt;plugins&gt;
            &lt;plugin&gt;
                &lt;groupId&gt;org.mortbay.jetty&lt;/groupId&gt;
                &lt;artifactId&gt;maven-jetty-plugin&lt;/artifactId&gt;
                &lt;version&gt;6.1.10&lt;/version&gt;
                &lt;configuration&gt;
                    &lt;contextPath&gt;/jaxrs&lt;/contextPath&gt;
                    &lt;connectors&gt;
                        &lt;connector implementation="org.mortbay.jetty.nio.SelectChannelConnector"&gt;
                            &lt;port&gt;9090&lt;/port&gt;
                            &lt;maxIdleTime&gt;60000&lt;/maxIdleTime&gt;
                        &lt;/connector&gt;
                    &lt;/connectors&gt;
                &lt;/configuration&gt;
            &lt;/plugin&gt;
        &lt;/plugins&gt;
    &lt;/build&gt;
&lt;/project&gt;

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

<version>0.0.1-SNAPSHOT</version>

<name>jaxrs-jersey</name>

<spring.version>3.1.0.RELEASE</spring.version>

<jersey-version>1.11</jersey-version>

</properties>

<groupId>com.sun.jersey</groupId>

<artifactId>jersey-server</artifactId>

<version>${jersey-version}</version>

</dependency>

<groupId>com.sun.jersey.contribs</groupId>

<artifactId>jersey-spring</artifactId>

<version>${jersey-version}</version>

</dependency>

<groupId>com.sun.jersey</groupId>

<artifactId>jersey-json</artifactId>

<version>${jersey-version}</version>

</dependency>

<groupId>org.springframework</groupId>

<artifactId>spring-core</artifactId>

<version>${spring.version}</version>

</dependency>

<groupId>org.springframework</groupId>

<artifactId>spring-context</artifactId>

<version>${spring.version}</version>

</dependency>

<groupId>org.springframework</groupId>

<artifactId>spring-context-support</artifactId>

<version>${spring.version}</version>

</dependency>

<groupId>org.springframework</groupId>

<artifactId>spring-beans</artifactId>

<version>${spring.version}</version>

</dependency>

</dependencies>

<build>

<finalName>jaxrs</finalName>

<groupId>org.mortbay.jetty</groupId>

<artifactId>maven-jetty-plugin</artifactId>

<contextPath>/jaxrs</contextPath>

</connector>

</connectors>

</configuration>

</plugin>

</plugins>

</build>

</project>

Here is the web.xml…

&lt;web-app&gt;
    &lt;display-name&gt;JAX-RS Jersey App&lt;/display-name&gt;

    &lt;listener&gt;
        &lt;listener-class&gt;org.springframework.web.context.ContextLoaderListener&lt;/listener-class&gt;
    &lt;/listener&gt;

    &lt;listener&gt;
        &lt;listener-class&gt;org.springframework.web.context.request.RequestContextListener&lt;/listener-class&gt;
    &lt;/listener&gt;

    &lt;servlet&gt;
        &lt;servlet-name&gt;JAX-RS Jersey App&lt;/servlet-name&gt;
        &lt;servlet-class&gt;com.sun.jersey.spi.spring.container.servlet.SpringServlet&lt;/servlet-class&gt;
        &lt;init-param&gt;
            &lt;param-name&gt;com.sun.jersey.config.property.packages&lt;/param-name&gt;
            &lt;param-value&gt;com.aver.restful&lt;/param-value&gt;
        &lt;/init-param&gt;
        &lt;load-on-startup&gt;1&lt;/load-on-startup&gt;
    &lt;/servlet&gt;
    &lt;servlet-mapping&gt;
        &lt;servlet-name&gt;JAX-RS Jersey App&lt;/servlet-name&gt;
        &lt;url-pattern&gt;/services/*&lt;/url-pattern&gt;
    &lt;/servlet-mapping&gt;
&lt;/web-app&gt;

<web-app>

<display-name>JAX-RS Jersey App</display-name>

<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>

</listener>

<listener-class>org.springframework.web.context.request.RequestContextListener</listener-class>

</listener>

<servlet-name>JAX-RS Jersey App</servlet-name>

<servlet-class>com.sun.jersey.spi.spring.container.servlet.SpringServlet</servlet-class>

<init-param>

<param-name>com.sun.jersey.config.property.packages</param-name>

<param-value>com.aver.restful</param-value>

</init-param>

<load-on-startup>1</load-on-startup>

</servlet>

<servlet-mapping>

<servlet-name>JAX-RS Jersey App</servlet-name>

<url-pattern>/services/*</url-pattern>

</servlet-mapping>

</web-app>

Here is the implementation of the TimeOfTheDayService. JAX-WS annotations have been used to configure various JAX-RS attributes.

package com.aver.restful;

import java.text.SimpleDateFormat;
import java.util.Calendar;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;

import org.springframework.stereotype.Component;

@Component
@Path("/timeoftheday")
public class TimeOfTheDayService {
    private static String PATTERN = "MM.dd.yyyy HH:mm:ss";

    @GET
    @Produces("text/plain")
    @Path("/asplaintext/{name}")
    public String getTimeOfTheDay(@PathParam("name") String name) {
        SimpleDateFormat df = new SimpleDateFormat(PATTERN);
        return name + "-" + df.format(Calendar.getInstance().getTime());
    }

    @GET
    @Produces("application/xml")
    @Path("/asxml/{name}/")
    public Time getTimeOfTheDayInXML(@PathParam("name") String name) {
        SimpleDateFormat df = new SimpleDateFormat(PATTERN);
        Time t = new Time();
        t.setName(name);
        t.setTime(df.format(Calendar.getInstance().getTime()));
        return t;
    }

    @GET
    @Produces("application/json")
    @Path("/asjson/{name}/")
    public Time getTimeOfTheDayInJSON(@PathParam("name") String name) {
        SimpleDateFormat df = new SimpleDateFormat(PATTERN);
        Time t = new Time();
        t.setName(name);
        t.setTime(df.format(Calendar.getInstance().getTime()));
        return t;
    }
}

package com.aver.restful;

import java.text.SimpleDateFormat;

import java.util.Calendar;

import javax.ws.rs.GET;

import javax.ws.rs.Path;

import javax.ws.rs.PathParam;

import javax.ws.rs.Produces;

import org.springframework.stereotype.Component;

@Component

@Path("/timeoftheday")

public class TimeOfTheDayService {

private static String PATTERN = "MM.dd.yyyy HH:mm:ss";

@GET

@Produces("text/plain")

@Path("/asplaintext/{name}")

public String getTimeOfTheDay(@PathParam("name") String name) {

SimpleDateFormat df = new SimpleDateFormat(PATTERN);

return name + "-" + df.format(Calendar.getInstance().getTime());

}

@GET

@Produces("application/xml")

@Path("/asxml/{name}/")

public Time getTimeOfTheDayInXML(@PathParam("name") String name) {

SimpleDateFormat df = new SimpleDateFormat(PATTERN);

Time t = new Time();

t.setName(name);

t.setTime(df.format(Calendar.getInstance().getTime()));

return t;

}

@GET

@Produces("application/json")

@Path("/asjson/{name}/")

public Time getTimeOfTheDayInJSON(@PathParam("name") String name) {

SimpleDateFormat df = new SimpleDateFormat(PATTERN);

Time t = new Time();

t.setName(name);

t.setTime(df.format(Calendar.getInstance().getTime()));

return t;

}

@Component – This is NOT a JAX-RS annotation. This is a Spring annotation to declare a spring bean via annotations vs. XML configuration
@Path(“/timeoftheday”) – Specifies the URI part for all the services in thisclass.
@GET– Used to annotate the read method.
@Produces(“text/plain”)– Marks the method as a producer of plain/text content.
@Path(“/asjson/{name}/”) – Describes the specific method. The optional {name} describes in our case the parameter passed into this service method.

Run “mvn package jetty:run” to compile and deploy the web application to a local Jetty web server. The URL to access the services would be one of:

http://localhost:9090/jaxrs/services/timeoftheday/asplaintext/mathew
http://localhost:9090/jaxrs/services/timeoftheday/asxml/mathew
http://localhost:9090/jaxrs/services/timeoftheday/asjson/mathew

The resource is identified via the URI and so is the parameter namein this example. Access one of the URLs mentioned above using your favorite browser and you will get the response in the appropriate format. You can also use the Jersey client API to access this service.

import com.sun.jersey.api.client.Client;
import com.sun.jersey.api.client.WebResource;

public class RestTest {
    public static void main(String[] args) {
        Client c = Client.create();

        // plain text
        WebResource r = c
                .resource("http://localhost:9090/jaxrs/services/timeoftheday/asplaintext/mathew");
        System.out.println("Plain Text=&gt;&gt; " + r.get(String.class));

        // json
        r = c.resource("http://localhost:9090/jaxrs/services/timeoftheday/asjson/mathew");
        System.out.println("JSON=&gt;&gt; " + r.get(String.class));

        // xml
        r = c.resource("http://localhost:9090/jaxrs/services/timeoftheday/asxml/mathew");
        System.out.println("XML=&gt;&gt; " + r.get(String.class));
    }
}

import com.sun.jersey.api.client.Client;

import com.sun.jersey.api.client.WebResource;

public class RestTest {

public static void main(String[] args) {

Client c = Client.create();

// plain text

WebResource r = c

.resource("http://localhost:9090/jaxrs/services/timeoftheday/asplaintext/mathew");

System.out.println("Plain Text=>> " + r.get(String.class));

// json

r = c.resource("http://localhost:9090/jaxrs/services/timeoftheday/asjson/mathew");

System.out.println("JSON=>> " + r.get(String.class));

// xml

r = c.resource("http://localhost:9090/jaxrs/services/timeoftheday/asxml/mathew");

System.out.println("XML=>> " + r.get(String.class));

}

Once you execute this client you should get a response such as:

Plain Text=&gt;&gt; mathew-01.10.2012 22:00:42
JSON=&gt;&gt; {"time":"01.10.2012 22:00:42","name":"mathew"}
XML=&gt;&gt; &lt;?xml version="1.0" encoding="UTF-8" standalone="yes"?&gt;&lt;clock&gt;&lt;time&gt;01.10.2012 22:00:42&lt;/time&gt;&lt;name&gt;mathew&lt;/name&gt;&lt;/clock&gt;

Plain Text=>> mathew-01.10.2012 22:00:42

JSON=>> {"time":"01.10.2012 22:00:42","name":"mathew"}

XML=>> <?xml version="1.0" encoding="UTF-8" standalone="yes"?><clock><time>01.10.2012 22:00:42</time><name>mathew</name></clock>

Click here to download the full Maven project.

{"Mat's Random Thoughts"}

Mathew's Tech Notes..

RESTful Services with Maven, Spring and Jersey