Comments inline.
On Apr 12, 2007, at 2:57 PM, Jerome Louvel wrote:
>
> Hi all,
>
> 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".
>
> Three important things:
> - high level
> - easy to use
> - declarative style of programming using annotations
> - independent of the underlying technology (Servlet, Restlet, JAX-
> WS, etc.)
>
The JSR text could be misread to mean "independent of underlying
technology (HTTP, WS-*, ...) which I definitely hope nobody here wants.
> 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
>
I don't see this as a conflict. Why can't the API use a "traditional
model" (I didn't even know OO had become traditional yet) and use
annotations wherever they make things easier?
> 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.
The JSR says that
"The goal of this JSR is to provide an easy to use, declarative style
of programming using annotations for developers to write REST ful Web
Services and also enable low level access in cases where needed by
the application."
My understanding was that this means that access to every "low-level"
feature is possible in a standardized way.
> 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.
>
> 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.).
>
Just as a matter of personal opinion, I would be very disappointed if
this was all JSR 311 achieves. I don't want to see POJOs mapped to
RESTful Web services; I want to see a good and standardized
programming model for building RESTful HTTP applications in Java.
Easy things should be easy and hard things possible.
> 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.
I disagree: I strongly believe this *should* be the goal. I don't see
how this stops us from providing an annotation-based programming
model, too.
> 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.
>
I'm not at all sure I like the RESTlet API, which is quite likely
because I still haven't looked at it ihn detail. But I would
definitely welcome it as one possible starting point for this JSR,
just as much as the current proposal from Marc and Paul.
Again, if the stated goal of this JSR is "define a good mapping of
POJOs to RESTful Web services", this seems just as backwards to me as
most of the JAX-WS stuff.
Stefan
--
Stefan Tilkov, http://www.innoq.com/blog/st/
> 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
>
> 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
>
> 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.
>
> Best regards,
> Jerome Louvel
> --
> http://www.restlet.org
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe_at_jsr311.dev.java.net
> For additional commands, e-mail: dev-help_at_jsr311.dev.java.net
>