Marc,
> 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.
It was an excerpt. The complete section 2.1 has several paragraphs. I
interpret "enable low level access" to giving access to artifacts such as
raw HTTP headers, which is a useful goal but not an important one for me.
Should this be interpreted as: provide a high-level annotation-based API as
well as a full low-level class-based HTTP processing API?
> 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 was referring exactly to the Representation<T>. Heiko was mentioning that
for him this should be the only way to expose representation metadata of
POJOs. I know that we agree on the complimentary role of the
Representation<T> wrapper with finer-grained metadata annotations.
[...]
> > 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.
But I don't remember your answer regarding the fact that if JavaME or
scripting languages lack the support for annotations, it is probably not a
good idea to use an annotation-based API in the first place.
The WebResource Javadocs don't even mention JavaSE but instead:
"Implmenting classes must be annotated with @UriTemplate and may use
@ConsumeMime and @ProduceMime to filter the requests they will receive."
JavaSE and scripting languages could perfectly use the Servlet or Restlet
API or even add support for annotations. The JSR goals where mentioning only
a subset of the API for JavaME, not an alternative API. IMO, this creates
confusion and complicates the implementation.
> 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).
Of course, if we end up building an alternative low level API in this JSR
this is a big concern! It would uselessly overlap on the Restlet API, and
even on the Servlet API which has already defined a request handling API. We
definitely don't need specific interfaces such as HttpRequestContext,
HttpResponseContext or WebResource and its handle(request, response) to give
access to low level HTTP semantics and to solve our main goals.
For the rest, there will obviously be overlap with the Restlet API in the
Resource and Representation area as well as in the metadata area (MediaType,
Cookie, CookieSetting, Reference/URI, CharacterSet, Encoding, etc.). Not a
huge deal, we can live with this overlap.
It would have been so much easier to first standardize the Restlet API and
then build on top of it rather than starting from the higher-level. But I
guess, we can't do anything about that now... Still, I'm trying to
participate to this JSR in an open and constructive way, I hope this is
clear too.
> > 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).
representation = data/content/entity + metadata
For example, the File class has a last modification date available, as well
as size. Media type, language, encoding can be inferred from the file name
extensions (using MIME mapping such as the one of the Servlet API).
Domain POJOs may very well have a last modification data available. The rest
of the metadata can be completed by the serializers with no need for
wrappers or annotations in most cases.
> 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.
IMHO, the MVC paradigm is different (with some similarities) to the REST
paradigm. Instead of speaking of Controller and View, we should be speaking
in terms of Resource and Representation.
An EJB service will typically be exposed as a Resource while an EJB Entity
(or a graph) will be mapped to Representations.
The POJO domain model I'm referring to it contains both service and data
oriented classes.
[...]
> > 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 ?
1) If a class-based approach is more practical/flexible, the Restlet API
could be used directly rather trying to retro-fit an annotation-based API to
support this case too.
2) We should focus on supporting as many POJO design style as possible in
our annotation-based API, such as EJBs, JAXB, db4o, etc.
Best regards,
Jerome