JAX-RS: The Java API for RESTful Web Services
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()
anddoGetAsHtml()
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.References
Jersey User Guide
Grizzly
JSR 311 JAX-RS specification
JAX-RS API
Jersey Client API
Apache CXF
Apache CXF API
Source Code
Page 2 of 2
This article was originally published on October 15, 2009