JAX-RS for Power Users Part I
Last updated
Last updated
In the upcoming chapters (including this one), we are going to bump things up a bit and go beyond the basics. This lesson covers
JAX-RS server side processing pipeline
Request to method matching
The inspiration for this section was the Processing Pipeline section in the JAX-RS 2.0 specification doc (Appendix C). I like it because of the fact that it provides a nice snapshot of all the modules in JAX-RS in the form of a ready to gulp capsule !
So I thought of using this diagram to provide a brief overview of the different JAX-RS components and how they orchestrate with each other. This chapter will make sense, now that we understand Entity Providers (Filters, Interceptors etc.)
What's discussed here is the server side processing pipeline i.e. the sequence of actions which are triggered after the client sends an HTTP request (GET, POST, PUT etc). It all begins when the client (browser or custom REST client) sends an HTTP request to a REST endpoint
The goal is to educate you in terms of what happens behind the scenes and more importantly, in which order. The intricate details of components like filters, interceptors etc. have not been repeated since they were covered in the previous chapter(s)
Request Filters
JAX-RS Filters are the first in a series of components which handle the HTTP request
Method matching
After (successful) filter execution, the JAX-RS run time initiates the resource method matching process.
This chapter has a sub-section dedicated to this topic in case you want to explore it in details
Here is a quick peek
The exact method to be invoked is based on the algorithm outlined by the specification (although JAX-RS providers are not bound by it)
It's determined by a combination of below mentioned annotations
@GET, @PUT, @POST, @DELETE etc - these are the annotations which should match up to the actual HTTP operation (the mapping of the annotation to the HTTP verb is rather obvious)
@Path - its value (relative to the context root) is used to map the request URI e.g. /tweeters/all
@Consumes - its values should match the Content-Type header value sent in the HTTP request
@Produces - its values should match the Accept header value sent in the HTTP request
HTTP components injection
After the method matching is complete, the required HTTP components get injected into JAX-RS Resource classes (if configured) by the the JAX-RS run time. All we need to do is use the appropriate annotation
Request Interceptors
Interceptors come into play in case the HTTP payload is transformed by custom entity providers (Message Body Readers)
Entity Providers (converting HTTP request payload to Java type)
Entity Providers help in conversion of HTTP message payload to its appropriate Java type (for injection into the method parameters of JAX-RS resource classes) and vice versa
Response Filter
Response Filters are similar to their Request-centric counterparts
Response Interceptors (chain)
They are invoked only when a MessageBodyWriter (see next topic) is registered to handle outgoing HTTP payload
Entity Providers
They deal with conversion of Java objects (within the application code) to HTTP response payloads
Let's look at the HTTP request to resource method matching in JAX-RS. Generally, the developers using the JAX-RS API are not exposed to (or do not really need to know) the nitty gritty of the matching process, rest assured that the JAX-RS runtime churns out its algorithms quietly in the background as our RESTful clients keep those HTTP requests coming! Just in case the term request to resource method matching is new to you - it's nothing but the process via which the JAX-RS provider dispatches a HTTP request to a particular method of your one of your resource classes (decorated with @Path)
What are the factors taken into consideration during the request matching process ?
HTTP request URI
HTTP request method (GET, PUT, POST, DELETE etc)
Media type of the HTTP request
Media type of requested response
Here is what happens at runtime
Narrow down the possible matching candidates to a set of resource classes. This is done by matching the HTTP request URI with the value of the @Path annotation on the resource classes
From the set of resource classes in previous step, find a set of methods which are possible matching candidates (algorithm is applied to the filtered set of resource classes)
The HTTP request verb is compared against the HTTP method specific annotations (@GET, @POST etc), the request media type specified by the Content-Type header is compared against the media type specified in the @Consumes annotation and the response media type specified by the Accept header is compared against the media type specified in the @Produces annotation.
Boil down to the exact method which can serve the HTTP request
The above mentioned process is known as Content Negotiation and this topic is covered in details in another chapter
I would highly recommend looking at the Jersey server side logic for implementation classes in the org.glassfish.jersey.server.internal.routing package to get a deeper understanding. Some of the classes/implementation which you can look at are
