Getting started with IBM JAX-RS

JAX-RS is a collection of interfaces and Java™ annotations that simplifies development of server-side REST applications. By using JAX-RS technology, Representational State Transfer (REST) applications are easier to develop and easier to consume when compared to other types of distributed systems.

1. Create a Java class.
   This class is used to represent a type of resource.

   package com.ibm.jaxrs.sample;
   
   public class HelloWorldResource {
   
   }

2. Annotate the Java class with a javax.ws.rs.Path annotation.
   The value of the annotation is the relative part of the URL after the application context. The application context is fully defined during deployment. In JAX-RS terminology, this class is known as a root resource.

   package com.ibm.jaxrs.sample;
   
   @javax.ws.rs.Path("/helloworld")
   public class HelloWorldResource {
   
   }

3. Create a Java method that returns a Hello World! response.
   It is intended for the method to be invoked when an HTTP request is received.

   package com.ibm.jaxrs.sample;
   
   @javax.ws.rs.Path("/helloworld")
   public class HelloWorldResource {
   
       public String sayHelloWorld() {
           return "Hello World!";
       }
   }

4. Add a javax.ws.rs.GET annotation to the Java method.
   Now, whenever an HTTP GET request is received by the application to the /helloworld path, the sayHelloWorld Java method is invoked. The response message body will contain Hello World! as its content.

   package com.ibm.jaxrs.sample;
   
   @javax.ws.rs.Path("/helloworld")
   public class HelloWorldResource {
   
       @javax.ws.rs.GET
       public String sayHelloWorld() {
           return "Hello World!";
       }
   }

   The resource implementation is now complete.
5. You must create the JAX-RS javax.ws.rs.core.Application configuration subclass.
   This subclass needs to return the set of Java classes that is relevant to the JAX-RS runtime environment.

   package com.ibm.jaxrs.sample;
   
   public class HelloWorldAppConfig extends javax.ws.rs.core.Application {
       public Set<Class<?>> getClasses() {
           Set<Class<?>> classes = new HashSet<Class<?>>();
           classes.add(com.ibm.jaxrs.sample.HelloWorldResource.class);
           return classes;
       }
   }

6. Create the web.xml web module configuration file.
   The file tells the web container that the web module contains the IBM JAX-RS REST servlet. You must initialize the IBM JAX-RS Rest servlet with the application configuration class.

   <?xml version="1.0" encoding="UTF-8"?>
   <web-app id="WebApp_9" version="2.4" xmlns=http://java.sun.com/xml/ns/j2ee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"> 
       <servlet>
           <servlet-name>HelloWorldApp</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.ibm.jaxrs.sample.HelloWorldAppConfig</param-value>
           </init-param>
           <load-on-startup>1</load-on-startup>
       </servlet>
       <servlet-mapping>
           <servlet-name>HelloWorldApp</servlet-name>
           <url-pattern>/rest/*</url-pattern>
       </servlet-mapping>
   </web-app>

   See the servlet mapping that is specified in the previous example. The pattern is used to help determine the final URL of the RESTful service.
7. Add the j2ee.jar file to the classpath.

   Get the j2ee.jar file from the app_server_root/dev/JavaEE directory and add the JAR file to the classpath. Compile the classes.

8. Assemble the web application.
   By using the jar command-line tool that is included with the JDK, run the following command:

   jar cvf helloworld-jaxrs.war *

   This command creates a WAR file.
9. Deploy the application onto the application server.

   When deploying the application, you might be prompted to provide a value for the context root of the module. The context root is used to define the application context.

   When using the IBM JAX-RS servlet, the following URL defines the application context:

   http://<your_hostname>:<your Web_container_port>/<context_root_of_Web_application>/servlet_mapping_pattern

   Root resource URLs that are specified by the @javax.ws.rs.Path values are relative to the application context root. Therefore, if the context root is defined as myapplication during deployment, the URL pattern is defined in the web.xml file as /rest/*, and the Java root resource class has a @javax.ws.rs.Path value of /helloworld. An example of the final URL is:

   http://localhost:9080/myapplication/rest/helloworld

   Now, you can send a client request to the final URL by using a web browser or any other HTTP client.