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:
javax.ws.rs - mainly annotations
javax.ws.rs.core - lower level APIs (more on these below)
javax.ws.rs.representation - base class and helper subclasses for
dealing with common representation formats
javax.ws.rs.response - 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:
javax.ws.rs.Entity - generic abstraction for a HTTP request entity,
provides additional metadata for a request entity.
javax.ws.rs.WebApplicationException - standard exception that an
application can throw when something goes wrong. allows setting of
the response status code and entity body
javax.ws.rs.core.CacheControl - abstraction for a response cache
control header, saves developers from having to manually build a
cache control header string value
javax.ws.rs.core.Cookie - abstraction for a cookie supplied in
request, frees developers from having to parse cookies
javax.ws.rs.core.NewCookie - abstraction for a cookie that an
application wishes to set in a response, frees developers from having
to manually build a set cookie header
javax.ws.rs.core.MediaType - abstraction for a media type, frees
developers from having to parse and build headers that include media
types (Content-Type, Accept, etc)
javax.ws.rs.core.MultivaluedMap - a generic map that allows multiple
values for a single key - useful for HTTP headers, query parameters,
matrix parameters.
javax.ws.rs.core.PathSegment - 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
javax.ws.rs.core.ResourceConfig - 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.
javax.ws.rs.core.HttpContext - 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.
javax.ws.rs.core.HttpRequestContext - 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
javax.ws.rs.core.HttpResponseContext - provides access to response
information, makes it easy to set additional headers not supported in
one of the pre-packaged javax.ws.rs.response.HttpResponse 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.
javax.ws.rs.core.WebResource - an interface that a JVM-based
scripting language could implement to be exposed as a resource.
javax.ws.rs.representation and javax.ws.rs.response 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 javax.ws.rs.core 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
data.
> 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.
>
Agreed.
> 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
representations.
Thanks,
Marc.
---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.
- application/pkcs7-signature attachment: smime.p7s