RSS Feed
Download our iPhone app
Browse DevX
Sign up for e-mail newsletters from DevX


JAX-RS: Developing RESTful Web Services in Java : Page 2

Learn how the JAX-RS API and annotations enable you to develop REST-based web services in Java.


The Resource Class

JAX-RS defines a resource as any Java class (POJO) that uses JAX-RS annotations to implement a web resource. The annotation @Path identifies a Java class as a resource class. Here is an example:

import javax.ws.rs.Path;

public class StockResource {
    public String getStockInfo() {
        return "This is Stock Information";

To invoke the above class with a value matching a corresponding URI value, you would:

  1. Package the class as part of a WAR file, with an entry for the Servlet provided in the web.xml file of your JAX-RS implementation.
  2. Deploy the WAR file in a container that supports the JSR 311 specification (GlassFish, for example)
  3. Access the resource using the usual URI: http://hostname:portnumber/WARfilename/stockquote

A new instance of the resource class will be created for each request to that resource. After the object creation, the constructor is invoked, the required dependencies are injected, the appropriate resource method is invoked, and when the response is provided, the object is made available for garbage collection. Figure 1 shows the full resource class lifecycle.

Figure 1. Resource Class Lifecycle: A new instance of the resource class will be created for each request to that resource.

Resource Methods

Resource methods are public methods of a resource class that you identify with a request method designator. Request method designators are annotations that you use to identify the methods that handle the HTTP requests, and JAX-RS defines annotations for HTTP methods such as GET, POST, PUT, DELETE, and HEAD. JAX-RS also allows you to create user-defined custom request method designators.

JAX-RS provides a clear mapping between the HTTP protocol and the URIs through well-defined classes and interfaces (see Table 2). As mentioned earlier, in RESTful web services, the HTTP methods are mapped to the CRUD operations they perform.

Table 2. HTTP Methods and Corresponding Request Method Designators

The type of HTTP method request dictates which request method designator is called. For example, if the request is from a HTTP GET request, the service automatically invokes a method annotated with @GET and provides the response.

For HTTP method requests such as HEAD and OPTIONS, JAX-RS provides some amount of automation support. When a HEAD request comes, a method annotated with the @HEAD request method designator is invoked. If no such request method designator exists, then by default the service invokes @GET without providing any response. However, this will have some impact on performance.

The return values of methods with request designator annotations are generally void, a Java language type, or a response object of the type javax.ws.rs.core.Response. Here is an example:

package com.demo;

import javax.ws.rs.Path;
import javax.ws.rs.GET;
import javax.ws.rs.PUT;

public class DemoResource {
    /** Creates a new instance of DemoResource */
    public DemoResource() {
     * Retrieves representation of an instance of com.demo.DemoResource
     * @return an instance of java.lang.String
    public String getXml() {

     * PUT method for updating or creating an instance of DemoResource
     * @param content representation for the resource
     * @return an HTTP response with content of the updated or created resource.
    public void putXml(String content) {

Resource methods can have a set of parameters. Some of these parameters will have annotations and others will not. You can annotate the method parameters with one of the annotations in Table 3.

Table 3. Parameter Annotations

package com.demo;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.QueryParam;

public class DisplayDetails {
    public DisplayDetails() {
    public String getHtml(@QueryParam("empname") String empName,
    @QueryParam("empnumber") int empNumber,
    @QueryParam("empunit") String empUnit,
    @QueryParam("empmail") String empMail) {
    StringBuilder str = new StringBuilder(" Hello, Mr./Ms.  "+empName+"  Welcome to the world of JAX-RS");
    str = str.append("
Your Employee Number is: "+empNumber+""); str = str.append("
Your Unit is: "+empUnit+""); str = str.append("
Your Email ID is: "+empMail+""); return str.toString(); } }

When the method is invoked, the appropriate parameters are mapped according to the semantics of the request. Parameters that are not annotated are called as entity parameters whose value is mapped from the request entity body. The JAX-RS specification does not permit more than one entity parameter per method.

As previously discussed, the return value of a resource method could be void, a response object, or any other Java type. For HTTP requests, you use the JAX-RS API's MessageBodyReader class to map the request entity body to method parameters. Similarly, for HTTP responses, you use MessageBodyWriter to map a return value to the response entity body. These classes take care of the conversion between the Java types and entity bodies. Methods that need to return additional types that are not part of the standard Java types should return an instance of the response object. Resource methods can also throw any checked or unchecked exception.

Table 4 explains how a return value of a resource method maps to the response.

Table 4. Return Value of Resource Method

Close Icon
Thanks for your registration, follow us on our social networks to keep up-to-date