Developing JAX-RS resources

JAX-RS resources are developed by using annotations defined within the JAX-RS specification. This enables fast development time and eliminates the need for excessive deployment descriptor information. The following steps will outline the process for developing a simple JAX-RS Address Book resource.

  1. Configure a development environment

    The previous step includes instructions for configuring a development environment for writing JAX-RS resources.
  2. Develop the resource class

    Develop a sample, such as the Address Book resource using JAX-RS annotations. For example, the following sample is developed to provide access to a list of names in an address book. There is a resource method for access the entire list and a resource method for accessing individual names. 

    package com.test;

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

/**
 * A sample resource that provides access to 
 * server configuration properties
 */
@Path(value="/addresses")
public class AddressBook {
    
    private static String[] list = new String[] {
        "Michael",
        "Ron",
        "Jane",
        "Sam"
    };
    
    @GET
    @Produces(value="text/plain")
    public String getList() {
        StringBuffer buffer = new StringBuffer();
        buffer.append("{");
        for (int i = 0; i < list.length; ++i) {
            if (i != 0) 
                buffer.append(", ");
            buffer.append(list[i]);
        }
        buffer.append("}");
        
        return buffer.toString();
    }

    @GET
    @Produces(value="text/plain")
    @Path(value="{id}")
    public String getPropety(@PathParam("id") int id) {
        if (id > -1 && id < list.length -1) {
            return list[id];
        }
        else {
            return "Name Not Found";
        }
    }

}

    In this example, we are specifying the AddressBook class as a root resource by placing the @Path annotation on the class. In addition, the 'getAddresses' method is mapped to an HTTP GET request by use of the @GET annotation. The @Produces annotation specifies that a MIME type of "text/plain" will be produced by invoking this method.

    The 'getAddress' method is mapped to an HTTP GET request as well, but also has a parameter that can be included in the request URL. This parameter will be mapping to the "id" input parameter on the method signature and can be used by the resource during invocation.

    The table below summarizes the resources available from this sample:

    Table 1. URI Overview
    HTTP Method URI Input Type(s) Output Type(s) Note(s)
    GET /addresses n/a text/plain n/a
    GET /addresses/{id} n/a text/plain n/a
  3. Deploy the resource

    Deploy your JAX-RS resource to the web container of your choice. This will make it available for testing.
  4. Test the resource

    Once deployed, the easiest way to test this resource is through a browser. The fact that the resource methods are based on an HTTP GET enables this. If the resource methods were another type of request, like a POST, it would require a client that could submit data to the resource. (Note: an HTML form is capable of handling this)



    First try accessing the full list of names available. The URL you use will be different in that the host will be whatever host your web container is running on and the context root will be whatever you specified during your application deployment. For example, if installed the application with a context root of "/rest", then your URL could look like: http://localhost:9080/rest/addresses. The return content should look like the image below.



    Now try targeting the second resource method available. The URI for this resource is a slight extension of the previous one. Include one of the available indexes to retrieve that entry from the list. This would be similar to providing a unique identifier to a record in a database that represents the resource you are looking for. The URL for a specific resource would be http://localhost:9080/rest/addresses/2 where the number at the end is the unique identifier. The returned content should match the image below.