The REST Way!

Building Web Services in Java - Part 2


Resource Methods

Resource methods are public methods of a 'Resource' class identified with the request method designator annotation. The specification provides a clear mapping to the HTTP protocol and the URI through well defined classes and interfaces. As discussed earlier, in RESTful web services, the HTTP methods are mapped to the CRUD (Create, Read, Update and Delete) operations they perform. Request method designators are annotations that are used to identify the methods that handle the HTTP requests and JAX-RS defines annotations for HTTP methods like GET, POST, PUT, DELETE and HEAD. JAX-RS also allows creating user defined custom request method designators.

The corresponding request method designators are called depending on the HTTP method request. For example, if the request is from a HTTP GET request, method annotated with @GET annotation is automatically invoked and the response is provided. However for HTTP method requests like HEAD and OPTIONS, some amount of automation support is provided. When a HEAD request comes, the method annotated with @HEAD request method designator is invoked, if there is no such request method designator, then by default @GET is invoked without providing any response. However this will have some impact on the performance. The return value of the methods with request designator annotations are generally void, a Java language type or a response object of the type

Resource methods can have a set of parameters. Some of these parameters will have annotations and others will not. The method parameters can be annotated with one of the following annotations:

When the method is invoked, appropriate parameters are mapped depending on the semantics of the request. Parameters that are not annotated are called as Entity Parameters whose values are mapped from the request entity body. The specification does not permit more than one entity parameter per method.

As discussed earlier, the return value of a resource method could be void, a response object or any other Java type. For HTTP requests, to map request entity body to method parameters MessageBodyReader class provided by JAX-RS API is used. Similarly, for HTTP response, to map return value to response entity body, MessageBodyWriter is used. These classes take care of the conversion between the Java types and an entity body. Methods that need to return additional type not part of the standard Java type should return an instance of Response object. Resource methods can also throw any checked or unchecked exceptions.

URI Template

As we know, a root resource class is identified using @Path annotation. The value of the annotation can have a relative URI path template mentioned between the curly braces {,} with a reference to the base URI provided by the deployment context. An URI path template acts as a place holder for relative path URI. URI path template generally is a String with zero or more embedded parameters in it. When the values are applied for the parameters forms a valid URI path.

In the following example, the Stock resource class is identified by the relative URI path stock/abc where abc is the value of the symbol parameter. However '{' and '}' will not appear in the URI as it is not valid, it is used just for the sake of specifying the URI template. The value of the symbol parameter can be retrieved in the method using @PathParam annotation as the parameter value in part of the URI path. URI template parameters can optionally have a regular expression.

Similarly, the parameter annotation @FormParam will be helpful to get the information from the form elements in the request.

Sub Resources

Apart from the Resource class, methods of a resource class can also be annotated with @Path annotation. When the methods are annotated with @Path annotation, the methods are called as sub resource methods or sub resource locators.

Sub Resource Methods

Methods in a resource class that are annotated with @Path annotation along with the request method designator annotation like @GET, @POST, ... are called as Sub Resource Methods. The sub resource methods will be invoked for a URI request that is created by concatenating the URI template of the method with the URI template of the resource class.

In the above example, a GET request from the URI /sayHello/lastname will be handled directly by the hello() sub-resource method in the SayHello resource class.

Sub Resource Locators

Methods in a resource class that are annotated with @Path annotation which are used to dynamically identify the object that will handle the request are called as Sub Resource Locators. The return value for these methods is generally an object of resource class that will handle the request. Sub Resource

Locators are similar to normal resource method but cannot have an entity parameter.

MIME Types supported by JAX-RS for Request and Response

MIME media types are used to identify the HTTP request entities and representations. A resource class can produce or consume any MIME type. Annotations are used to specify the MIME media type for request and response on a resource class or a resource method. Annotation @Produces is used to specify the MIME type for the response (representation that can be produced by a resource and sent back to the client) and @Consumes is used to specify the MIME type for the request (representation that a resource can accept from HTTP request entity or consume the content sent by client). For specifying simple 'text/plain' MIME, @Produces ("text/plain") and @Consumes ("text/plain") will be used.

If the MIME type is HTML, then "text/html" is used as the value for @Produces and @Consumes annotations.

If the value of the annotation @Produces of a resource method is not supported by the HTTP request (if it is not part of the header - Accept in HTTP request), then the resource method will not be invoked. Similarly if the value of the annotation @Consumes of a resource method does not match with the header - Content-Type in HTTP request, the resource method will not be invoked. If these annotations are not present, then any of the MIME types (*/*) is supported.



S Sangeetha
S Sangeetha

What do you think?

JAX Magazine - 2014 - 03 Exclucively for iPad users JAX Magazine on Android


Latest opinions