Request Message, Parameters and Contexts

Usually, the resource method has one or more parameters representing a request message body, HTTP headers and different parts of the request URI. The resource method may only have one parameter representing a message body (and none in case of empty requests) but may have many parameters representing the headers or URI parts. @PathParam, @MatrixParam and @QueryParam capture various URI-related values while @HeaderParam and @Cookie capture various HTTP header values. @FormParam or JAX-RS MultivaluedMap can be used to capture name and value pairs of the form sequences.

The method parameter which has no JAX-RS annotations such as @PathParam does represent a request message. JAX-RS MessageBodyReader providers are responsible for reading the input stream and converting the data into this parameter object. JAXB-annotated, JAXP Source, InputStream and some other types are supported out of the box.

Method parameters representing URI parts or HTTP headers are the ones which have annotations such as @PathParam. These parameters are not handled by MessageBodyReader providers. The JAX-RS specification has the conversion rules which instruct the runtime to check the constructors or factory methods accepting Strings.

JAX-RS also introduces Contexts. Contexts represent the state of the request. UriInfo, HttpHeaders, SecurityContext, Request, HttpServeltRequest, etc are contexts which can be injected into the fields of the JAX-RS root resource instance or passed in as method parameters annotated with the @Context annotation. Contexts such as UriInfo, HttpHeaders and Request make it easy to introspect and use the information contained in the current request URI and headers while SecurityContext can be used to check if the current user is in the provided role. Injecting contexts in the fields is usually recommended as it may help simplify the method signatures, for example, given that the query values can be found from the UriInfo context adding explicit @QueryParam parameters to method signatures may not be needed. The runtime will ensure that the contexts injected into the fields of the singleton root resource are thread-safe. For example, here is how a resource method may look like before the introduction of contexts:

@Path("/")
public class BookResource {

   /**
    * Find the books with the id greater or equal to the passed id 
    * and the authors first name equal to the passed name
    */
   @GET
   public Response findBook(@QueryParam("id") Long id, 
      @QueryParam("name") String name) {
      // find the books
   }

}

In the above example, a method contains 2 query parameters. The alternative approach is to introduce a UriInfo context:

@Path("/")
public class BookResource {
   @Context
   private UriInfo context;
   /**
    * Find the books as requested by the user query
    */
   @GET
   public Response findBook() {
      MultivaluedMap<String, String> map = context.getQueryParameters();
      // iterate over the map, check all the query parameters, 
      // find the books
   }
    
}