Creating a Java based RESTful web service (JAX-RS)

Here we will build a Java based RESTfull web service using Jersey.


What is Jersey ?
Jersey is an open source framework that we can use to build RESTful web services. And furthermore it is based on standard JAX-RS framework.

So we can use just the standard JAX-RS provided by JDK also. But developing with Jersey can make you a handy person. ;)

As a start you can have a dynamic web project in Eclipse and then add .jars provided by Jersey. But the thing is Jersey jars are already in maven repository. So if you create a maven project instead of a dynamic web project, maven downloads and resolves any dependencies.

You can create a Maven project from Jersey archtype. If the related archtype is not defined you can create a arch type by providing the following.

• artifactId=jersey-quickstart-webapp
• archetypeGroupId=org.glassfish.jersey.archetypes
• archetypeVersion=2.22.1 // The latest stable version available.

What is happening with Jersey ?

1. Client request the REST service via a valid URL(

Lets say http://host.com/AppName/webapi/myResource 

Because we can request services via URLs we dont need to create additiona hard coded REST clients, just a browser is enough. But if you wannt do much more with URLs and requests there are very very good browser plugins and extensions for chome and FireFox.

2. Application (AppName)gets the request. Actually web.xml in WEB-INF gets and handles the request.

It decides what package to look for (com.kapal.restdemo)

<init-param>
            <param-name>jersey.config.server.provider.packages</param-name>
            <param-value>com.kapal.restdemo</param-value>
</init-param>

And also it does the mapping between URL and resource classes. Here it maps webapi/ any_url_portion with com.kapal.restdemo

<servlet-mapping>
        <servlet-name>Jersey Web Application</servlet-name>
        <url-pattern>/webapi/*</url-pattern>
</servlet-mapping>

3. So the resource we need to look for is myResource.
If there is a class annotated with @Path("myResource"), Jersey will get that class.

package com.kapal.restdemo;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;


@Path("myresource")
public class MyResource {

    
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String getIt() {
        return "Got it! yeah";
    }
}

Here additional 2 annotations are needed.
@GET - respond to GET HTTP verb
@Produces - Means in what format we should send the response to client.
Typically it can be plain text, or HTML format. But sometime we may need to respond with XML format or JSON.

(MediaType.APPLICATION_XML)
With JDK we have JAXB(Java Architecture for XML Binding). So it is pretty straight foreward to convert Java objects to XML format and vice versa. All we have to do annotate the requires object class as @XmlRootElement


(MediaType.APPLICATION_JSON)
Unfortunately with JDK we dont have a inbuilt support. We need to have a 3rd party support. Jersey also has a JSON library called moxy. You can manually add the .jars or let Maven do it for you. All you need do is add the dependency by uncommenting following dependency portion in pom.xml

<dependency>
            <groupId>org.glassfish.jersey.media</groupId>
            <artifactId>jersey-media-moxy</artifactId>
 </dependency>