Subresources and Runtime Resource Resolution
You can use a resource class to process only a part of the URI request. A root resource can then implement subresources that can process the remainder of the URI path.
A resource class method that is annotated with @Path is either a subresource method or a subresource locator:
- A subresource method is used to handle requests on a subresource of the corresponding resource.
- A subresource locator is used to locate subresources of the corresponding resource.
Subresource Methods
A subresource method handles an HTTP request directly. The method must be annotated with a request method designator such as @GET or @POST, in addition to @Path. The method is invoked for request URIs that match a URI template created by concatenating the URI template of the resource class with the URI template of the method.
The following code snippet shows how a subresource method can be used to extract the last name of an employee when the employee’s email address is provided:
@Path("/employeeinfo")
Public class EmployeeInfo {
public employeeinfo() {}
@GET
@Path("/employees/{firstname}.{lastname}@{domain}.com")
@Produces("text/xml")
public String getEmployeeLastName(@PathParam("lastname") String lastName) {
...
}
}
The getEmployeeLastName method returns doe for the following GET request:
GET /employeeinfo/employees/john.doe@example.com
Subresource Locators
A subresource locator returns an object that will handle an HTTP request. The method must not be annotated with a request method designator. You must declare a subresource locator within a subresource class, and only subresource locators are used for runtime resource resolution.
The following code snippet shows a subresource locator:
// Root resource class
@Path("/employeeinfo")
public class EmployeeInfo {
// Subresource locator: obtains the subresource Employee
// from the path /employeeinfo/employees/{empid}
@Path("/employees/{empid}")
public Employee getEmployee(@PathParam("empid") String id) {
// Find the Employee based on the id path parameter
Employee emp = ...;
...
return emp;
}
}
// Subresource class
public class Employee {
// Subresource method: returns the employee's last name
@GET
@Path("/lastname")
public String getEmployeeLastName() {
...
return lastName
}
}
In this code snippet, the getEmployee method is the subresource locator that provides the Employee object, which services requests for lastname.
If your HTTP request is GET /employeeinfo/employees/as209/, the getEmployee method returns an Employee object whose id is as209. At runtime, JAX-RS sends a GET /employeeinfo/employees/as209/lastname request to the getEmployeeLastName method . The getEmployeeLastName method retrieves and returns the last name of the employee whose id is as209.
