JAX-RS Request Handling

Introduction

Creation and handling of API requests are very important while implementing RESTful services. Invoking a request, mapping of the request, handling the request call and responding to it, etc. are very essential steps in building RESTful services. In this article, let’s have a look at how the Java REST library, JAX-RS handles requests from the clients.

JAX-RS Request Handling

There are multiple stages for handling a request in JAX-RS. The diagram below shows some of the main aspects of JAX-RS request handling.

 

 

JAX-RS uses annotations at the server-side for handling requests from the client. Different types of annotations match different use cases. We are going to have a look at those annotations that are used while handling a client-side API request.

@Path Annotation

If you want a Java class to be able to handle REST requests, the class must add at least one @Path (“/”)” annotation. The value of this @Path variable can be simple strings to complex regular expressions.

Some of the things that we must know about the @Path annotations are:

Priority Check Rules

•  First, check the number of matching characters in a @Path.
•  Second, check the number of embedded template expressions.
•  Finally check the number of non-default template expressions.

Path Characters

If the expression in the path contains characters that need to be escaped, it will be escaped automatically. Otherwise, the URL encoding will be thought and performed. Here the following characters are allowed.

 a-z, A-Z, 0-9, -!. ~'()*

The following characters are reserved as escape characters.

 ??$??/? @

Sub-resource locators

If a method that specifies @Path annotations but does not specify HTTP method annotations returns another resource class object that then distributes and processes requests for sub-resources. Sub-resource classes do not need to be exposed as services, so the class can be without @Path annotation.

Consider the following example, here @Path(“{database}-dB”) servers as the sub-resource locator.

 

public class CustomerData    { ……      @Path(“{database}-dB”)      public CustomerDatabase getDatabase(@PathParam(“database”) String dataBase)       {         // find the instance based on the dataBase parameter         CustomerRecord resource = locateCustomerRecord(dataBase);         return resource;        }        …..     }

 

 

 

The @Consumes annotation

This annotation specifies which media type a resource can accept at the server-side from an API request. This is important to specify while creating or updating resources at the server side using REST APIs.

If this annotation is applied at the class level, all the methods in the class accept the same media type by default. When there is a method that applies @Consumes at a method level, that will override the class level annotation.

The value of @Consumes is a string array with acceptable media types. For example: @Consumes({“text/plain,text/html”})

Request Method Annotations

The request method annotations are used to map the HTTP methods to Java programming language methods. These are run-time annotations defined by JAX-RS.

They correspond to the similarly named HTTP methods. JAX-RS defines @GET, @POST, @PUT, @DELETE, and @HEAD as common request method annotations. You can also create your own custom request method annotations.

Methods decorated with request method annotations must return a void or a javax.ws.rs.core.Response Object.

Extracting Request Parameters

When we create an API request, we can include different parameters into it so that we can extract information at the server side based on these parameters.

The following types of parameters can be extracted from a given request.

1. Query

Query parameters are specified by @QueryParam in the method parameter arguments. One must import javax.ws.rs.QueryParam class for this. The following example demonstrates application of

                                                                 

@QueryParam.   @Path(“smooth”)   @GET   public Response smooth(      @DefaultValue(“2”) @QueryParam(“count”) int count,      @DefaultValue(“true”) @QueryParam(“has-min”) boolean hasMin)           {             ……….           }

 

Here one thing to note is the use of @DefaultValue annotation. They are used to set a specific value to the request if there is no value is provided by the client while using a specific @QueryParam

2. URI path

URI path parameters are extracted from the URI request itself. The parameter name is included in the @Path annotation. In the java method arguments, they are specified using the @PathParam annotations.

For example:

                                                                             

@Path(“/{name}”)   public class UserNamePrinter    {      ……    @GET      public String printUserName(@PathParam(“name”) String userID)      {        ……..         }     }

 

3. Form

Form parameters use the @FormParam annotation and extract information from a request that is of the MIME media type application/x-www-form-urlencoded and conforms to the HTML form encoding specifications. They are mostly used when information is sent in HTML form using the POST method.

4. Cookie

Cookie parameters extract information from the cookie-related HTTP headers. It uses @CookieParam annotation.

5. Header

Header parameters extracts information from the HTTP headers. Here we use @HeaderParam annotation. One must include the javax.ws.rs.HeaderParam class for using this annotation.

6. Matrix

Header parameters extracts information from the URL path segments. The annotation for the Matrix request parameter is @MatrixParam. The class is located in javax.ws.rs.MatrixParam.

Summary

JAX-RS uses annotations at the server side for handling API requests and there are specific annotations for handling requests from a client-side API. Forming a correct URI, specifying the media types, extracting information from the URI, etc are some of the important steps while processing an API request at the server-side.