So, REST based web services are simpler than SOAP, right? Then why's it so difficult to create a REST based web service in Java? Using tools I can crank out a SOAP based web service in seconds - not so easy with REST. But help is on the way.

JSR 311: JAX-RS: The Java API for RESTful Web Services aims to simplify the process. Paul Sandoz, co-specification lead along with Marc Hadley, does a nice job of introducing JAX-RS in the presentation he delivered last month at Jazoon, specifically by comparing the work you'd have to do using just the servlet API versus the proposed JAX-RS annotations.

The Sun Web Developer Pack contains an early access implementation of JAX-RS along with a tutorial. The tutorial starts with your standard hello application, but it provides a working copy of the application rather than instructions how how to build it from scratch. That's where I come in...

Setting Things Up

• Download and install NetBeans 6.0. If you don't already have GlassFish installed, grab the Standard and Full distribution which has it included.
• Download and install the SWDP to GlassFish.

Creating the hello Application

1. Start NetBeans 6.0 and create a new Web Application named hello.
2. Expand GlassFish under the Libraries node to verify that the SWDP was properly installed. If so, you'll see restbeans-api.jar and restbeans-impl.jar:
   
   
   
   If you do not see the rest libraries, try removing and adding the GlassFish to NetBeans.
   
   
3. Create a new Java class named Hello. Set the package name to anything you like. I used rest. Hello will be a "resource class" identifiable by a URI.
   
   
4. To associate the resource with a URI we use a UriTemplate annotation as follows:
   
   

   @UriTemplate("/hello")
   public class Hello {

   
   
5. Next, define a method to handle the request:
   
   

       public String sayHello() {
           return new String("Hello there.");
       }

   
   
6. Then use an HttpMethod annotation to indicate which type of HTTP request it responds to: GET, POST, PUT or DELETE.
   
   

       @HttpMethod("GET")
       public String sayHello() {
           return new String("Hello there.");
       }

   
   
7. Finally, use a ProduceMime annotation to specify what type should be returned to the client:
   
   

       @HttpMethod("GET")
       @ProduceMime("text/plain")
       public String sayHello() {
           return new String("Hello there.");
       }

Building the hello Application

Before we can deploy the application, we need to generate a class that will load our resource classes (hello in our case), into the application. JAX-RS ships with an annotation processor that will generate this class for us. And NetBeans 6.0 ships with the Ant tasks necessary to call the annotation processor. You'll find it in build-impl.xml. The only problem is these tasks will only run if REST support is turned on:



and NetBeans 6.0 does not yet include an option to turn on REST support via the project's properties, so we just have to do it manually.

1. Alt+Shift+O to open private.properties and add the following:
   
   

   rest.support.on=true

2. Press F11 to build the project and generate the class RESTBeansResources, which you'll find in the build/generated/rest-gen/restbeans folder under the Files tab:
   
   
   
   

There's one more piece to the runtime puzzle, and that's the servlet that kicks everything off, which is provided by the JAX-RS runtime: com.sun.ws.rest.impl.container.servlet.ServletAdaptor. If you look in the WEB-INF directory above, you see a web.xml, which loads this servlet, was also generated for us:

  <servlet>
    <servlet-name>RESTBeans Application</servlet-name>
    <servlet-class>
        com.sun.ws.rest.impl.container.servlet.ServletAdaptor
    </servlet-class>
    <init-param>
      <param-name>resourcebean</param-name>
      <param-value>restbeans.RESTBeansResources</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>RESTBeans Application</servlet-name>
    <url-pattern>/restbean/*</url-pattern>
  </servlet-mapping>

However, the contents of this web.xml did not make it into our distributable.

1. Ctrl+1 to switch to the Projects tab.
2. Open web.xml under Configuration Files, switch to the XML view, and paste the code above just after the opening web-app tag.

Running the Application

1. Open Project Properties and select the Run category. Set the Relative URL to /restbean/hello.
2. Press F6 to run the application:
   
   
   
   

How It All Works

Much of how all of this works is explained in detail in the resources I list below. I found the RESTful Web Services tutorial and the Getting Started With RESTful Web Services Development articles particularly useful. However, in summary, we have an application flow which looks like the following:

ServletAdapter => RESTBeansResources => Hello

The ServletAdapter is provided by the JAX-RS runtime and loads the generated RESTBeansResources class, which in turn provides the REST resources - Hello in our application. The URL, /hello/restbean/hello, breaks down as follows:

/hello - the context root, configured in sun-web.xml
/restbean - mapped to the ServletAdapter, configured in web.xml
/hello - mapped to the Hello resource, configured using the @UriTemplate annotation in the Hello resource itself.

The Working Application

Admittedly, the application is very simple, but the real point of this post was to get you up and running with JAX-RS in NetBeans 6.0. It should now be possible to continue with the other exercises provided in the tutorial.

• hello.zip.

Resources

• JSR 311: JAX-RS: The Java^TM API for RESTful Web Services
• JSR 311 project at java.net.
• JSR 311 Presentation by specification co-leader Paul Sandoz
• Sun Web Developer Pack
• RESTful Web Services tutorial
• Getting Started With RESTful Web Services Development
• REST API Javadoc