Jersey in Spring usage quick guide

Jersey in Spring usage quick guide


This is a quick guide for building a restful webservice with Jersey in Spring.


Step1: setup a dispatcher servlet
Step2: create root resource class
Step3: create methods to handle webservice reqeust
Step4: testing with restful client
Appendixes


Step1: setup a dispatcher servlet. 


For setting up a restful webservice, a dispatcher servlet must be configured for listening to the incoming request. 
You can use the SpringServlet as dispatcher servlet or write a new one to extend from SpringServlet.
SpringServlet is included in jersey-spring-x.x.x.jar file.  


What is the difference between the two approaches? It depends on your needs while selecting SpringServlet or customized servlet.
If one dispatcher is ok to process all reqeust, a single SpingServlet instance can handle everything for you. 
If you would like to setup multiple dispatcher servlet or add customized function (such as prining logs), then customized servlet would be better.


And then how to configurate dispatcher servlet? There are two options as well.
Traditionally, the setting is in web.xml, like this,

  <servlet>
    <servlet-name>WSTest Servlet</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>org.pegasus.ws.testImpl</param-value>    <!-- This is the package including java classes -->
    </init-param>
    <load-on-startup>1</load-on-startup>
  </servlet>


  <servlet-mapping>
    <servlet-name>WSTest Servlet</servlet-name>
    <url-pattern>/WSTest/*</url-pattern>    <!-- This is the url pattern for accessing the webservices -->
  </servlet-mapping> 


The alternative is to setup with annotation. 
Since SpringServlet is packaged in jersey jar file, so annotation is suitable when you create customized dispatcher servlet only.
Here is a sample how to use annotation,

@WebServlet(name = "webServiceRest", urlPatterns = { "/webserviceRS/*" }, loadOnStartup = 1, initParams = { @WebInitParam(name = "com.sun.jersey.config.property.packages", value = "org.pegasus.ws.testImpl") })
public class WSTestSpringJerseyServlet extends SpringServlet {
......

Only one line for the annotation, just like what you set in web.xml. That is easy, right? But because annotation is hard coded in java code. It is not recommended.


Step2: create root resource class

OK, a dispatcher servlet is ready, the next is to set a root resource for webservice. 
A root resource is a java class to publish as webservice interface. Actually, it is a java class with '@Path' annotation, like this,

@Path("RestfulTest")
public class RestfulTestImpl implements RestfulTest {
...


After that, it is possible to access the webservice with url: http://<domain-name>/<application-context>/WSTest/RestfulTest.
WSTest is the url pattern set in web.xml and RestfulTest is the root resouce name.
But if you visit the url, you must get errors. Because there is no method to handle the request now.  For next, let's create methods to handle the request.


Step3: create methods to handle webservice reqeust

In Jersey website, http://jersey.java.net/. you can find the detailed API doc. 
In the quick guide, I will show a simplest way to create a method.


@POST
public String getHelloWorld() {

return "Hello World POST";

}

@POST means receiving the POST type httprequest. You could use POST, GET, DELETE, PUT types etc.


@POST
@Path("getHelloWorld")
public String getHelloWorld() {

return "Hello World POST";
}
@Path in method level is different with class level.  @Path in method level is not necessary.
If it is existed, the webservice should be visited by url: http://<domain-name>/<application-context>/WSTest/RestfulTest/getHelloWorld.
Otherwize, http://<domain-name>/<application-context>/WSTest/RestfulTest is ok. For both, the request must be sent by POST.


Step4: testing with restful client


For deploying the sample, Spring and Jersey dependent jars will be required.
Spring jars can be downloaded in http://www.springsource.com/download/community and Jersey jars in  http://jersey.java.net/.


And for testing, you probably need a restful client.  Chrome, Firefox both provide restful client plugins. 
Download and install the plugin and then test with it. 




Appendixes:
A) For more Jersey features and details, please read user guide at http://jersey.java.net/nonav/documentation/latest/user-guide.html.
B) Official quick tutorial, please read http://docs.oracle.com/cd/E19776-01/820-4867/index.html
C) API doc can be found in Jersy website http://jersey.java.net/.