@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:
Example 3.17. Sub-resource methods
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:
Example 3.18. Sub-resource locators
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. A method can be annotated with the @Path annotation with empty path (
@Path("")) which means that the sub resource locator is matched for the path of the enclosing resource (without sub-resource path).
Example 3.19. Sub-resource locators with empty path
In the example above the sub-resource locator method
getItemContentResource is matched for example for request path "/item/locator" or even for only "/item".
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). So for example the following sub resource locator is valid:
Example 3.20. Sub-resource locators returning sub-type
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. If it is required that the runtime manages the sub-resources as standard resources the
Class should be returned as shown in the following example:
Example 3.21. Sub-resource locators created from classes
JAX-RS resources are managed in per-request scope by default which means that new resource is created for each request. In this example the
javax.inject.Singletonannotation says that the resource will be managed as singleton and not in request scope. The sub-resource locator method returns a class which means that the runtime will managed the resource instance and its life-cycle. If the method would return instance instead, the
Singleton annotation would have no effect and the returned instance would be used.
The sub resource locator can also return a programmatic resource model. See resource builder section for information of how the programmatic resource model is constructed. The following example shows very simple resource returned from the sub-resource locator method.
Example 3.22. Sub-resource locators returning resource model
The code above has exactly the same effect as previous example.
Resource is a resource simple resource constructed from
ItemContentSingletonResource. More complex programmatic resource can be returned as long they are valid resources.