JAX-RS QuickStart Guide

This quickstart guide will walk you through development of a very basic "Hello, World!" JAX-RS sample application in Eclipse IDE (version 3.4.2, as of this writing), deployable on nearly any web container framework.

  1. Create a new java project. Let's call it "jaxrs_helloworld"
  2. Configure your project to have the JAX-RS API and implementation library jars on its buildpath
  3. Develop your server-side JAX-RS application:
    1. Create a new class that processes incoming requests
      As a best practice, you may wish to name your resource with "Resource" at the end of your class name.

      Resource classes can support the four HTTP commands: POST, GET, DELETE, and PUT. Our HelloWorldResource class will only support GET.
      • Right-click project -> New -> Java Class ->
      • Package: org.myorg.jaxrs.sample
      • Class: HelloWorldResource
    2. Create a method that takes no parameters, and returns the string "Hello, World!" The method name is arbitrary: 
      public String helloWorld() {
	return "Hello, World!";
}

      The JAX-RS runtime needs to know where to expose this resource. Add the @Path annotation to the method: 
      @Path("helloworld")
public String helloWorld() {
	return "Hello, World!";
}

      Now JAX-RS needs to know which methods perform what actions. Our only method, helloWorld(), simply returns a String. So logically, it fits with the GET command. Add the @GET annotation to the helloWorld() method: 
      @GET
@Path("helloworld")
public String helloWorld() {
	return "Hello, World!";
}

      Now our resource class is configured to handle HTTP inbound GET requests at: 
      http://<host>:<port>/<context_root>/helloworld

      Note: <context_root> is defined by the the servlet container on which you deploy your application and may be an empty value, making your URL http://<host>:<port>/helloworld

      Since all web browsers send GET requests when a URL is entered in as the location, we will be able to query our application very simply from a browser.

      However, we need to register the HelloWorldResource class as a resource with the JAX-RS runtime. We do this by creating a HelloWorldApplication class that declares resources to the JAX-RS runtime:
    3. Create a new application class:
      As a best practice, you may wish to name your resource with "Application" at the end of your class name.
      • Right-click project -> New -> Java Class ->
      • Package: org.myorg.jaxrs.sample
      • Class: HelloWorldApplication
      • Superclass: javax.ws.rs.core.Application;

      In the HelloWorldApplication, write a method to override the javax.ws.rs.core.Application.getClasses method. This is how you declare to the JAX-RS runtime which classes should be exposed as resources. In our application, we only have one resource class, so your getClasses method would look like this: 
      @Override
public Set<Class<?>> getClasses() {
	Set<Class<?>> classes = new HashSet<Class<?>>();
	classes.add(HelloWorldResource.class);
	return classes;
}

      At this point, we have a complete JAX-RS application with a single resource to handle an HTTP GET request!

      (The next few steps assume you are not using Eclipse or other IDE tools to build a WAR file.)

    4. There's one last thing to do. We have to tell the application server's servlet container what servlet implementation to use, and we have to pass our application class name as a parameter to the JAX-RS servlet implementation. This is all done with the very familiar web.xml deployment descriptor:

      Create the necessary web.xml deployment descriptor:
      • Create a WEB-INF directory as a peer to your project src directory
      • Create a web.xml file inside. At a minimum, you will need a a servlet-name, servlet-class, init-param, and servlet-mapping. For our HelloWorldApplication, it would look like this: 
        <?xml version="1.0" encoding="UTF-8"?>
	<!--
		This program may be used, executed, copied, modified and distributed
		without royalty for the purpose of developing, using, marketing, or
		distributing.
	-->
<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">
	<servlet>
		<servlet-name>HelloWorld</servlet-name>
		<servlet-class>com.ibm.ws.jaxrs.web.RESTServlet </servlet-class>
		<init-param>
			<param-name>javax.ws.rs.Application</param-name>
			<param-value>org.myorg.jaxrs.sample.HelloWorldApplication</param-value>
		</init-param>
		<load-on-startup>1</load-on-startup>
	</servlet>
	<servlet-mapping>
		<servlet-name>HelloWorld</servlet-name>
		<url-pattern>/*</url-pattern>
	</servlet-mapping>
</web-app>
      • Export your project as a WAR to be deployed on a web server with a servlet container. Recall that the structure of a WAR is: 
        WEB-INF/classes/<path_to_compiled_classes>
WEB-INF/lib/<library_jars_for_your_app>
WEB-INF/web.xml

        Specifically, our HelloWorld application WAR file would be (note that the listed JAR files in the lib folder are required by the JAX-RS runtime, and thus are required to be in your WAR file): 
        META-INF/MANIFEST.MF
WEB-INF/classes/com/ibm/jaxrs/sample/helloworld/HelloWorldResource.class
WEB-INF/classes/com/ibm/jaxrs/sample/helloworld/HelloWorldApplication.class
WEB-INF/web.xml
WEB-INF/lib/ibmjaxrs-SNAPSHOT.jar
WEB-INF/lib/jsr311-api-0.11.jar
WEB-INF/lib/abdera-0.4.0-incubating.jar
WEB-INF/lib/abdera-core-0.4.0-incubating.jar
  4. That's it! Hello, World!

Next Steps