Having discussed subresources, we will now see a subresource locator.

It is perfectly legal to use the @Path annotations on methods in a REST resource class without any resource method designators such as @GET, @POST, @PUT, or @DELETE. The objects returned by these methods will be used for resolving the incoming HTTP request further. These methods are called the subresource locators. These locators are useful when requests need to be further resolved dynamically by other objects. This gives you more flexibility in implementation.

In the following example, DepartmentResource is the root resource and the findManagerForDepartment() method is a subresource locator method. The findManagerForDepartment() method has only the @Path annotation in the code snippet. The EmployeeResource object returned by this method further resolves the HTTP request:

// Imports are omitted for brevity 
@Path("departments") 
public class DepartmentResource { 
    
    //Sub-resource locator method 
    @Path("{id}/manager") 
    public EmployeeResource  
        findManagerForDepartment(@PathParam("id")  
        Short deptId) { 
        //Find the department for id 
        Department department = findDepartmentEntity(deptId); 
        //Create the instance of Employee object 
        //This instance will be used for further resolving request 
        EmployeeResource employeeResource = new  
            EmployeeResource(department.getManagerId()); 
        return employeeResource; 
    } 
//Other methods are omitted for brevity 
} 
 
/** 
  *This class that defines the subresource used in  
  *DepartmentResource 
*/ 
//imports are omitted for brevity  
public class EmployeeResource{ 
    Short employeeId; 
    public EmployeeResource(Short employeeId){ 
        this.employeeId=employeeId; 
    } 
    //Resolves GET request to findEmployee() method 
    @GET  
    @Produces(MediaType.APPLICATION_JSON) 
    public Employee findEmployee(){ 
        Employee employee = findEmployeeEntity(employeeId); 
        return employee; 
    } 
    //Other methods are omitted for brevity 
 
} 

In this example, let's see what happens on the server when a client calls the HTTP GET method with the following URI: departments/10/manager.

The JAX-RS runtime on the server resolves the URI part of the HTTP request to the findManagerForDepartment() method defined on the DepartmentResource class. The runtime further resolves the request on the EmployeeResource object returned by the findManagerForDepartment() method and identifies the findEmployee() that matches the HTTP request type. The HTTP request will be then dispatched to the findEmployee() method defined on the EmployeeResource instance. 

In the preceding example, you are managing the life cycle of the subresource by creating an instance of EmployeeResource in the code and returning it from the findManagerForDepartment() method. You can ask the JAX-RS runtime to manage the subcomponent instance by returning the class instead of an instance, as given in the following code:

@Path("{id}/manager") 
public Class<EmployeeResource>  
    findManagerForDepartment(@PathParam("id") Short deptId) { 
    return EmployeeResource.class; 
} 

In this case, the runtime will manage the initialization of the subresource instance (EmployeeResource), including all dependency injections via Context and Dependency Injection (CDI), if any. If you are not familiar with CDI, go through the tutorial available at http://docs.oracle.com/javaee/7/tutorial/partcdi.htm.