JavaEE 6 release includes Java API for RESTful Web Services (JAX-RS) support which provides a POJO based framework to build lightweight web services that conform to the Representational State Transfer (REST) style of software architecture. JAX-RS API, which is part of JSR 311, offers several annotations that can be used to expose Java class methods as web resources.
JAX-RS automatically translates between Java types and MIME media types. For example, if you mark a class method with annotation "@Produces (MediaType.TEXT_PLAIN)", JAX-RS would translate the Java type to the "text/plain" MIME type, which represents plain text, and return content of that type in the HTTP response to the client.
Java EE 6 includes the latest release of the technology, JAX-RS 1.1, which is a maintenance release that aligns JAX-RS with new features in Java EE 6. Jersey is the open source Reference Implementation for JAX-RS specification. Jersey 1.1.5 version implements JAX-RS 1.1.
The annotations add the information needed to identify resources and serve HTTP requests. Some of the annotations supported by JAX-RS are as follows:
Path: This annotation specifies a relative path for the resource. @Path identifies the URI path that a resource class or class method will serve requests for.
GET: The @GET annotation specifies that the annotated method handles HTTP GET requests. When a client directs an HTTP GET request to the URI for the web resource, the JAX-RS runtime invokes the annotated java method to handle the GET request.
POST: The @POST annotation specifies that the annotated method responds to HTTP POST requests.
Produces: This annotation specifies the MIME media types that the methods in the resource can produce and return to the client.
Consumes: The @Consumes annotation specifies the MIME media types that the methods in the resource can accept from the client. As is the case for the @Produces annotation, if you specify @Consumes on a class, it applies to all the methods in the class. If you specify @Consumes on a method, it overrides the MIME type in any @Consumes annotation that you specify for the class.
JAX-RS also has other convenient features like parameter-based annotations that can be used to extract information from a request. One of these annotations is @QueryParam, which can be used to extract query parameters from the Query component of a request URL. Other parameter-based annotations are @MatrixParam, which extracts information from URL path segments, @HeaderParam, which extracts information from HTTP headers, and @CookieParam which extracts information from the cookies declared in cookie-related HTTP headers.
There are also a number of utility classes and interfaces that further simplify actions related to building and using RESTful web services in Java. Some of these classes include:
- MediaType class can be used for abstracting MIME media types. The instances of this class are immutable.
- UriInfo is an interface for accessing application and request URI information.
- UriBuilder, a URI template aware utility class, is used for building URIs from their components.
- Response is an abstract class that represents an HTTP response. It defines the contract between a returned instance and the runtime when an application needs to provide metadata to the runtime. An application class can extend this class directly or can use one of the static methods to create an instance using a ResponseBuilder.
- Response.ResponseBuilder, a class that builds Response objects, in accordance with the Builder Pattern.
RESTEasy framework from JBoss is another implementation of the JAX-RS specification. Apache's open source services framework CXF will also provide support for JAX-RS 1.1 as part of their version 2.3 release.