On Apr 12, 2007, at 8:57 AM, Jerome Louvel wrote:
>
> As there are many questions related to this topic, I thought it
> would be
> more productive to start a new thread and summarize my point of view.
>
> 1) Goals of JSR-311
>
> Heiko wants to "do one thing and do it right". I agree. All the
> question is
> about what is this "thing" we want to do. To cite the JSR:
>
> "This JSR will aim to provide a high level easy-to use API for
> developers to
> write RESTful web services independent of the underlying technology"
>
> "The goal of this JSR is to provide an easy to use, declarative
> style of
> programming using annotations for developers to write RESTful Web
> Services".
>
The full sentence reads: "The goal of this JSR is to provide an easy
to use, declarative style of programming using annotations for
developers to write RESTful Web Services and also enable low level
access in cases where needed by the application." Note the final clause.
> Three important things:
> - high level
> - easy to use
> - declarative style of programming using annotations
> - independent of the underlying technology (Servlet, Restlet, JAX-
> WS, etc.)
>
> If the goal was to use a traditional style of programming using
> classes,
> then we could just require people to:
> - have all resources extend a base Resource class
> - have all representations extend a base Representation class
>
> This is exactly the approach that we took in the Restlet API and it
> works
> very well. See the Javadocs:
> http://www.restlet.org/documentation/1.0/api/org/restlet/resource/
> package-su
> mmary.html
>
> We were just about to submit the standardization of the Restlet API
> to the
> JCP (as stated publicly and in our roadmap) when Sun proposed me to
> participate to this effort, stating the goals I've mentioned above.
> It was
> said that this API would be declarative, based on annotations (not
> excluding
> support classes of course) and was complimentary to our Restlet API. I
> agreed to join this EG on this ground and liked the idea of
> exposing pure
> domain objects (POJOs) as RESTful Web Services very much.
>
> Now, if the goal is now to force people to use API specific classes
> to model
> their representations and their resources because it is more
> convenient than
> annotating POJOs, then we radically change the goals of the JSR.
>
Nobody (as far as I can see) is suggesting to force use of "API
specific classes to model their representations and their resources".
Things like Representation<T> are explicitly trying to avoid that by
providing a generic wrapper that encapsulates additional metadata. I
don't see how you could infer that kind of approach from all of the
examples that we've been discussing over the last few days.
> I think that our main concern should be: how can we express the
> mapping from
> POJOs to RESTful Web services in the most compelling and in less
> intrusive
> ways, while supporting the important high-level Web/HTTP features
> found in
> RESTful applications (caching, stateless, identification by URIs,
> uniform
> interface, content negotiation, etc.).
>
I agree with that goal.
> Our goal should NOT be: what is the most convenient way to model
> Resources
> and Representations, otherwise the answer will inevitably be: just
> extend
> those Resource and Representation base classes where you can access
> to all
> the details of the request and the response.
The only class in the API that even remotely fits the description is
the WebResource interface and as I've explained previously that is an
optional interface only included as an avenue for support of JavaME
and scripting languages built on the JVM.
> This already works very well
> and can be already found in the Restlet API, which is BTW also
> supporting
> client-side Web applications and many more features. As I said
> already, I
> would be more than happy to submit the Restlet API to the JCP
> earlier than
> currently planned. See: http://www.restlet.org/about/roadmap.
>
Should I infer that your main objection to some of things in the
proposed API is that they encroach too much on Restlet ? If that is
the case then perhaps there is some scope for sharing of classes/
interfaces between the two where that makes sense ? Perhaps you could
list the areas where there are egregious overlaps (I think some
overlap is probably unavoidable).
> 2) From POJOs to Resources and Representations
>
> If the goal is still the stated one, then we should consider:
> - what are the common ways to model a problem domain as a graph of
> POJOS?
> - how can we expose RESTful Web Services out of this graph of POJOs?
> - how can we ensure that we don't require inconvenient changes
> (such as
> additional parameters to methods, base classes and implemented
> interfaces,
> logic change, etc.) to those POJOs?
>
> I've already underlined the example of EJB3/JPA that is allowing the
> annotation of graphs of POJOs in order to ensure their persistence
> in a
> RDBMS. Another example is the annotation of graphs of POJOs using
> JAXB in
> order to de/serialize them as XML, also without requiring changes
> to the
> POJOs.
>
> First, let's try to identify a number of mappings:
> - representation mapped to a primitive type (String, int, etc) via
> a getter
> - representation mapped to a common class (File, InputStream,
> ReadableChannel, DOM Document/Element, SAX Source, JAXP Result,
> etc.) via a
> getter
> - representation mapped to a graph of modifiable POJOs ->
> annotation and
> serialization aspects
> - representation mapped to a graph of unmodifiable POJOs ->
> wrapping and
> serialization aspects
>
When you write representation do you include metadata (headers) or
just the entity body ? The reason I ask is that many existing classes/
type don't have anywhere to put metadata but an application class
could be written/extended to include such information (not that I'd
advocate that approach).
> Then, let's consider serialization:
> - representation is serializable to fixed metadata (mediatype,
> language,
> dates, encoding, character set)
> - representation is serializable to a fixed set of metadata
> (variants for
> content negotiation)
> - representation is serializable to a dynamic set of metadata
>
> Now for resources mapping:
> - resource mapped to a single modifiable POJO
> - resource mapped to a single non-modifiable POJO -> wrapper
> - resource mapped to a graph of modifiable POJOs -> annotation
> - resource mapped to a graph of non-modifiable POJOs -> wrapper
>
When you write POJO do you mean the application data object ? As a
counter example, we've been working on an example that uses JPA where
the application data objects are in the form of JPA entites. The
classes that contain our annotations are separate and are much closer
to controllers in the MVC sense. Now its certainly possible to mix
controller and model in the same class but generally speaking its
cleaner to keep the separation and a lot of our thinking has been
modeled around an MVC approach where the JSR 311 annotations would be
for controllers rather than model classes.
> Heiko added a range of interesting questions:
> - Is it really desirable to have a resource being in charge of
> serialization?
> - Would a layer of indirection (serializer registry) be the better
> approach?
> - Regarding @MediaType and the like: It's a smart (although
> simple) to
> mix meta-data (i.e. @MediaType) with the actual payload (i.e. JAXB
> pojo)
> - How does Representation<T> fit into the picture from this point of
> view?
> --
>
> This is just an initial list of design problems that we should try
> to *solve
> together*, rather than quickly discard because their are some cases
> (rare or
> not) where it isn't practical/flexible to rely on annotations or
> not as easy
> as using a class-based approach.
>
I'm not sure exactly how to read the last paragraph. Either you are
saying:
- we shouldn't discard solutions that use annotations even when a
class-based approach is more practical/flexible, or
- we shouldn't discard design problems where use of a class-based
approach is more practical/flexible than annotations
Which, if either, do you mean ?
Thanks,
Marc.
---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.
- application/pkcs7-signature attachment: smime.p7s