@Path may be used on classes and such classes are referred to as root resource classes. @Path may also be used on methods of root resource classes. This enables common functionality for a number of resources to be grouped together and potentially reused.
The first way @Path may be used is on resource methods and such methods are referred to as sub-resource methods. The following example shows the method signatures for a root resource class from the jmaki-backend sample:
@Singleton @Path("/printers") public class PrintersResource { @GET @Produces({"application/json", "application/xml"}) public WebResourceList getMyResources() { ... } @GET @Path("/list") @Produces({"application/json", "application/xml"}) public WebResourceList getListOfPrinters() { ... } @GET @Path("/jMakiTable") @Produces("application/json") public PrinterTableModel getTable() { ... } @GET @Path("/jMakiTree") @Produces("application/json") public TreeModel getTree() { ... } @GET @Path("/ids/{printerid}") @Produces({"application/json", "application/xml"}) public Printer getPrinter(@PathParam("printerid") String printerId) { ... } @PUT @Path("/ids/{printerid}") @Consumes({"application/json", "application/xml"}) public void putPrinter(@PathParam("printerid") String printerId, Printer printer) { ... } @DELETE @Path("/ids/{printerid}") public void deletePrinter(@PathParam("printerid") String printerId) { ... } }
If the path of the request URL is "printers" then the resource methods not annotated with @Path will be selected. If the request path of the request URL is "printers/list" then first the root resource class will be matched and then the sub-resource methods that match "list" will be selected, which in this case is the sub-resource method getListOfPrinters
. So in this example hierarchical matching on the path of the request URL is performed.
The second way @Path may be used is on methods not annotated with resource method designators such as @GET or @POST. Such methods are referred to as sub-resource locators. The following example shows the method signatures for a root resource class and a resource class from the optimistic-concurrency sample:
@Path("/item") public class ItemResource { @Context UriInfo uriInfo; @Path("content") public ItemContentResource getItemContentResource() { return new ItemContentResource(); } @GET @Produces("application/xml") public Item get() { ... } } public class ItemContentResource { @GET public Response get() { ... } @PUT @Path("{version}") public void put( @PathParam("version") int version, @Context HttpHeaders headers, byte[] in) { ... } }
The root resource class ItemResource
contains the sub-resource locator method getItemContentResource
that returns a new resource class. If the path of the request URL is "item/content" then first of all the root resource will be matched, then the sub-resource locator will be matched and invoked, which returns an instance of the ItemContentResource
resource class. Sub-resource locators enable reuse of resource classes.
In addition the processing of resource classes returned by sub-resource locators is performed at runtime thus it is possible to support polymorphism. A sub-resource locator may return different sub-types depending on the request (for example a sub-resource locator could return different sub-types dependent on the role of the principle that is authenticated).
Note that the runtime will not manage the life-cycle or perform any field injection onto instances returned from sub-resource locator methods. This is because the runtime does not know what the life-cycle of the instance is.