Quick Peek at JAX-RS Request to Method Matching

In this post, let’s look at the HTTP request to resource method matching in JAX-RS. It is one of the most fundamental features of 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). Hats off to the JAX-RS spec doc for explaining this in great detail (we’ll just cover the tip of the iceberg in this post though!)

Primary criteria

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

High level steps

A rough diagram should help. Before we look at that, here is the example scenario

• Two resource classes – Books.java, Movies.java
• Resource methods paths in Books.java – /books/, /books/{id} (URI path parameter), /books?{isbn} (URI query parameter)
• HTTP request URI – /books?isbn=xyz

Who will win ?

@Path("books")
public class Books{
    @Produces("application/json")
    @GET
    public List<Book> findAll(){
        //find all books
    }
    @Produces("application/json")
    @GET
    @Path("{id}")
    public Book findById(@PathParam("id") String bookId){
        //find book by id e.g. /books/123
    }
    @Produces("application/json")
    @GET
    public Book findByISBN(@QueryParam("isbn") String bookISBN){
        //find book by ISBN e.g. /books?isbn=xyz
    }
}

@Path("movies")
public class Books{
    @Produces("application/json")
    @GET
    public List<Movie> findAll(){
        //find all movies e.g. /movies/
    }
    @Produces("application/json")
    @GET
    @Path("{name}")
    public Movie findById(@PathParam("name") String name){
        //find movie by name e.g. /movies/SourceCode
    }
}

JAX-RS request to method matching process

Break down of what’s going on

• 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)
• Boil down to the exact method which can server the HTTP request

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

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

• MatchResultInitializerRouter
• SubResourceLocatorRouter
• MethodSelectingRouter
• PathMatchingRouter

Time to dig in….?

Happy hacking !