Root resource classes

Overview

A root resource class is the entry point into a JAX-RS implemented RESTful Web service. It is decorated with a  @Path  that specifies the root URI of the resources implemented by the service. Its methods either directly implement operations on the resource or provide access to sub-resources.

Requirements

In order for a class to be a root resource class it must meet the following criteria:

The class must be decorated with the  @Path  annotation. The specified path is the root URI for all of the resources implemented by the service. If the root resource class specifies that its path is  widgets  and one of its methods implements the  GET  verb, then a  GET  on  widgets  invokes that method. If a sub-resource specifies that its URI is  {id} , then the full URI template for the sub-resource is  widgets/{id}  and it will handle requests made to URIs like  widgets/12  and  widgets/42 .
The class must have a public constructor for the runtime to invoke. The runtime must be able to provide values for all of the constructor's parameters. The constructor's parameters can include parameters decorated with the JAX-RS parameter annotations. For more information on the parameter annotations see  Passing Information into Resource Classes and Methods .
At least one of the classes methods must either be decorated with an HTTP verb annotation or the  @Path  annotation.

Example

Example 2.3  shows a root resource class that provides access to a sub-resource.
Example 2.3. Root resource class

package demo.jaxrs.server;



import javax.ws.rs.DELETE;

import javax.ws.rs.GET;

import javax.ws.rs.POST;

import javax.ws.rs.PUT;

import javax.ws.rs.Path;

import javax.ws.rs.PathParam;

import javax.ws.rs.QueryParam;

import javax.ws.rs.core.Response;



@Path("/customerservice/") 

public class CustomerService

{

  public CustomerService() 

  {

    ...

  }



  @GET 

  public Customer getCustomer(@QueryParam("id") String id)

  {

    ...

  }



  @DELETE

  public Response deleteCustomer(@QueryParam("id") String id)

  {

    ...

  }



  @PUT

  public Response updateCustomer(Customer customer)

  {

    ...

  }



  @POST

  public Response addCustomer(Customer customer)

  {

    ...

  }



  @Path("/orders/{orderId}/") 

  public Order getOrder(@PathParam("orderId") String orderId)

  {

    ...

  }



}

The class in  Example 2.3  meets all of the requirements for a root resource class.
The class is decorated with the  @Path  annotation. The root URI for the resources exposed by the service is  customerservice .
The class has a public constructor. In this case the no argument constructor is used for simplicity.
The class implements each of the four HTTP verbs for the resource.
The class also provides access to a sub-resource through the  getOrder()  method. The URI for the sub-resource, as specified using the the  @Path  annotation, is  customerservice/order/id . The sub-resource is implemented by the Order  class. For more information on implementing sub-resources see  Working with sub-resources .