The REST Way!
Building Web Services in Java - Part 3
JAX-RS has providers that help in mapping between entities and associated Java types. These are called as Entity Providers. The two types of Entity Providers supported by JAX-RS are:
1. MessageBodyReader is a class that is used to map HTTP request entity body to method parameters.
2. MessageBodyWriter is a class that is used to map the return value to the HTTP response entity body. By default, there are some types automatically supported by MessageBodyReader and MessageBodyWriter, they are called as standard types. Following are the standard types:
• byte – All Media types (*/*)
• java.lang.String – All Media types (*/*)
• java.io.InputStream – All Media types (*/*)
• java.io.Reader – All Media types (*/*)
• java.io.File – All Media types (*/*)
• javax.activation.DataSource – All Media types (*/*)
• javax.xml.transform.Source – For XML Media types only
(text/xml, application/xml, application/*+xml)
• javax.xml.bind.JAXBElement and application supplied JAXB classes – For XML Media types only (text/xml, application/xml, application/*+xml)
• MultivaluedMap<String, String> - Form Content (application/x-www-form-urlencoded)
• StreamingOutput - All Media types (*/*), only for MessageBodyWriter If the application chooses not to use any of the standard types, a method can return an object of Response which is built using ResponseBuilder class.
JAX-RS allows one to write custom mapping from/to representation and entity body. Such classes which would provide custom mapping are annotated with @Provider and implements the MessageBodyReader or MessageBodyWriter classes. Entity Provider is also a resource class annotated with @Provider annotation and implements the JAX-RS API. @Provider annotation can be used along with @Produces and @Consumes annotations as demonstrated below:
The value of the stock parameter will be mapped from the request entity body using the StProvider class. Similarly when a mapping has to be done from the representation to the response entity body, StockProvider class will be used.
To get a handle to the deployment environment and the individual request, JAX-RS provides different types of Context to resource class as well as providers. Annotation @Context is used to get the Java types related to request or response. The different types of Context provided by JAX-RS are:
• UriInfo provides information about the components of a request URI. Information about both static and dynamic request URI is provided. However the information provided is valid per request only. An instance of UriInfo is injected to the field of a class or to the parameter of a method using @Context annotation.
• In the above example, Context is used to inject an object of type UriInfo as the method parameter whose methods provide access to request URI information.
• Headers: HttpHeaders provide information about request header. Generally the information is provided in the form of a map. An instance of HttpHeader is injected to the field of a class or to the parameter of a method using @Context annotation. The methods of HttpHeaders provide access to request information.
• Request: Request interface is provided for content negotiation and evaluating certain preconditions. An instance of request is injected to the field of a class or to the parameter of a method using @Context annotation.
• Security: SecurityContext provides information about the security context of the request. With SecurityContext, information about the user, group, and roles can be retrieved from the request and it also helps in identifying the authentication scheme used and whether the request is using https or not. An instance of SecurityContext is injected to the field of a class or to the parameter of a method using @Context annotation.
All the above contexts mentioned are available to all containers where JAX-RS root resource class or a provider is deployed. Apart from these standard ones, @Context annotation can be used to specify container specific resources too. For example, in Servlet Container based environment, @Context can be used to inject dependencies of type HttpServletRequest, HttpServletResponse, ServletConfig and ServletContext.
Frameworks supporting JAX-RS
There are several open source frameworks supporting JAX-RS specification. All of them provide good support for standard server-side JAX-RS APIs and proprietary client APIs. Each one has its own merits and demerits and are used appropriately. Some of them are discussed here:
- Jersey: JAX-RS applications can be developed in Java using Jersey – an open source production quality reference implementation of JAX-RS from Sun/Oracle. Jersey implements all the APIs and provides annotations for easy and quick creation of web services in Java using REST style. Apart from the defined set of annotations and features defined by JAX-RS, Jersey provides a lot of additional features with its own APIs like Jersey Client API. Jersey is available separately for download as well as coming bundled with NetBeans 6.5 along with Glassfish V3 Prelude. Jersey is built completely using Maven. Jersey provides a good integration with frameworks like Spring MVC.
- RESTEasy is a JBoss framework for developing RESTful web services which is fully complaint with the JAX-RS specification. RESTEasy has been designed to run in any Servlet Container, but it is preferred with JBoss Application Server because of its tight integration. An important benefit of RESTEasy is apart from providing complete support for JAX-RS server side APIs; it comes with a powerful RESTEasy JAX-RS Client framework which allows mapping of HTTP requests to remote servers and interface proxies. It provides a good integration with other frameworks like Google Guice, Spring and Spring MVC. It is highly preferred when there is a need for integration with JBoss SEAM.
- Apache CXF is an open source services framework which helps in building web services in Java using both JAX-WS and JAX-RS standards. It supports a variety of protocols ranging from SOAP, REST HTTP and CORBA to transports like JMS, JBI etc. Apache CXF provides a good integration with Spring and JAX-WS services and usage of Maven makes the integration easier. The benefit of Apache CXF is that it provides a pluggable architecture which supports both XML and non XML bindings with any transport.
- Apache Wink is an open source simple yet powerful framework for building RESTful web services in Java. This framework has been exclusively designed for REST support, unlike Apache CXF which supports both SOAP based and REST based web services. Apache Wink comes with two modules:
- a) Wink Server - is JAX-RS complaint server side API. Apart from the standard implementation it provides additional facilities for RESTful web services.
- b) Wink Client – is Java based client framework which helps in consuming RESTful web services. This is extended from HttpURLConnection class available in java.net package.
- Restlet is a leading (most preferred and matured) open source RESTful web framework for Java which is not JAX-RS complaint. Its simplicity and scalability helps to blend server side web applications, web clients and web services into a uniform web application. There are extensions available to integrate with JAX-RS. The benefit of Restlet comes from its unique Java API available for applications built using different platforms like Java SE, Java EE, Google App Engine, Android and Google Web Toolkit.
JAX-RS provides a good support for building RESTful web services in Java. It is simple and provides an easy approach for exposing POJO as a service and supports different types of representations. JCP has already started working on the next version of JAX-RS – JAX-RS 2.0 where the focus is going to be more on the need for a standardized Client API. Discussions are in place to introduce support for hypermedia, integrate matured open source client frameworks from Apache and introduce architecture – MVC compatible with JAX-RS programming model – JAX-RS MVC. All these makes JAXRS a more promising technology/standard for RESTful Web services in Java.
The author would like to sincerely thank Mr. Subrahmanya SV, VP - ECOM Research group for all his encouragements, support and constant motivation. Special thanks to Mr. Nitin KL for quickly reviewing this from the technology perspective.