Home » Java » Enterprise Java » Quick peek at JAX-RS request to method matching

About Abhishek Gupta

Abhishek Gupta

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 ?

public class Books{
    public List<Book> findAll(){
        //find all books
    public Book findById(@PathParam("id") String bookId){
        //find book by id e.g. /books/123
    public Book findByISBN(@QueryParam("isbn") String bookISBN){
        //find book by ISBN e.g. /books?isbn=xyz
public class Books{
    public List<Movie> findAll(){
        //find all movies e.g. /movies/
    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 !

(0 rating, 0 votes)
You need to be a registered member to rate this.
Start the discussion Views Tweet it!
Do you want to know how to develop your skillset to become a Java Rockstar?
Subscribe to our newsletter to start Rocking right now!
To get you started we give you our best selling eBooks for FREE!
1. JPA Mini Book
2. JVM Troubleshooting Guide
3. JUnit Tutorial for Unit Testing
4. Java Annotations Tutorial
5. Java Interview Questions
6. Spring Interview Questions
7. Android UI Design
and many more ....
I agree to the Terms and Privacy Policy
Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Inline Feedbacks
View all comments