think differently big

Measuring REST

Check out (at least) the last 10 slides from Subbu Allamaraju‘s Measuring REST:

You’ll get a different perspective on how to architect applications.

Jersey and Guice Integration

Following my first experiments with Jersey I’ve continue my investigation of Jersey and Guice integration. As mentioned in the previous post my research was mainly centered around Paul Sandoz’s post, the Jersey mailing list (nb. unfortunately I could find much), and as the last resort the source code.

Jersey 1.3 and Guice

For Jersey 1.3 and Guice integration the news are quite good. There is a jersey-guice module that provides pretty much everything that is needed. And there is also a sample project providing the necessary details for setting this integration up, so I’ll not detail it here. Basically all you have to do is:

• download the jersey-guice module from here
• download the sample application from here and use it an example for configuring the integration.

But you will also want to be aware of the following three things:

1. Jersey 1.3 requires Java 6
2. you cannot use Guice constructor @Inject if you also need to pass in any of the JAX-RS @*Param
3. there seems to be some issues using Viewable JSPs

While point 1 above may be a non-issue to most/some, the other two deserve a bit of explanation/details.

When using the Guice integration provided in Jersey 1.3, Guice is responsible to both create and inject components, resources, and providers. Unfortunately due to they way bindings are defined in Guice, there was no easy way to make it aware of all @*Param values and so even if it is recommended to use constructor based injection, you’ll not be able to to both use @Inject and @*Param in a constructor. Most probably the scenarios where you’ll see is issue are those elements that have a per-request lifecycle. The good news is that there are simple workarounds for it:

• define all per-request @*Param as fields and the constructor as @Inject
• define all Guice @Inject dependencies as either fields or methods, and use the constructor parameters to make Jersey pass in *@Params

The last point is covered in more detail and this email thread. According to the conclusions in there, you’ll probably need a Guice trunk build to get around this issue.

Jersey 1.2 and Guice

In case you are stuck with Java 5 for the time being, you’ll have to go back and use Jesey 1.2. Unfortunately this comes with a couple of other bad news:

• the Guice integration in Jersey 1.2 is not as good as the onein 1.3
• if you think of using the integration module provided with Jersey 1.3 in Jersey 1.2, that will not work either. The 1.3 integration relies on new Jersey internal API.

Unfortunately I’m in this second situation. My machines are still running Java 5 and an upgrade is not foreseeable. There might be a good part in this though: if I’ll find the time I’ll probably try to backport Jersey 1.3 Guice support to 1.2. But there are still some problems with this (license, distribution, etc.) and I’ll need to consult myself with Jersey people.

My experience with Jersey (JAX-RS)

A couple of weeks ago I started a small sanbox project using the Jersey JAX-RS implementation. My goal was quite simple: trying a couple of things out and plumbing together Jersey, Sitemesh, and Guice. Below are some notes on what I ended up with.

Sitemesh

Integrating Sitemesh was trivial. I only had to include the default Sitemesh configuration options and everything just worked. With the only caveat that the entity to be represented is not available to the Sitemesh decorators. Anyways I’ve decided to leave it as is, as not having access to the entity may actually be a good thing for making your decorators really generic. Just in case you do not agree and you’d like to get access to the entity into decorators leave a comment and I’ll look into it. Or if you already know how to do that, please share it.

Note: I assume this behavior is triggered by the entity being available in the JSP page context and not on the request.

Guice

Documentation about using Guice with Jersey is extremely rare (kindly said) and extremely old. What I’ve ended up with is more like using Guice as the factory pattern then DI: the resource object gets access to the Guice injector from where it canI fetch the needed dependencies. I’m not completely satisfied with this, but I didn’t have enough time to dig deeper.

Note: Ideally you’ll want the resource to be injected with dependencies automatically by Guice, but I’m not really sure if that is possible or not. I guess both Guice and Spring have to do the same thing, so maybe looking at the Spring integration will give me more ideas (hopefully I’ll be able to find more documentation about Spring integration). Paul Sandoz has written about some improvements for Guice integration in Jersey 1.3

Update: here is the follow up post on Guice integration in Jersey 1.3 and Jersey 1.2

Error codes and exception handling

While playing with my little project, I have noticed that there is no recipe for error handling with Jersey. When I say error handling, I’m actually referring to two scenarios:

• handling server side exceptions
• handling server side error codes

My goal was quite simple: have a way to customize the errors returned to the client for both exceptional cases and standard errors,

The only part related to this covered by the spec is defining exception mappers, but that is pretty far from being able to provide a complete solution.

I’ve also searched extensively the mailing list, but I haven’t been able to find a complete solution. What I did find where a couple of interesting ideas and some suggestions that set me on the right direction.

So I’ve ended up writing a couple of classes that would provide an easy way to deal with errors, allow me to customize the “output”, while also maintaining the complete media type support. Basically, my solution defines:

• 1 exception class ServiceException,
• 1 data class ErrorInfo which can carry details of different server side errors,
• 3 ExceptionMappers: `
• WebApplicationExceptionHandler: deals with WebApplicationException creating an ErrorInfo
• ServiceExceptionHandler: deals with ServiceException creating an ErrorInfo
• ThrowableHandler: deals with all Throwable, creating an ErrorInfo

The last part of the solution is providing custom MessageBodyWriters for the ErrorInfo class supporting the formats you want to provide from your service. Right now, ErrorInfo can be serialized to XML, JSON and HTML using specific templates.

Handling forms

Dealing with forms and validation is a very common task when creating services/web apps, so I was a bit confused not to found a “standard” or at least some well established solutions. This made me write a couple of classes to make things simpler:

• populate a JavaBean from the form parameters (while this is not a complete solution it allows mapping form parameters to JavaBean properties, including and excluding some properties)
• validate forms parameters using either JSR-303 annotations or programmatically defined constraints according to JSR-303

A sample:

        Form.FormBuilder fb = new Form.FormBuilder(ValidatedBean.class)
                .include("creditCard")
                .validate("creditCard", Validations.CreditCard)
                .exclude("param1", "param2");
            Form<ValidatedBean> vform = fb.build(validForm);
    assertTrue(vform.valid());
    ValidatedBean gBean= vform.getObject();

For now that’s all. If there is any interest in these custom pieces I’ve written, please drop me a note and I’ll do my best to share them on GitHub.

Web Frameworks are Passing the REST litmus test

After reading the excellent ☞ REST Litmus Test for Web Frameworks I was wondering what web frameworks are really passing it.

If you know of any please share it with me. Including links to the documentation/code for each of the points in the post will definitely be even more helpful.

I’ve submitted this question also on ☞ Hacker News and ☞ Reddit. Once I’ll get some results I’ll make sure to start updating this post.

REST - Essential Resources

Everyone interested in learning or applying REST should definitely start his journey by reading Roy Fielding’s Architectural Styles and the Design of Network-based Software Architectures ☞ which focuses on the rationale behind the design of the modern Web architecture and how it differs from other architectural styles.

Over time, I’ve put together a list of articles that introduced me to REST and helped me learn the concepts and how to apply them. Anyways, I’m not going to include all my Delicious tagged bookmarks here, but only quote the ones that I think we’ll give a good head start.

A Brief Introduction to REST

This article written by Stefan Tilkov talks about the REST five key principles:

• Give every “thing” an ID
• Link things together
• Use standard methods
• Resources with multiple representations
• Communicate statelessly

↪

Addressing Doubts about REST ☞

Another great article from Stefan Tilkov:

Invariably, learning about REST means that you’ll end up wondering just how applicable the concept really is for your specific scenario. And given that you’re probably used to entirely different architectural approaches, it’s only natural that you start doubting whether REST, or rather RESTful HTTP, really works in practice, or simply breaks down once you go beyond introductory, “Hello, World”-level stuff.

↪

Hypermedia in RESTful applications ☞

Mark Baker’s article is about that “Link things together principle” (formally known as hypermedia):

[…] there’s a sub-constraint that goes by the unwieldly name of “Hypermedia as the engine of application state”, which is arguably the most important constraint of REST in the sense that it alone provides the bulk of the “shape” of RESTful systems as we know them.

↪

RESTful HTTP in practice ☞

Once you got used to the REST concepts, the very next thing that might prove useful is to see real examples. Gregor Roth’s article is a good intro to how to design your RESTful HTTP app:

Applications which implement a dedicated architecture style will use the same patterns and other architectural elements such as caching or distribution strategies in the same way.

↪

REST Anti-Patterns ☞

When people start trying out REST, they usually start looking around for examples – and not only find a lot of examples that claim to be “RESTful”, or are labeled as a “REST API”, but also dig up a lot of discussions about why a specific service that claims to do REST actually fails to do so.

↪

There is also the excellent book written by Leonard Richardson and Sam Ruby: RESTful Web Services: Web Services for the real world ☞:

You’ve built web sites that can be used by humans. But can you also build web sites that are usable by machines? That’s where the future lies, and that’s what this book shows you how to do. Today’s web service technologies have lost sight of the simplicity that made the Web successful. This book explains how to put the “Web” back into web services with REST, the architectural style that drives the Web.