Building RESTful web service using Jersey

Jersey is an open source reference implementation of JSR-311. The implementation provides support for annotations defined in JSR-311 and other APIs making it easy for developers to build RESTful web service. In this tutorial we will build a simple Hello World web service using Jersey.

Before we code, let’s have a look at basics.

What is a RESTful web service?

Representational state transfer (REST) is a style of software architecture for distributed hypermedia systems. It’s not a standard but makes use of widely accepted standards like HTTP,HTML, XML and URL.

A client application using REST is viewed as state machine. The client references a Web resource using a URL. A representation of the resource called is returned to the client. It can be HTML, XML, plain text etc.

What is Jersey?

Like I earlier - Jersey is the open source JAX-RS (JSR 311) reference implementation for building RESTful web services. Jersey 1.0.2 implements JAX-RS 1.0 and is shipped with GlassFish server. You can download the jars from Jersey site: https://jersey.dev.java.net/

Building our frist RESTful web service

I have kept our first web service as simple as possible. It would just serve a text “Hello World”! You can grab the source code here. I have used ServletContainer to expose the service. This way you will be able to deploy our service in any servlet container.

In REST, a service is called resource. Jersey provides annotation what make developers job easy and quick. Here is our resource (HelloWorldResource.java):

package rest.resource;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;

@Path("helloworld")
public class HelloWorldResource {
 
 @GET
 @Produces("text/plain")
 public String getMessage() {
  return "Hello World";
 }
}

Remove the annotations and you get a simple POJO. So, in short what we are doing here is adding some annotations to a POJO and deploying it as a service. Let me explain the annotation you see in the above code.

@Path defines a relative URI path for accessing the service. What you see is a very simple path. JAX-RS allows you to embed variables in URI making it path templates.

@GET annotation designates the request method. JAX-RS supports @POST, @PUT, @DELETE and @HEAD along with @GET method.

@Produces annotation is used to specify the MIME types for a resource representation that is sent back to the client. In our case, we are returning a plain text.

We will discuss other annotation is the coming tutorials. With this, we have out first service ready. To deploy this in a servlet container we need to configure web.xml to process requests coming to the server. In web.xml file, we declare a serlvet-class with appropriate parameters as shown below:

<servlet>
<servlet-name>Jersey</servlet-name>
<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
 <init-param>
 <param-name>com.sun.jersey.config.property.packages</param-name>
<param-value>rest.resource</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>Jersey</servlet-name>
<url-pattern>/jersey/*</url-pattern>
</servlet-mapping>

Please note that in my servlet-mapping, I have the url-pattern as /jersey/*. This is not the only method to specify REST resources class in web.xml. I will explain other methods in a separate article.You can access our new RESTful service using the URL http://localhost:8080/restweb/jersey/helloworld.