REST made easy with Java EE 6 and JAX-RS 1.1
By: Stephan Oudmaijer, 19 February 2010
In my previous post I wrote about Spring 3.0 and how Spring MVC enables REST services in Spring 3.0. Java EE 6 adds support for RESTfull services by adding JAX-RS to the specification. In this post I will show how JAX-RS 1.1 will make your life easy when writing RESTfull services for JEE 6.
GlassFish v3 is an open source application server and is the first compatible implementation of the Java EE 6 platform specification. To test the examples in this article I will assume that you use GlassFish (or any other JEE6 enabled application server) to run the examples.
Maven2 dependencies
Lets start with the Maven dependencies, you can add them all to the pom.xml of your war. I have also included Sun’s Maven2 repository for downloading the JEE6 dependencies like the javaee-api and Sun’s JAX-RS 1.1 implementation called Jersey.
Both dependencies are scoped as provided because GlassFish already ships with these libraries. In fact, my war file is not bigger than 22kb. JEE6 allowes developers to package full blown JEE application as a web archive file, there is no need for an enterprise archive anymore. This makes JEE6 applications really light weight.
JAX-RS RESTfull services in JEE6
JAX-RS supports configuration through annotations, just like the Spring 3.0 REST annotations. Annotations can be added to both classes and methods. Classes in JAX-RS can be POJO`s. One thing about JAX-RS is that it does not integrate well with other JEE specification, for example the JSR-330 annotations for dependency injection are not supported by JAX-RS (yet), but there is a workaround 
Because of the flexibility of JAX-RS it is possible to annotate EJB SessionBean or CDI components with JAX-RS annotations. So when a bean with JAX-RS annotation is packaged in a war file, the annotations are automatically picked up by the JAX-RS implementation (Jersey in this case). Since EJB3.1 SessionBeans and CDI components support all of the dependency injection features offered by JEE6, JAX-RS now does too!
Below is an example JAX-RS annotated class. The goal of this RESTfull service is to expose two methods of the ProductService through a RESTfull interface. The ProductService is injected using the @Inject annotation.
In JAX-RS the @Path annotation is used to map an URI to a REST service. In the example below I’ve defined the @Path annotation on the class, this will map all the URIs starting with /product to this class. I also defined the @ManagedBean (CDI) annotation on the class for the @Inject to work properly.
There are two methods within the service which are annotated with @Path, @GET and @Produces. The @Path is the same as with the class, but in this case it maps URI’s to a method. The URI of a method is relative to URI specified in the @Path annotation
on the class. So the following URLs are mapped in this example:
JAX-WS allowes for mapping HTTP methods like GET, PUT, POST and DELETE to Java methods with the @GET, @PUT, @POST and @DELETE annotations. In this example only the GET method is used. In RESTfull service the HTTP GET is used to retrieve data. To map a GET request to a method you can simply annotate a method with @GET.
The @Produces annotation specifies the Mime-Type of the response data the methods produces. In this example the methods both produce XML data, therefore we need to set the Mime-Type to application/xml. When returning an Object from a method annotated with @Produces, JAX-RS trieds to find an appropriate converter to produces the output. In this case I will use JAXB will to marshall the Objects to XML (see below).
JAXB marshalling
In order for JAXB to marshall the Objects returned, we need to specify JAXB annotations on the Objects returned from the methods.
In this example I’ve added @XmlRootElement to the returned Objects to simply marshall the entire Object to XML.
Adding Jersey to the web deployment descriptor: web.xml
For JAX-RS to work we still need to add a Servlet to the web.xml which maps URL’s to the services. In this case we need to add the JerseyServlet to the web.xml. In the servlet-mapping all /rest/ URL patterns are mapped to Jersey. We can access the REST services using the following URIs: /rest/product/etc.
Conclusion
When building RESTfull services on an JEE6 enabled application server, JAX-RS really makes things easy. You will have to decide for your specific case if you want to use Spring or JAX-RS.
19 February 2010 om 10:14 am
Quick question: Is the @Path annotation mandatory? What happens if you omit it?
I’m asking this because in the case of getCategories the convention could be to just use “/categories”..? This also holds for getProducts, even with the parameter, a convention would yield a similair path.
If it is mandatory I don’t understand why they have two seperate annotations, wouldn’t it be easier to have @GET(“/categories”)?
Also, why are @GET, @PUT and @DELETE in uppercase?? Are they abbreviations that I’m not aware of?
19 February 2010 om 3:41 pm
Hi Stephen,
a good introduction to REST in two consecutive posts – your previous post helped me get started quickly with a spring MVC implementation. Check out another good article where both technologies are compared side by side: http://www.infoq.com/articles/springmvc_jsx-rs, comparison made by a Spring Source member.
Another thing I noticed after implementing a REST service and firing a request manually with the browser was that it would be nice to have a Java client to consume this service. Again, both Jersey and Spring offer easy to use clients. I’ll show my spring implementation below, might be useful to get started quickly:
The container:
The client code:
This is the most basic client. To get more control on the request (e.g. authenticate) you need to supply your own HTTPRequestFactory to the RestTemplate constructor and manipulate the header there. Like with the server side, Jersey seems more expressive than Spring when it comes to REST.
19 February 2010 om 7:33 pm
@roy
The @Path annotation on methods are not required! You can specify the @Path on a class level and add @GET on the method within the class that handles the HTTP GET. When you try to specify two @GET annotations on different methods, the service simply wont work
The @Path on a class level can be seen as a URI prefix for @Path on methods.
Regarding the uppercased annotations, the only thing I can imagine why the annotations are uppercased is that the HTTP Methods are also uppercased in the HTTP protocol specification (http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html).
@kolov
Thanks for the addition. It is worth another blog post