dev@jsr311.java.net

Precondition support

From: Marc Hadley <Marc.Hadley_at_Sun.COM>
Date: Fri, 06 Apr 2007 12:01:22 -0400

Starting a new thread to discuss precondition support.

We think that support for preconditions is important and the
HttpRequestContext contains a few evaluatePreconditions methods that
offer such support. Jerome raised the question of whether we could
use annotations instead of these methods using something like the
following:

@UriTemplate("someuri")
public class SomeResource {

  ...

  @LastModified
  Date getLastModified() {
    ...
  }

  @Tag
  EntityTag getEntityTag() {
    ...
  }
}

We did consider this approach for while but decided against it for
the following reasons:

- A strong entity tag can depend on the media type of the returned
representation (a brute force approach is to hash the bytes of the
returned representation). If a class has two methods that return
different media types then you either need multiple variants of the
above @Tag method or some way of indicating which method is going to
be called and what the returned mediaType will be.

- Often you'll need to obtain the same data to compute an entity tag
and last modified value as you'll need to service the request (should
the preconditions be met). You don't want to have to fetch the same
data multiple times so you'd want some way to cache it between the
getEntityTag/getLastModified/http method. However its not clear which
of the methods will actually be called since the preconditions might
not be met so then you end up with data lifecycle issues. We
considered thread-local approaches to caching data but that has
implications on the container for thread management.

The current design avoids these issues. The developer writes their
http methods as normal and just has to add a call to one of the
evaluatePreconditions methods where its appropriate. If
evaluatePreconditions returns null then the preconditions were met
and the method continues as normal. A non-null return value indicates
that the preconditions weren't met and supplies an appropriate
Response that the method can use.

On the downside this approach does dictate that the method have a
Response return type which is unfortunate. We considered use of an
exception but rejected it since this isn't really an exceptional
circumstance.

Marc.

---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.