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.)
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.
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.).
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. 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.
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