Work begins on JAX-RS 2.0

by Mark Little on Nov 14, 2010 |

Over the years the adoption of REST as an integration architecture outside of the Web has grown, so it was inevitable that Java and Java EE would be graced with a suitable standard, which was JSR 311, or more often called JAX-RS. This was finalised in 2008 and became part of EE6. Now over that time there have been several implementations, including the mandatory reference implementation. Many Java developers have found JAX-RS a benefit, though of course there have been the inevitable discussions about whether or not JAX-RS is RESTful.

However, as with most good standards, implementation experience is now being fed back into JAX-RS, with Roberto Chinnici of Oracle (ex Sun), recently announcing ...

Below you'll find a draft of the JAX-RS 2.0 JSR. Since JAX-RS 1.1 closed, we've been interacting with many of you in the community, at conferences and across various forums, so hopefully you won't find any surprising items in this draft. Please send us your comments/suggestions in the next couple of weeks. In parallel, we'll be working on filling in the remaining sections marked as TBD, including the schedule and business terms. We'd like to submit the JSR in early December, so as to get it approved by the JCP Executive Committee ahead of the year-end holidays.

Some highlights from the proposals include:

  • The most commonly requested feature for JAX-RS 2.0 is a client API: many if not all JAX-RS implementations provide some degree of client API support. This JSR will define two client APIs, both compatible with the REST style: a low level API using a builder pattern and a higher level one leveraging the former.
  • Model-View-Controller (MVC) is a common pattern in Web frameworks, where it is used predominantly by HTML-based applications. Adopting the MVC terminology, JAX-RS resource classes are comparable to controllers. This JSR will specify an MVC architecture compatible with the JAX-RS programing model. Java Server Pages will be specified as one type of view. It will be possible to plug in other view technologies, for example FreeMarker or StringTemplate.
  • JAX-RS 1.1 was defined before JSR-330 was specified and as a result does not utilize 330 annotations, such as @Inject, as effectively as it could. This JSR will specify closer integration with 330 annotations that may potentially render some existing annotations in JAX-RS, such as @Context, deprecated or redundant.
  • JAX-RS 1.1 defines a synchronous request response model on the server side. This JSR will specify a simple asynchronous request processing model such that a response can be returned asynchronous to the request. Servlet 3.0 can be leveraged to enable such support but implementations may choose to use other container-specific APIs instead.

Stefan Tilkov, has announced support of the new proposal, and Jerome Louvel, lead developer of the Restlet framework, is also supportive, but raises concerns about the TCK:

My main concern is about TCK access for open source projects such as the Restlet Framework (http://www.restlet.org). Despite several requests (including via the JCP scholarship program), we never got access to the TCK. Could you make clear upfront what will be the business/license terms for implementations of JAX-RS 2.0 distributed under open source licenses?

Bill de hÓra, one of the members of the original expert group, is also in agreement and provides the most feedback so far, including:

One practical problem I've seen is that real world systems don't always return errors in the same format as requested by the client (assuming the app developer requested anything at all, again common). Simple example - tomcat/jetty throwing up html error pages. We can argue this is quality problem with the server but it's ugly on clients when it happens and the entity binding blows up. I'd like to see something that echoes the exception mapper on the server side of JAX-RS. Another possibility is allocating handlers onto response codes.

Roberto asks for comments and suggestions relatively soon because, as he says "We'd like to submit the JSR in early December, so as to get it approved by the JCP Executive Committee ahead of the year-end holidays." So are there other things that need considering in JAX-RS 2.0?

Related Editorial

Hello stranger!

You need to Register an InfoQ account or to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread
Community comments

MVC by serge boulay

1.) Model-View-Controller (MVC)

This actually makes a lot of sense IMO. I think JSF 2.0 has made many fine improvements but I still think that there will be many people that will never identify with it. In part, because of their past experience with it and in part because they would rather use an "action" based framework (with the JavaScript framework of the day) over a "component" based framework. I'm sure there are many other reasons for not choosing JSF as a web framework; all this to say that there needs to be some standard MVC type framework (controller mainly) that is an alternative to JSF on the EE platform. In a similar vein, Microsoft has created asp.net MVC as an alternative web framework to asp.net. I think making JAX-RS easier to use as an MVC type framework will be a great alternative for those who don't want to use JSF.

oData is a sensible client API by Faisal Waris

•The most commonly requested feature for JAX-RS 2.0 is a client API: many if not all JAX-RS implementations provide some degree of client API support.

My suggestion would be to adopt Open Data Protocol (www.odata.org/). Lets not reinvent if we don't have to.

Re: oData is a sensible client API by Stefan Tilkov

While oData is useful, this is not what I believe is meant by the term "client API": At the moment, JAX-RS supports the development of server-side code only––there is no standardized Java API to interact with a RESTful HTTP application.

Re: oData is a sensible client API by Jean-Jacques Dubray

Stefan:

a client API? MVC? I must be dreaming?

Re: oData is a sensible client API by Stefan Tilkov

I'm not used to getting your point, JJ, and this time is no exception.

Re: oData is a sensible client API by Jean-Jacques Dubray

I am disappointed Stefan, I thought you would answer that I still "don't understand". A client API and MVC controllers are so uniform... that indeed you wonder why with such a uniform API you need a "client" API and controllers. I must be missing something.

Re: oData is a sensible client API by Stefan Tilkov

Yes, I believe you are missing that the client API would work with any RESTful service.

Re: oData is a sensible client API by Jean-Jacques Dubray

Well I have been working with "RESTful" services for about a year now, and the experience has been transformational. I had to constantly decipher obscure, poorly maintained "HTML" documentations, I had to write a lot of code to deal with JSON and validate that I was getting the right kind of data, not to mention that it was hard to keep up our HTML doc in synch with our own "RESTful" services. As you can see, we didn't REST very much. Things that would take me 2 minutes in the old days take me now anywhere between 2 hours and 2 days. I must admit this is so much better now, we need a team of 20 to do the job of two people. The industry should thank you for all your hard work in showing us the way, ... back to client code, and controllers. I keep the details about versioning for later.

Re: oData is a sensible client API by Stefan Tilkov

Sad to hear that, JJ; I am sure many people have the same experience and miss all those nice and easy WS-* specs, their interoperable implementations. the ease of use, and the fine architectural guidance. But it's great to hear my evil plan has succeeded.

Re: oData is a sensible client API by Jean-Jacques Dubray

I don't even have time to argue sorry, I have to fix some pesky HTTP headers before the end of the day.

Far more that those 4 points by William Martinez

I fell 2.0 should go beyond those 4 points in the highlite.
Client API is a must, but still the server side feels like a set of marshalling/serializing, URL to method mapping, servlet spec in annotations thing.

A couple of weeks ago I read a comment where some guy confused a RESTFull service with a method in Java that I call encoding in the URL the method specs. If JAX-RS gives that impression, should be improved to semantically avoid those interpretations.

The goal is an spec about a framework for building RESTFul services in Java, but I feel it still needs more work to achieve that, like defining a service in the first place.

Cheers.

Re: oData is a sensible client API by William Martinez

Jean-Jacques, Stefan.
Funny to read you both. Reminds me of two brothers that love discussing and usually disagree, but actually like each other.
Client API (or should I say Client side framework), would be very difficult. Nothing related to uniform interface, as it is not about a client that offers connectivity at that level. It may be more related to HATEOAS and App semantics.
Still, yes, the client may be just an HTTP hiding wrapper for the JAVA language, that based on other APIs, will create a Stub and perform method invocation (RPC mapping again). Let's hope it is not that.

Cheers

Client API plus by Cristian Ebbens

It would be great if the Cliente API allow EASY and PRACTICAL ways for setting custom headers params (and any common/trivial setting of a HTTP request). I had "fun" during 2 days with the Resteasy way of doing it :(, and I must say the code was a lot more verbose that the one-liner it should! Thanks

Re: Client API plus by Raymond Feng

In Apache Tuscany (tusany.apache.org) project, we used a JAX-RS annotated interface to denote which parameters are mapped to query parameters, paths and headers in the same way as the server side. The runtime then provides a proxy of the client interface to dispatch the client calls to the HTTP layer.

For example, calling the following method will generate a HTTP request to invoke the REST service:

@Produces("application/xml")
Customer getCustomer(@QueryParam("id") String id);

Tuscany SCA can inject the proxy to the client component. People may take this a "RPC" style, but it really simplifies the client code, IMO.

Thanks,
Raymond

Re: Client API plus by Jean-Jacques Dubray

sorry, but I have to smile quite a bit, not because of what you said Raymond, but about what people like Stefan, Tim, Steve, Bill and a few others claimed back in 2007.

I have made a proposal a while back for a RESTful client programming model here using an Xtext based DSL in response to Stefan finally admitting that "OO is pretty much a barrier to RESTfulness":

www.ebpml.org/blog2/index.php/2010/07/08/mde-be...

but what do I know?

I think I am missing something by Boris Lublinsky

Building Client APIs support seems like a good idea (although this contradict to initial REST claims, that REST is better than WS, because it does not require heavy frameworks), but this is what bothers me:
As a foundation for client APIs you are proposing not a language independent interface definition (Yes, I am stopping short of using the W word), but rather Java interface. This will effectively leads to morphing REST into RMI with expensive protocol and marshaling. I understand that this is JAX-RS, but what about poor bastards that are using other languages, like C#, JavaScript, etc.
It also means throwing away many good things, for example loose coupling. In this approach it is slightly less coupled then RMI, but coupled enough.
Another topic is adding MVC to JAX-RS. I doubt it really makes a lot of sense. I was always fighting developers that where trying to merge business logic implementation with protocol implementation. The rational was always that interfaces come and go, while business implementation stays. Merging JAX-RS with MVC will inevitably lead to bleeding of some business logic into interface implementation

Re: oData is a sensible client API by Juergen Brendel

@JJD: Sorry to hear about your bad experiences with REST. Badly maintained and out of date documentation is certainly a problem. With our RESTx project, we tried to avoid this by having the documentation generated automatically by the server. So, any new resources or components, etc. were automatically discoverable (by following links). Meta data (about parameters and types, for example) was also automatically generated by the server. Those things therefore were never out of date.

I think this sort of built-in, automatic generation of meta data / documentation about a resource is very helpful, especially once you have APIs where even users can create new resources. In that case, it's actually pretty much mandatory that the system documents itself and stays up to date.

Currently, we are working on moving some of the RESTful concepts we explored with RESTx into the Mule ESB.

Re: oData is a sensible client API by Jean-Jacques Dubray

@Juergen

>> by having the documentation generated automatically by the server. ...
>> Metadata ... this sort of built-in, automatic generation of meta data /
>> documentation about a resource is very helpful

you must be kidding me, a small group of people sold us REST in 2007 as being the technology that didn't need any kind of code / documentation generation because this was brittle. What's next? are you also going to generate code?

@Boris, I guess some of the RESTafarians have no (Java Server) face.

Re: I think I am missing something by William Martinez

Hi!.

Building Client APIs support seems like a good idea (although this contradict to initial REST claims, that REST is better than WS, because it does not require heavy frameworks)

Actually, wrong claim. First because WS and REST has almost nothing in common. REST is not for services (originally, let's say) and now that is used to construct services in web, of course it will need a little help.

As a foundation for client APIs you are proposing not a language independent interface definition (Yes, I am stopping short of using the W word), but rather Java interface.

That makes sense since this is a Java helper. Now, you can use the server side and use any language for the client. A Java framework for the client side will simplify the use of the REST interface, but should not be coupled. That is, I cannot, in any way, make that java client the only one able to use the Jax-RS server api.


This will effectively leads to morphing REST into RMI with expensive protocol and marshaling. I understand that this is JAX-RS, but what about poor bastards that are using other languages, like C#, JavaScript, etc.

Totally agree. As JAX-RS tries to leverage Java language, particularly objects, into REST, the final result is a Forced Paradigm Antipattern instance (blogginh about it, not time to post now), where you end up with RMI if no care is taken.


Another topic is adding MVC to JAX-RS. I doubt it really makes a lot of sense. I was always fighting developers that where trying to merge business logic implementation with protocol implementation. The rational was always that interfaces come and go, while business implementation stays. Merging JAX-RS with MVC will inevitably lead to bleeding of some business logic into interface implementation

This sounds very logical to me. Agree it should be discussed further.

William Martinez Pomares.

Re: oData is a sensible client API by Juergen Brendel

@JJD: No, I wasn't kidding, actually. We are still experimenting with the ideas, but if you are inclined to do so, have a look at RESTx and the online demo. That should at least give you an idea of what we are talking about.

Specifically, the 'generated documentation' is merely a different representation of the resource: A real-time view of the resource's meta data. It's not generated documentation in the conventional sense. The meta data contains enough information to be suitable as documentation and which is also machine readable, contains links to follow, etc.

We need to simplify by Simon S.

As Dan says here on the right (btw, great talk, I will attend QCon London 2011 as well) we need to simplify. REST is nice because all you need to be a service provider is a servlet, and all you need to be a service consumer is an http client. With MVC and client generation it looks like we are going to reinvent SOAP, but we already have SOAP.
Let's keep the latter for the guys that like
- binding contracts
- client/server code generation
- concurrent client/server development
- protocol abstraction
and the former for the ones who can do without the above and want to have it the easy way.
REST is so beautiful, it would be bad have a complicated api to implement it in java.

Re: MVC by Cat Weazle

Here at Devoxx Marek Potociar of the expert group said it is unlikely the will do MVC related work in JAX-RS 2.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

22 comments

Educational Content

General Feedback
Bugs
Advertising
Editorial
 InfoQ.com and all content copyright © 2006-2013 C4Media Inc. InfoQ.com hosted at Contegix, the best ISP we've ever worked with.
Privacy policy