Friday, April 10, 2009

Soap Shakes, Jersey Rocks

I have grown to be a big fan of JAX-RS ("Java API for RESTful Web Services" -- but where did "X" come from?), and especially the flagship JAX-RS implementation, Jersey. Although I have only been actual user for past couple of months (and lurker on the mailing lists for less than a year), I am fully sold on it by now. In many ways, it might be the only web services framework you need to known, on J2EE platform.

I think of it as moving from manual to automatic shifting. Very convenient, lettig me forget about clutch and gears, and just focus on the road and traffic ahead. Or perhaps Hanoi Rocks playing on CD.

But what exactly is it that JAX-RS and Jersey provide? Here is small sampling of what I like.

1. Jersey the Plumber

You know the gunk between the server receiving a request, and that request reaching actual business logic layer? With Jersey, you only need to be vaguely aware that it exists, give it a hint as to how you want the endpoints to match, and it Does The Plumbing.

You create end points by annotating your method to take in @GET or @POST (etc) requests. And kindly request that things like

  • URL path components (@PathParam
  • Query (@QueryParam) and Form (@FormParam) parameters
  • HTTP headers (@HeaderParam
  • Cookie values (@CookieParam
  • POST payload (any parameter without other annotations
are brought to your method as parameters so annotated. And that's what they will be when method gets called, when request matches the path definition. Pretty nifty. And similarly response is converted back to actual serialized response message, along with headers (for content type) and status code. This means that dealing with the interface (GIGO) takes one method with perhaps 6 lines of code; or maybe 10 if you do proper exception handling to deal with breakage of your business logic.

So long for having to know what kind of stinky stuff clogs the drains: feel free to focus on the actual business logic within service.

In fact, this convenience alone is worth the framework. Seriously. It makes writing services almost fun.

2. Needles and Pins

Almost as important as getting the input parameters in (and reponse out) is to get hold of context objects, to access configuration and shared contextual facilities like connection pools and caches . And this too is provided to you by simple act of annotation: in this case by annotating members of your resource classes (any class with JAX-RS annotations to the class or at least one of its methods is a resource).

Need some Servlet Context with your service? Just declare a member variable is desired type, add @Context annotation, and it'll be there when you need it.

3. Any Way You Want It -- Single Format is SO passe...

Remember that Last Fashionable web service framework? What was it.... something named by a commone household detergent? The one that allowed you to use any data format, as long as it was based on pointy brackets? (if not, good for you).

Well: nowadays SoapSponge Squarepants may act like it was hip Json the Menace: but the only way to do this is to fake Json (aka FrankenJSON). And usually that's as far as "cross-format" tolerance goes. And this despite not having "xml" anywhere within acronym itself.

Not so with JAX-RS: any format can be used. And while XML still is sort of "First among equals" (due to bit of preferential treatment that implementations like Jersey give to JAXB), it is barely noticeable and does not get in the way. In fact my simple built-in-a-day-or-two SQL report service can provide results as XML, JSON, HTML or CSV; and if I need to, in PDF and some more of alphabet soup too.

Addendum: Word of Warning

Is there anything I don't like with JAX-RS or Jersey?

No big regrets yet: but there is one thing I have noticed that can get you to a rat hole: excessive abstraction and indirection. There are many hooks to further create factories, providers and injectors that sometimes application developers are turned into framework developers. It is good to keep simple things simple, and only add indirection when it actually makes sense. There is always time to create frameworks later on, once you learn good ways to build clean and working code.

But having ways to build abstract extensions is not really fault of the framework I guess: and most of the things exposed are made good use of itself.

blog comments powered by Disqus

Sponsored By

Related Blogs

(by Author (topics))

Powered By

About me

  • I am known as Cowtowncoder
  • Contact me
Check my profile to learn more.