type=page
status=published
title=Subresources and Runtime Resource Resolution
next=jaxrs-advanced004.html
prev=jaxrs-advanced002.html
~~~~~~
Subresources and Runtime Resource Resolution
============================================

[[GKNAV]]

[[subresources-and-runtime-resource-resolution]]
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.

The following topics are addressed here:

* link:#GKLAG[Subresource Methods]
* link:#GKRHR[Subresource Locators]

[[GKLAG]]

[[subresource-methods]]
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:

[source,oac_no_warn]
----
@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:

[source,oac_no_warn]
----
GET /employeeinfo/employees/john.doe@example.com
----

[[GKRHR]]

[[subresource-locators]]
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:

[source,oac_no_warn]
----
// 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`.


