Developing Restful Web services Using IBM JAX-RS

Java™ API for RESTful Web Services (JAX-RS) is a programming model that provides a mechanism for developing services that follow Representational State Transfer (REST) principles. Using JAX-RS, development of RESTful services is simplified.

The IBM^® implementation of JAX-RS provides an implementation of the JAX-RS specification.

IBM JAX-RS includes the following features:

• JAX-RS server runtime
• Standalone client API with the option to use Apache HttpClient 4.0 as the underlying client
• Built-in entity provider support for JSON4J
• An Atom JAXB model in addition to Apache Abdera support
• Multipart content support
• A handler system to integrate user handlers into the processing of requests and responses

Required Jars:

• jsr311-api.jar
• commons-lang.jar
• slf4j-api.jar
• slf4j-jdk14.jar
• ibm-wink-jaxrs.jar

Step 1 - Creating the Root Resource

As defined in the JAX-RS specification, by default, resource instances are created per request.  For the JAX-RS runtime environment to create a resource instance, you must have either a constructor with no argument or a constructor with only JAX-RS annotated parameters(@Context,@HeaderParam,@CookieParam,@MatrixParam,@QueryParam,@PathParam). present.

I created a class with no constructor.

public class HelloWorld {

}

Step 2 – Adding path to resource

Add a @javax.ws.rs.Path annotation to HelloWorld class.  For each @javax.ws.rs.Path annotation, set the value as the part of the URL after the base URL of the application.

@Path("/home")

public class HelloWorld {

..

}

 http://<host_name>:<port>/<context_root>/<servlet_path>/home will use HelloWorld class.

Step 3 – Adding method to resource

 I have created a method called welcomeMessage and annotate the method as GET

@Path("/home")

public class HelloWorld {

      @GET

      public String welcomeMessage(){

            return "Welcome to Our Websphere Portal JAX-RS";

      }    

}

Whenever an HTTP GET request is received by this class, the welcomeMessage method will be invoked.

Step 4 – Creating a javax.ws.rs.core.Application sub-class

For non-JAX-RS aware web container environments (most environments are currently non JAX-RS aware), a javax.ws.rs.core.Application sub-class needs to be created which returns sets of JAX-RS root resources and providers. In the following example, there is only one root resource that will need to be returned.

public class RestConfig extends  Application{

      public Set<Class<?>> getClasses() {

            Set<Class<?>> classes = new HashSet<Class<?>>();

            classes.add(HelloWorld.class);

            return classes;

      }

}

Step 5 – Configure the web.xml file for the JAX-RS application

We need to modify the web.xml so that the servlet container knows that the web application is JAX-RS supported and what are the JAX-RS classes by specifying the application configuration sub class as a parameter.

<web-app id="WebApp_ID" version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

      <display-name>RestExample</display-name>

      <servlet>

                  <servlet-name>REST</servlet-name>

                  <servlet-class>com.ibm.websphere.jaxrs.server.IBMRestServlet</servlet-class>

                  <init-param>

                        <param-name>javax.ws.rs.Application</param-name>

                        <param-value>com.ourwebsphereportal.jaxrs.RestConfig</param-value>

                  </init-param>

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

            </servlet>

            <servlet-mapping>

                  <servlet-name>REST</servlet-name>

                  <url-pattern>/rest/*</url-pattern>

    </servlet-mapping>

</web-app>

click here to download the example

on accessing,

http://localhost:7080/RestExample/rest/home 

where RestExample is context root