Java EE Notes: rest

Like Servlets, the container uses one instance of a web service class to handle incoming web service requests, which is the default behavior. Ofcourse, you can make the web service thread-safe by adding the synchronized method to the exposed methods like the following code:


@WebService
public class ExampleWS {
    public synchronized void doSomething() {
        ;
    }

    public synchronized void doSomethingElse() {
        ;
    }
}

By doing this, you eliminate the possibility of parallel or concurrent handling of incoming requests. In order to support concurrent processing, you can mark the web service class as thread scoped by using the @ThreadScope annotation.


import org.jvnet.jax_ws_commons.thread_scope.ThreadScope;

@WebService
@ThreadScope
public class ExampleWS {
    public synchronized void doSomething() {
        ;
    }

    public synchronized void doSomethingElse() {
        ;
    }
}

The added annotation will force the container to create a new instance of the web service class for every thread (ie. every request). Instances will not be shared by threads.

This tutorial demonstrates how RESTful services are created using JAX-RS. We'll be using Glassfish as our primary application server. This tutorial is limited to reading representational objects. For implementation information about CRUD-operations and REST, I recommend the following online book.

The tutorial consists of the following steps:

1. Define URLs
2. Define data format
3. Configure JAX-RS in web.xml
4. Create REST POJO's
5. Test application with URLs

1. Define URLs

The first step is define the URLs we'll be using in accessing the REST objects. For this example, we define four relative URLs:

1. All departments: /departments/
2. Department by ID: /departments/{id}
3. All employees: /employees/
4. Employee by ID: /employees/{id}

The {id} is the ID parameter, which should be an integer number.

2. Define data format

In this step we have to choose how we want to format the object for the client. Commonly, this will be either XML or JSON. The latter one is definitely preferred if AJAX is handling the output. But for this tutorial, we'll be using XML.


<department id="12345">
  <link rel="self" href="/departments/12345" />
  <name>Solutions Development</name>
</department>


<employee id="1580">
  <link rel="self" href="/employees/1580" />
  <firstName>Gin Lung</firstName>
  <lastName>Cheng</lastName>
  <department id="12345">
    <link rel="self" href="/departments/12345" />
  </department>
</employee>

3. Configure JAX-RS in web.xml

Now, we need to configure the application server to support RESTful services by putting the following XML-code in the web.xml file inside the <web-app>-element:


<servlet>
  <servlet-name>Jersey Web Application</servlet-name>
  <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
  <load-on-startup>1</load-on-startup>
</servlet>

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

This tells our application server that we want URLs that start with /rs/ are handled by the JAX-RS Servlet.

4. Create REST POJO's

Create the POJO's that contain the methods behind the URLs. For demonstration purposes, the output is hardcoded. Normally, content is retrieved from a database, and converted to XML with JAX-B.

DepartmentService.java


package com.javaeenotes;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;

@Path("/departments")
public class DepartmentService {

  @GET
  @Produces("application/xml")
  public String showDepartments() {
    // Return all departments.
    return "<department id=\"12345\">"
      + "<link rel=\"self\" href=\"/departments/12345\" />"
      + "<name>Solutions Development</name>"
      + "</department>";
  }

  @Path("{id}")
  @GET
  @Produces("application/xml")
  public String showDepartment(@PathParam("id") int id) {
    // Return department by ID.
    return "<department id=\"" + id + "\">"
      + "<link rel=\"self\" href=\"/departments/" + id + "\" />"
      + "<name>Solutions Development</name>"
      + "</department>";
  }
}

EmployeeService.java


package com.javaeenotes;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;

@Path("/employees")
public class EmployeeService {

  @GET
  @Produces("application/xml")
  public String showEmployees() {
    // Return all employees.
    return "<employee id=\"1580\">"
      + "<link rel=\"self\" href=\"/employees/1580\" />"
      + "<firstName>Gin Lung</firstName>"
      + "<lastName>Cheng</lastName>"
      + "<department id=\"12345\">"
      + "<link rel=\"self\" href=\"/departments/12345\" />"
      + "</department>"
      + "</employee>";
  }

  @Path("{id}")
  @GET
  @Produces("application/xml")
  public String showEmployee(@PathParam("id") int id) {
    // Return employee by ID.
    return "<employee id=\"" + id + "\">"
      + "<link rel=\"self\" href=\"/employees/" + id + "\" />"
      + "<firstName>Gin Lung</firstName>"
      + "<lastName>Cheng</lastName>"
      + "<department id=\"12345\">"
      + "<link rel=\"self\" href=\"/departments/12345\" />"
      + "</department>"
      + "</employee>";
  }
}

5. Test application with URLs
If you deployed your application on a default install of Glassfish on your computer, the objects can be retrieved using the following URLs:

http://localhost:8080/restfulservices/rs/departments
http://localhost:8080/restfulservices/rs/departments/12345
http://localhost:8080/restfulservices/rs/employees
http://localhost:8080/restfulservices/rs/employees/1580

If you use Firefox to do this, remember that Firefox will render XML-tags invisible. Try to view the source of the page.

Java EE Notes

Sunday, March 13, 2011

Thread scoped JAX-WS webservices

Saturday, February 5, 2011

RESTful webservices using JAX-RS

Monday, September 6, 2010

SoapUI