JAX-RS for Power Users Part I

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

Server side request processing pipeline

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 chain

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 chain

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

JAX-RS request to method matching

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

Further exploration

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

PreviousJAX-RS Providers Part IIINextJAX-RS for Power Users Part II

Last updated