Re: Welcome to JSR 311

From: Marc Hadley <Marc.Hadley_at_Sun.COM>
Date: Wed, 04 Apr 2007 13:45:10 -0400

Hi Jerome,

Some comments/responses inline below.

On Apr 4, 2007, at 9:57 AM, Jerome Louvel wrote:
> 1) Number of packages
> 11 packages seems way too much for a high-level API that wants to
> simplify
> the life of developers. I was expecting one or two compact packages
> with the
> list of Annotation types and a couple of helper classes/interfaces
> at most.
Yes, I understand that it does look a little daunting at first but
note that 5 of the 11 are SPIs which I wouldn't expect most users to
need. Of the remaining 6 the messages and container packages are very
small and the majority of the API is contained in the remaining four
packages: - mainly annotations - lower level APIs (more on these below) - base class and helper subclasses for
dealing with common representation formats - base class and helper subclasses for dealing
with common response types

> IMO, we should start fresh, with the minimum number of artifacts (a
> set of
> annotations basically) and only add support artifacts (classes/
> interfaces)
> when absolutely necessary.
That is how Paul and I got to this starting point, perhaps it would
help to list the use cases we had in mind for each of the non-
annotation classes/interfaces: - generic abstraction for a HTTP request entity,
provides additional metadata for a request entity. - standard exception that an
application can throw when something goes wrong. allows setting of
the response status code and entity body - abstraction for a response cache
control header, saves developers from having to manually build a
cache control header string value - abstraction for a cookie supplied in
request, frees developers from having to parse cookies - abstraction for a cookie that an
application wishes to set in a response, frees developers from having
to manually build a set cookie header - abstraction for a media type, frees
developers from having to parse and build headers that include media
types (Content-Type, Accept, etc) - a generic map that allows multiple
values for a single key - useful for HTTP headers, query parameters,
matrix parameters. - represents a single path segment of a
URI along with any matrix parameters - saves the developer from
having to parse URI paths manually, depends on MultivaluedMap for
Matrix parameters - an interface implemented by an
application class that an implementation of the API uses to obtain
the list of resource classes and additional global seetings. Our impl
generates a ResourceConfig implementing class by scanning the source
code for annotations in a pre-compile build step. It would also be
possible to supply the same information via a deployment descriptor
(in environments that support that kind of thing) or via some other
standard mechanism like a static file of a standard format. - injectable interface that provides
access to the request and response contexts and can create a response
that will forward a request within the same container, e.g. to a JSP
page. - provides access to request
information and supports pre-condition evaluation. we imagine that
there will be cases where an application needs to get access to lots
of headers or a large set of query parameters where it would be
onerous to have to itemize each one as a method parameter. this
interface provides a pull capability for such information depends on
Cookie, MultivaluedMap, PathSegment - provides access to response
information, makes it easy to set additional headers not supported in
one of the pre-packaged subclasses,
e.g. cookies and provides a way for an application to get an output
stream to write an entity body to. Depends on NewCookie, MultivaluedMap. - an interface that a JVM-based
scripting language could implement to be exposed as a resource. and are described
above, we think its useful to have a way for applications to return
common types of responses in a simple way.

> 2) The package
> This package redefines a low-level HTTP API which seems
> contradictory with
> the goal of the JSR. I hope that we won't need this package at all.
As outlined above, each of the classes/interfaces has a distinct
purpose and all are intended to simplify the development experience.
Its a tricky balance between functionality and complexity, we only
included things we thought necessary but we're open to adding/
removing features as necessary. The other balancing point is between
container-specific and container-independent functionality. E.g. one
could remove the cookie-related APIs from the above list and defer to
container-specific APIs but then applications built using JSR 311
that want to work with cookies will either be tied to a specific
container or have to invent their own abstraction over the raw header

> If I had to support all this interfaces in a container based on the
> Restlet
> API or on the Servlet API, I would have to provide too many wrapper/
> adapter
> objects in order to support JSR311 request/response lifecycle.

FWIW, our Servlet-specific implementation code is less that 400 lines
including comments and whitespace. I imagine a Restlet-based adaptor
would require even less code.

> I think that
> we should leave the maximum flexibility to the implementers of the
> annotations and not guide them to a particular design.

> 3) HTTP dependent
> Even if HTTP is obviously the core protocol that we want to support
> (the
> HTTP centric goal), REST doesn't tie itself to HTTP and I don't
> think that
> we should either. We were able to keep this separation in the
> Restlet API,
> so I don't see why we couldn't in a higher-level API.
We're open to any ideas that would make the API less HTTP specific
but I'd be wary of introducing some abstract layer that would require
casting etc to build a HTTP application. E.g. I'm not too keen on the
Servlet approach where you have the generic servlet APIs with a bunch
of HTTP-specific APIs layered on top.

> 4) POJO-based goal
> IMO, this is the goal where this JSR can bring the most value and
> we should
> concentrate on it first. We should have this scenario in mind: "How
> can I
> take my existing coarse grained POJOs and expose them as Web
> resources?" We
> shouldn't add any restriction on those POJOs, beside being
> JavaBeans maybe.
> Ideally, the same POJO could be at the same time a persistent EJB
> and a
> RESTful Web resource, only by specifying annotations.
I agree and I think the proposal largely achieves that unless I'm
missing something.

> As soon as we will start constraining the design of those POJOs, we
> will
> reduce the interest of choosing an annotation-based design. I know
> that this
> brings some challenges on how to expose and consume
> representations, but
> there are other approaches possible to this need.
With the proposed API you can already just return an arbitrary type
from a method provided the API can determine the correct media type
(or you are happy with application/octet-stream) and you have a
serializer registered for the return type. On the consuming side, the
proposed API requires Entity<T> for the request entity body but we
could consider relaxing that in the same way as we do for returned


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