On Apr 12, 2007, at 10:39 AM, Jerome Louvel wrote:
>
>> 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?
>
I interpret this to mean that we should provide enough of an API
(high or low level) to meet what the EG decides is a useful 80/20
point and provide some kind of escape hatch whereby an application
can drop down to a container API to meet the other 20%. How we
subdivide the 80% between high and low level APIs is another matter
as is what qualifies as high level and what as low level.
>> 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.
>
I think I'm OK with more granular approaches for request data (i.e.
dropping Entity<T>). I'm less convinced by the idea of annotating
classes that will become entities for all the reasons previously
given. E.g. I think I'm OK with
Foo postFoo(Foo foo, @HeaderParam("Content-Language") String language)
instead of
Foo postFoo(Entity<Foo> foo)
but I'm less convinced by
MyInputStreamWrapper getBar()
class MyInputStreamWrapper {
@EntityBody
InputStream data;
@MediaType
String type;
@Language
String language;
@...
...
}
instead of
Representation<InputStream> getBar()
A compromise would be to define the @EntityBody, @MediaType, etc
annotations and then define a standard Representation<T> class using
those annotations. Most folks could just the standard
Representation<T> class when the metadata can't be determined
statically but if someone really wanted to they could define their
own representation class that uses the @Data, @MediaType etc
annotations directly. That's a bunch of extra annotations but its
pretty flexible.
We could probably extend that approach to Response too if folks think
its worth pursuing.
>
> 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.
>
I think this is going to be a sticking point. I think we should be
free to use classes/interfaces in this JSR where they make sense. I
don't think its reasonable to exclude use cases purely on the grounds
that their requirements are better met with classes/interfaces than
annotations.
Marc.
---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.
- application/pkcs7-signature attachment: smime.p7s