JAX-RS: The Java API for RESTful Web Services

October 14, 2009
By Thribhuvan Thakur

Send Email »
More Articles »

JAX-RS Annotations

JAX-RS annotations are runtime annotations. Let's look at some of the important ones that you implemented in the previous example.

@Path identifies the URI path that a resource class or class method will service. It may be used on classes. The classes that use it are referred to as root resource classes. It may also be used on methods of root resource classes. In the Jersey example, RestByExampleResouce.java was hosted at the URI path '/restbyexample'.
@PathParam extracts URI path parameters from the request URI, where the parameter names correspond to the URI path template variable names specified in the @Path class-level annotation. In the Jersey example, the sub resource method getUserName() has an annotation @GET @Path("users/{name}"). It responds to the URI http://localhost:9998/restbyexample/users/xx by returning the text: You asked for xx
@GET indicates that the annotated method responds to HTTP GET requests. In the jersey example, the sub resource method doGetAsHtml() served to process HTTP GET requests for the media type text/html. It produces "Welcome to JAX-RS tutorial" for the URI http://localhost:9998/restbyexample.
@PRODUCES specifies the MIME media types of representations a resource will produce for a client. In the Jersey example, the sub resource methods doGetAsText() and doGetAsHtml() produce representations identified by the MIME media types text/plain and text/html, respectively.
@CONSUMES specifies the MIME media types of representations that a resource can consume from a client. In the Jersey example, the sub resource method doPostMimeFormEncoded() will consume representations identified by the MIME media type application/x-www-form-urlencoded.
@FormParam extracts information as form parameters POSTed by HTML forms from a request representation of MIME media type application/x-www-form-urlencoded. In the Jersey example, the sub resource method doPostMimeFormEncoded() will retrieve the form parameter 'whoami' when the form is posted with the action "http://localhost:9998/restbyexample/formpost".
@POST Indicates that the annotated method responds to HTTP POST requests. In the Jersey example, doPostMimeFormEncoded() served to process HTTP POST.

For a complete list of annotations defined in JAX-RS, refer to the Java API for JAX-RS documentation.

Apache-CXF

Currently, there are two ways to build RESTful services with CXF:

JAX-RS APIs
JAX-WS Provider and Dispatch APIs

A Simple JAX-RS Web Service with Apache-CXF

Download the source for the latest distribution of Apache CXF, which includes JAX-RS examples in the jax-rs directory under samples and a POM for Maven builds. Please review the README in the samples directory.

Follow the process outlined for Jersey in the previous section to build a Maven template in Eclipse (choose the Group Id and Artifact Id as listed in the POM of the sample distribution). After you have created the project, make sure the package structure reflects the one shown in the sample. Next, copy/extract the files from the distribution into the Eclipse workspace, including the POM (replacing the existing POM in the Eclipse/Maven project).

The sample at C:\apacheSourceREST\apache-cxf-2.2.3-src\distribution\src\main\release\samples\jax_rs\basic shows how to build REST-based web services using JAX-RS. It has two parts: a server and a client.

On the server side:

The root resource class CustomerService.java demonstrates how to build a RESTful web service with the JAX-RS (JSR-311) APIs.
The main URI /customerservice/ is denoted by @Path at the class level. It responds to GET at the sub URI /customers/{id}/), PUT at /customers/, POST at /customers/, and DELETE at /customers/{id}/.
The method getOrder(@PathParam("orderId") String orderId) is an example of a sub-resource locator because it doesn't use a request method designator.
An HTTP GET request to URL http://localhost:9000/customerservice/customers/123 returns an XML document representing the customer 123. The annotation @XmlRootElement defines an XML element name for the XML schema type of the corresponding classes (Customer, Order, Product) using JAXB.

On the client side:

The sample demonstrates how to send HTTP GET/POST/PUT/DELETE requests using the Apache-specific org.apache.commons.httpclient.HttpClient.

Conclusion

REST is an architectural style that provides a simple and uniform way of calling server-side resources using HTTP web services. Developing web services has never been easy, but REST assists the developer with an inherent loose coupling of client and server without the complications of WSDL or XML. In this article, we have covered the basic definition of REST and demonstrated two frameworks that support REST concepts.