RESTful Service with Java using Jersey

What is REST?

REST stands for Representational State Transfer. It is an architectural style based on HTTP protocol and was conceptualized by Roy Fielding way back in the year 2000. In REST service, everything is a resource and every resource has an id. The resources reside at the REST server end and is consumed by one or more REST clients using common HTTP operations like GET, POST, PUT, DELETE, OPTIONS, etc. The resources can be represented in multiple application formats like text, XML, JSON etc. Content negotiation is done by the REST client using which it gets the resource in required format via REST call.

Prerequisites

This tutorial uses Eclipse WTP and Apache Tomcat Server V7.0 as a web container for hosting the REST service.

The server can be downloaded and installed in eclipse via Window -> Preferences -> Server -> Runtime Environments -> Add -> Download and install. The server thus installed can be started or stopped using Window -> Show View -> Servers -> Servers.

This tutorial assumes the reader to be familiar with how server setup is done and how a dynamic web project is created with Eclipse WTP. Although deep dive into the details for the setup is not under scope of this tutorial, we are attaching a screenshot to show how the IDE would look like on successful setup of the server.

Add tomcat to eclipse
Add tomcat to eclipse

Jersey

Java defines the standard for REST services in Java Specification Request 311 (jsr311). It is also called Java API for RESTful Web Services (JAX-RS). Jersey is one of the reference implementations of JAX-RS.

Using Jersey, the base URL of the servlet that is used for mapping REST service would be:
http://domainname:portnumber/display-name/url-pattern/serviceclass_path_annotation_value

The display-name and url-pattern will be specified in deployment descriptor (web.xml) and this will be discussed later in this tutorial.

Servlet mapping is an example of MVC architecture implementation where the servlet analyses the incoming HTTP requests and redirects to the correct class and method that shall serve the request. This is done with the help of annotations on the class and methods.

JAX-RS Annotations

Important annotations of JAX-RS and their descriptions are given in the table below.

Annotation Description
@Path(“pathname”) This denotes that for accessing the particular service, we need to hit the URL formed using basepath + /pathname.
@GET Denotes that the method that immediately follows this annotation will respond to a GET request
@POST Denotes that the method that immediately follows this annotation will respond to a POST request
@PUT Denotes that the method that immediately follows this annotation will respond to a PUT request.
@DELETE Denotes that the method that immediately follows this annotation will respond to a DELETE request.
@Produces(mediatype) or @Produces(mediatype1, mediatype2, more types) Denotes the MIME type that a Resource can produce and send back to client. This annotation can be applied at both method level as well as class level.
@Consumes(mediatype) or @Consumes(mediatype1, mediatype2, more types) Denotes the MIME type that a Resource can consume. Like @Produces, this annotation can also be applied at both method and class level.
@PathParam Used to extract parameter from path component of URL that matches with what is specified in @Path annotation.
@QueryParam Used to extract parameter from query component of URL. Usually it is denoted using questionmark in a given URL. eg: http://localhost:8080/services?count=10. In this URL, count is query parameter whose value requested by client is 10.

Creating the first REST service

We will start with implementing a simple service hat shall display a message when invoked via an HTTP GET request.

Create A New Dynamic Web Project In Eclipse

Right click on the project explorer. Select New -> Dynamic Web Project. The following Wizard will open.

New dynamic web project
New dynamic web project

Give project name and click Next.

Dynamic web project details
Dynamic web project details

 

Click Next again. In the next page of the Wizard, make sure to enable the checkbox to “Generate web.xml deployment descriptor”.

 

New dynamic web project
New dynamic web project

Click Finish. Now our first project is created and we should be able to see the newly created project inside Project Explorer.

Add Jersey To The Project

Download and install jersey libraries into the dynamic web project. For this, we need to download the distribution as a zip folder from the official Jersey download site.

After downloading the zip file, extract all files and copy the jars into project -> WebContent -> WEB-INF->lib folder.

 

Jersey installed
Jersey installed

Java Service Class

Let us create our first service class.

Jersey Servlet Settings

We have created our simple implementation class but we need to make sure that our service is invoked whenever an HTTP GET request is sent to baseurl+/hello. For this, we need to register Jersey as servlet dispatcher by altering the web.xml that was created during project creation. The modifications for the web.xml is as follows:

web xml change
web xml change

Running The First REST Service

Right click on Project inside project explorer. Select Run As -> Run on Server.

We should be able to access the REST service via browser or cURL [if that is installed] using the URL:

http://localhost:8080/JerseyRestExample/hello

 

Rest output browser
Rest output browser

Our first REST service is up and running.

Leave a Reply