What's New in JAX-RS 2.0

JAX-RS is a framework designed to help you write RESTful applications both on the client and server side. With Java EE 7 is being slated to be released next year, 2013, JAX-RS is one of the specifications getting a deep revision. JAX-RS 2.0 is currently in the Public Draft phase at the JCP, so now is a good time to discuss some of the key new features so that you can start playing with your favorite JAX-RS implementation and give some valuable feedback the expert group needs to finalize the specification.

Key features in 2.0:

• Client API
• Server-side Asynchronous HTTP
• Filters and Interceptors

This article gives a brief overview of each of these features.

Client Framework

One huge thing missing from JAX-RS 1.0 was a client API. While it was easy to write a portable JAX-RS service, each JAX-RS implementation defined their own proprietary API. JAX-RS 2.0 fills in this gap with a fluent, low-level, request building API. Here's a simple example:

Client client = ClientFactory.newClient(); 
WebTarget target = client.target("http://example.com/shop"); 
Form form = new Form().param("customer", "Bill")
                      .param("product", "IPhone 5") 
                      .param("CC", "4444 4444 4444 4444"); 
Response response = target.request().post(Entity.form(form)); 
assert response.getStatus() == 200; 
Order order = response.readEntity(Order.class); 

Let's dissect this example code. The Client interface manages and configures HTTP connections. It is also a factory for WebTargets. WebTargets represent a specific URI. You build and execute requests from a WebTarget instance. Response is the same class defined in JAX-RS 1.0, but it has been expanded to support the client side.

The example client, allocates an instance of a Client, creates a WebTarget, then posts form data to the URI represented by the WebTarget. The Response object is tested to see if the status is 200, then the application class Order is extracted from the response using the readEntity() method.

The MessageBodyReader and MessageBodyWriter content handler interfaces defined in JAX-RS 1.0 are reused on the client side. When the readEntity() method is invoked in the example code, a MessageBodyReader is matched with the response's Content-Type and the Java type (Order) passed in as a parameter to the readEntity() method.

If you are optimistic that your service will return a successful response, there are some nice helper methods that allow you to get the Java object directly without having to interact with and write additional code around a Response object.

Customer cust = client.target("http://example.com/customers")
                      .queryParam("name", "Bill Burke")
                      .request().get(Customer.class); 

In this example we target a URI and specify an additional query parameter we want appended to the request URI. The get() method has an additional parameter of the Java type we want to unmarshal the HTTP response to. If the HTTP response code is something other than 200, OK, JAX-RS picks an exception that maps to the error code from a defined exception hierarchy in the JAX-RS client API.

Asynchronous Client API

The JAX-RS 2.0 client framework also supports an asynchronous API and a callback API. This allows you to execute HTTP requests in the background and either poll for a response or receive a callback when the request finishes.

Future<Customer>
future = client.target("http://e.com/customers")
               .queryParam("name", "Bill Burke")
               .request()
               .async()
               .get(Customer.class);

try {
   Customer cust = future.get(1, TimeUnit.MINUTES);
} catch (TimeoutException ex) {
  System.err.println("timeout");
}

The Future interface is a JDK interface that has been around since JDK 5.0. The above code executes an HTTP request in the background, then blocks for one minute while it waits for a response. You could also use the Future to poll to see if the request is finished or not.

Here's an example of using a callback interface.

InvocationCallback<Response>
callback = new InvocationCallback {

   public void completed(Response res) {
      System.out.println("Request success!");
   }

   public void failed(ClientException e) {
      System.out.println("Request failed!");n
   }
};

client.target("http://example.com/customers")
      .queryParam("name", "Bill Burke")
      .request()
      .async()
      .get(callback);

In this example, we instantiate an implementation of the InvocationCallback interface. We invoke a GET request in the background and register this callback instance with the request. The callback interface will output a message on whether the request executed successfully or not.

Those are the main features of the client API. I suggest browsing the specification and Javadoc to learn more.

Server-Side Asynchronous HTTP

On the server-side, JAX-RS 2.0 provides support for asynchronous HTTP. Asynchronous HTTP is generally used to implement long-polling interfaces or server-side push. JAX-RS 2.0 support for Asynchronous HTTP is annotation driven and is very analogous with how the Servlet 3.0 specification handles asynchronous HTTP support through the AsyncContext interface. Here's an example of writing a crude chat program.

@Path("/listener")
public class ChatListener
{

   List<AsyncResponse> listeners = ...some global list...;


   @GET
   public void listen(@Suspended AsyncResponse res) {
      list.add(res);
   }

}

For those of you who have used the Servlet 3.0 asynchronous interfaces, the above code may look familiar to you. An AsyncResponse is injected into the JAX-RS resource method via the @Suspended annotation. This act disassociates the calling thread to the HTTP socket connection. The example code takes the AsyncResponse instance and adds it to a application-defined global List object. When the JAX-RS method returns, the JAX-RS runtime will do no response processing. A different thread will handle response processing.

@Path("/speaker")
public class ChatSpeaker
{
   List<AsyncResponse> listeners = ...some global list...;
   @POST
   @Consumes("text/plain")
   public void speak(String speech) {
      for (AsyncResponse res : listeners) {
         res.resume(Response.ok(speech, "text/plain").build());n
      }
   }
}

When a client posts text to this ChatSpeaker interface, the speak() method loops through the list of registered AsyncResponses and sends back an 200, OK response with the posted text.

Those are the main features of the asynchronous HTTP interface, check out the Javadocs for a deeper detail.

Filters and Entity Interceptors

JAX-RS 2.0 has an interceptor API that allows framework developers to intercept request and response processing. This powerful API allows framework developers to transparently add orthogonal concerns like authentication, caching, and encoding without polluting application code. Prior to JAX-RS 2.0 many JAX-RS providers like Resteasy, Jersey, and Apache CXF wrote their own proprietary interceptor frameworks to deliver various features in their implementations. So, while JAX-RS 2.0 filters and interceptors can be a bit complex to understand please note that it is very use-case driven based on real-world examples. I wrote a blog on JAX-RS interceptor requirements awhile back to help guide the JAX-RS 2.0 JSR Expert Group on defining such an API. The blog is a bit dated, but hopefully you can get the gist of why we did what we did.

JAX-RS 2.0 has two different concepts for interceptions: Filters and Entity Interceptors. Filters are mainly used to modify or process incoming and outgoing request headers or response headers. They execute before and after request and response processing. Entity Interceptors are concerned with marshaling and unmarshalling of HTTP message bodies. They wrap around the execution of MessageBodyReader and MessageBodyWriter instances.

Server Side Filters

On the server-side you have two different types of filters. ContainerRequestFilters run before your JAX-RS resource method is invoked. ContainerResponseFilters run after your JAX-RS resource method is invoked. As an added caveat, ContainerRequestFilters come in two flavors: pre-match and post-matching. Pre-matching ContainerRequestFilters are designated with the @PreMatching annotation and will execute before the JAX-RS resource method is matched with the incoming HTTP request. Pre-matching filters often are used to modify request attributes to change how it matches to a specific resource. For example, some firewalls do not allow PUT and/or DELETE invocations. To circumvent this limitation many applications tunnel the HTTP method through the HTTP header X-Http-Method-Override. A pre-matching ContainerRequestFilter could implement this behavior.

@Provider
public class HttpOverride implements ContainerRequestFilter {

   public void filter(ContainerRequestContext ctx) {
      String method = ctx.getHeaderString("X-Http-Method-Override");
      if (method != null) ctx.setMethod(method);
   }
}

Post matching ContainerRequestFilters execute after the Java resource method has been matched. These filters can implement a range of features for example, annotation driven security protocols.

After the resource class method is executed, JAX-RS will run all ContainerResponseFilters. These filters allow you to modify the outgoing response before it is marshalled and sent to the client. One example here is a filter that automatically sets a Cache-Control header.

@Provider
public class CacheControlFilter implements ContainerResponseFilter {
   public void filter(ContainerRequestContext req, ContainerResponseContext res) {
      if (req.getMethod().equals("GET")) {
         req.getHeaders().add("Cache-Control", cacheControl);
      }
   }
}

Client Side Filters

On the client side you also have two types of filters: ClientRequestFilter and ClientResponseFilter. ClientRequestFilters run before your HTTP request is sent over the wire to the server. ClientResponseFilters run after a response is received from the server, but before the response body is unmarshalled.

A good example of client request and response filters working together is a client-side cache that supports conditional GETs. The ClientRequestFilter would be responsible for setting the If-None-Match or If-Modified-Since headers if the requested URI is already cached. Here's what that code might look like.

@Provider
public class ConditionalGetFilter implements ClientRequestFilter {

   public void filter(ClientRequestContext req) {
      if (req.getMethod().equals("GET")) {
         CacheEntry entry = cache.getEntry(req.getURI());
         if (entry != null) {
            req.getHeaders().putSngle("If-Modified-Since", entry.getLastModified());
         }
      }
   }
}

The ClientResponseFilter would be responsible for either buffering and caching the response, or, if a 302, Not Modified response was sent back, to edit the Response object to change its status to 200, set the appropriate headers and buffer to the currently cached entry. This code would be a bit more complicated, so for brevity, we're not going to illustrate it within this article.

Reader and Writer Interceptors

While filters modify request or response headers, interceptors deal with message bodies. Interceptors are executed in the same call stack as their corresponding reader or writer. ReaderInterceptors wrap around the execution of MessageBodyReaders. WriterInterceptors wrap around the execution of MessageBodyWriters. They can be used to implement a specific content-encoding. They can be used to generate digital signatures or to post or pre-process a Java object model before or after it is marshalled. Here's an example of a GZIP encoding WriterInterceptor.

@Provider
public class
GZIPEndoer implements WriterInterceptor {

   public void aroundWriteTo(WriterInterceptorContext ctx) throws IOException, WebApplicationException {
      GZIPOutputStream os = new GZIPOutputStream(ctx.getOutputStream());
      try {
         ctx.setOutputStream(os);
         return ctx.proceed();
      } finally {
         os.finish();
      }
   }
}

Resource Method Filters and Interceptors

Sometimes you want a filter or interceptor to only run for a specific resource method. You can do this in two different ways: register an implementation of DynamicFeature or use the @NameBinding annotation. The DynamicFeature interface is executed at deployment time for each resource method. You just use the Configurable interface to register the filters and interceptors you want for the specific resource method.

@Provider
public class ServerCachingFeature implements DynamicFeature {

   public void configure(ResourceInfo resourceInfo, Configurable configurable) {
      if (resourceInfo.getMethod().isAnnotationPresent(GET.class)) {
         configurable.register(ServerCacheFilter.class);
      }
   }
}

On the other hande, @NameBinding works a lot like CDI interceptors. You annotate a custom annotation with @NameBinding and then apply that custom annotation to your filter and resource method

@NameBinding
public @interface DoIt {}


@DoIt
public class MyFilter implements ContainerRequestFilter {...}


@Path
public class MyResource {
   @GET
   @DoIt
   public String get() {...}

Wrapping Up

Well, those are the main features of JAX-RS 2.0. There's also a bunch of minor features here and there, but youll have to explore them yourselves. If you want to testdrive JAX-RS 2.0 (and hopefully also give feedback to the expert group), Red Hat's Resteasy 3.0 and Oracle's Jersey project have implementations you can download and use.

Useful Links

Below are some useful links. I've also included links to some features in Resteasy that make use of filters and interceptors. This code might give you a more in-depth look into what you can do with this new JAX-RS 2.0 feature.

• JAX-RS 2.0 Public Draft Specification
• Resteasy 3.0 Download
• Jersey
• Resteasy 3.0 client cache implementation code (to see how filters interceptors work on client side)
• Doseta digital signature headers (good use case or interceptors)
• File suffix content negotiation implementation (server-side filter example)
• Other server-side examples (cache-control annotations, gzip encoding, role-based security)