Jersey – a review

We’ve been getting more interested in using RESTful web services and AJAX based applications recently. One of the tools we’ve been using with that is Jersey – the JAX-RS (JSR-331) reference implementation. I’ve been using it in anger for about a month now, and thought I’d write up some thoughts I had about it.

Jersey 101

Let’s start with what Jersey is. As I said, Jersey is the reference implementation for JAX-RS: the Java API for RESTful Web Services. In other words, it’s a library designed to help with writing web-based services that follow the REST principles. If you don’t know about those, then stop reading now. Or better yet, read about them first, then come back here.

At it’s heart, Jersey is a web-framework. That means you need to start with a WAR application, and a web.xml. In its simplest form, you just need to provide a servlet and servlet-mapping. We’re using it with Spring, so our web.xml looks kind of like this:

  <!-- Configure Spring in this application. -->
  
    contextConfigLocation
    classpath:applicationContext.xml
  
  
    org.springframework.web.context.ContextLoaderListener
   

  <!--  Configure Jersey in this application. -->
  
    jersey
    com.sun.jersey.spi.spring.container.servlet.SpringServlet
  

  
    jersey
    /
  

In the applicationContext.xml file, I enable Spring’s component scanning support so that it will find my Jersey resources automagically and enable them for me. Because I bound the servlet to the root, all web requests will go through it.

So what is a Jersey resource, and what does it look like? A Jersey resource is an endpoint for a web request. In other words, it’s like a JSP page or a Struts Action – it’s the class that’s going to receive the web request.

Let’s go for a simple example:

package net.twasink.jersey.example.resource;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

import org.springframework.stereotype.Service;

import net.twasink.jersey.example.model.HotelModel;

@Service @Path("/hotels/")
public class Simple {

    @GET @Path("{hotelId}/")
    @Produces({ MediaType.TEXT_HTML, MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
    public HotelModel doSomethingSimple(@PathParam("hotelId") String hotelId) {  

        Hotel hotel = ... // look up the hotel.
        
        return new HotelModel(hotel);
    }
}

(I should point out here that after four years working at Wotif.com, most of the examples that come to mind easily these days involve things like Hotels and Rooms and Rates; there is no implication that this in any way resembles real Wotif code, folks)

Anyway, let’s break that down.

• Line 13 – the @Service annotation marks this class as a component to be managed by Spring. The @Path annotation tells Jersey that this covers the “/hotels/” directory.
• Line 16 – the @GET says that this is only for HTTP GETs. The @Path is relative to the earlier path, and means that the first directory down from “/hotels/” will be used as the hotel ID. So a web request like http://mysite.org/hotels/12345/ will try to load hotel 12345. This gets bound to the method parameter in line 18.
• Line 17 – the @Produces lists the media types this method produces. This is handy, because in an AJAX style app, I probably wouldn’t want to load the hotel from the database for a HTML request
• Line 22 – here we return the Model object (in a Model-View-Controller context). This is a JAXB-configured class.

Jersey will map incoming requests to this resource, and to the method, based on what occurs during “conneg” – short for “Content Negotiation”. Out of the box, this will use the Accept header in the HTTP request; we added support for using extensions^[1] as well, as it’s easier to test.

Once it’s got the model, it will pass it to a “>MessageBodyWriter; Jersey comes out-of-the-box with decent support for XML (based on JAXB), some support for JSON (also based on JAXB), and we dropped in support for HTML based off Freemarker templates. Jersey also has support for implicit and explicit views, as well as JSP templating, but I don’t know much about that part yet.

Overall Impressions

First – it’s a terrible name. Whenever I google anything about it, I get back hits for the state of New Jersey, or the Isle of Jersey. Folks – when you start a new framework, please please please pick names that don’t already have massive Google-presence.

Second – the framework itself looks pretty powerful, especially once it’s integrated with Spring to leverage its features (such as security and transaction AOP). It looks like it will be able to do what we want with it pretty well.

Third – I love the cleanliness of using the one model class and transforming it via views into different representation. This means, for example, that providing a CSV extract is as simple as coding (once) the rules for turning a generic Java class into a CSV file. Annotations help a lot here, and the MessageBodyWriters are smart enough to be able to chain up, and only write the body out if they support the model. Personally, I like this clean pattern (of using models that populate themselves from the domain to drive views), and Jersey’s support of it suits me.

Fourth – I don’t like the level of documentation. The actual provided docs are very sketchy; most of the knowledge-base is embedded in the mailing lists and the blogs of the main Jersey developers. This, combined with point one, can make information hard to find. If the Jersey folks really want to push it as a mainstream choice, they’ll need to lift their game here a bit.

Fifth – I think it’s great that they’ve got JSON support. It’s fantastic that it uses the JAXB annotations. I’d be happier if the resulting JSON was friendly to work with on the Javascript side. In many ways, their JSON formats (you have a choice of three) seem to be written with an eye to parsing Java side, and they all have quirks. For example, in the default “mapped” format, a one-element list gets rendered like this:

"foo": "bar"

instead of like this:

"foo": ["bar"]

This means you can’t just loop over it in Javascript properly. D’oh! As I don’t care about Java clients parsing the JSON (they can use the XML format), I’m in the process of writing a JSON writer that still leverages the JAXB annotations but is friendlier to the Javascript clients.

Sixth – integration with other frameworks. Still working on this one. Integration with Spring is fine, and from that we get a lot (such as Hibernate support), but I’m curious to see how well I can get other frameworks (e.g. ehcache for page caching) to work. I also had some neat tricks intended to reduce boilerplate in Spring MVC that I’d like to introduce; for example, in Spring MVC I would be able to replace the hotelId parameter shown in the code snippet above with an actual Hotel object that was magically fetched from the repository – this isn’t a big deal when you have one endpoint, but when you start having a few different end points (say – “update”, or “add room”, or “upload photo”), reducing this boilerplate saves a few lines.

Seventh – performance. No idea on this one yet. OTH, we take performance testing pretty seriously at Wotif (we actually do some!), so this one will get address over time.

Overall, it looks interesting, if somewhat not-quite-ready for prime time (due to the doco flaws, mostly – featurewise it’s pretty complete).

---

[1] the implementation we use is pretty similar to this suggestion on the Jersey forums.