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
Time to dig in….?
Happy hacking !
| Reference: | Quick peek at JAX-RS request to method matching from our JCG partner Abhishek Gupta at the Object Oriented.. blog. |
