Saturday, February 13, 2010

JAX-RS 1.1: What's New?

Srini Penchikala's InfoQ article Java EE 6 Web Services: JAX-RS 1.1 Provides Annotation Based REST Support provides a concise (fits on one printed page!) high-level overview of JAX-RS 1.1, some of the commonly used JAX-RS annotations, and some common implementations of JAX-RS 1.1. It's definitely worth the short read for anyone just starting to learn about JAX-RS. JAX-RS 1.x has been developed under the Java Community Process via JSR 311 ("JSR 311: JAX-RS: The Java API for RESTful Web Services").

The JAX-RS 1.1 changelog documents changes from JAX-RS 1.0 to 1.1. One of the most significant characteristics of JAX-RS 1.1 is that it is part of Java EE 6 and so multiple items related to inclusion with Java EE 6 are included. Several minor, but appreciated, enhancements surround adding examples to, clarifying, and correcting Javadoc comments related to use of JAX-RS.

One of the interesting JAX-RS 1.1 enhancements is changing the enum Response.Status to implement an interface called Response.StatusType. This is interesting from an intellectual or conceptual perspective that it illustrates the usefulness of having a Java enum implement an interface. In this case, this allows JAX-RS 1.1 to get around limitations associated with not being able to extend an enum. In particular (and this is where this is interesting from a practical perspective), this allows developers to express their own custom response status types by custom enum.

The new @ApplicationPath annotation can be used on a custom extension of Application to specify the base URI for all paths specified with the @Path annotation. This is similar to specifying this in the web.xml file and, in fact, the any setting in the web.xml file still takes precedence over the @ApplicationPath value. I generally prefer this strategy (used also in Java Persistence API) of having external XML/configuration be able to override/supersede in-code annotations.

It is not unusual to have a version 1.1 of a specification focus on improvements to the 1.0 version found during "real life" application of that specification. JAX-RS 1.1 is no exception and has several changes related to improving JAX-RS by making standard supported behavior less ambiguous. For example, JAX-RS 1.1 requires implementations to use application/octet-stream as the default Content-Type. JAX-RS 1.1 also requires compliant implementations to support a static fromString method in a type describing a resource model parameter.

There are several other goodies added to JAX-RS 1.1 and these can be seen in the previously mentioned changelog. Markus Karg's blog post "WebDAV Support for JAX-RS" Release 1.1 discusses how changes in JAX-RS 1.1 enabled him to simplify WebDAV support for JAX-RS.

The article that I referenced at the beginning of this post (Java EE 6 Web Services: JAX-RS 1.1 Provides Annotation Based REST Support) outlines the versions of several JAX-RS implementations that support JAX-RS 1.1. These implementations of JAX-RS 1.1 are Jersey 1.1.5, Apache CXF 2.3, and RESTEasy. Other JAX-RS implementations include Restlet and Apache Wink (incubator).

JAX-RS 1.1 introduces some nice changes to JAX-RS that one normally expects when going from a 1.0 to a 1.1. Not the least of these advantages is its inclusion in Java EE 6.

1 comment:

markus said...

Actually the changes in JAX-RS 1.1 had not only been allowing me to simplify the WebDAV code, but in fact, I developed the proposals of JAX-RS as part of the WebDAV code ontop of JAX-RS 1.0 and then forwarded those to Marc and Paul as a proposal for the planned JAX-RS 1.1 release. So this is a great example how usage of an API leads to improvement of the same API, by developing patches and sending them in as a proposal for future adoption in the standard. BTW, the this also included my idea to migrate the enum to an interface, which was just necessary to simplify WebDAV - it was not actually intended from the start of such a brilliant solution, we just had no other idea how to do it otherwise. ;-)

- Markus Karg, Head Crashing Informatics (http://www.headcrashing.eu)