dev@jsr311.java.net

Re: Representation<T> and Entity<T>

From: Dhanji R. Prasanna <dhanji_at_gmail.com>
Date: Sat, 7 Apr 2007 09:33:52 +1000

On 4/7/07, Marc Hadley <Marc.Hadley_at_sun.com> wrote:
>
> Use
> of Entity<T> and Representation<T> are both optional and a developer
> can also use the raw T instead if they are not interested in the
> additional metadata supplied by the two interfaces.


This is a good approach, for the straightforward cases, one can use the raw
types directly but for additional metadata the Representation<T> interface
offers more flexibility.

>
> (iii)
>
> @UriTemplate("someuri")
> public class SomeBean {
> @HttpMethod
> Foo postData(Bar bar) {
> ...
> }
> }
>
> @Representation(mediaType="application/foo")
> public class Foo {
> ...
> }
>
> @Representation(mediaType="application/bar")
> public class Bar {
> ...
> }


If this is the choice, then it we should also have the option to specify it
on the service class (as in example (i))--as you point out marc, not all
source code is under ones control. More importantly, the api should not
force people to use only non-final classes or write delegate subclasses
simply to serve as a metadata bridge.

or (I'm interpreting here since the example only had one type rather
> than two but I think this is what was being proposed and I'm sure
> Jerome will correct me if I missunderstood)
>
> (iv)
>
> @UriTemplate("someuri")
> public class SomeBean {
> @HttpMethod
> @Representation(mediaType="application/foo")
> Foo postData(@Representation(mediaType="application/bar")Bar bar) {
> ...
> }
> }


I prefer this approach because it is more flexible in terms of having
multiple @HttpMethods returning consuming and different media types at the
same resource name/template. In this way, I can reuse methods internally
(consume both text/xhtml and text/xml for instance--and parse them with the
same internal method).

Now for some additional comments:
>
> To use approach (iii) the developer would have to write two
> subclasses of String just to have something to attach the
> @Representation to.


Not to mention that String is final too!

That means
> you can't edit the generated classes to add the @Representation
> annotation and the developer is again left having to write a subclass
> to attach the annotation to.


Even if you were able to edit those classes, I would argue that they are the
wrong place to annotate. The same entity may be consumed from a variety of
different encodings, I should not have to create an adapter subclass for
each one of those simply to specify the encoding. Also, it is the service
that depends on the entity, not the other way around--so I dont see a reason
for importing service-api classes (even annotations) in the entity .java.
The entity is roughly a domain model class. It should not model anything but
its target problem domain (fields and props of object being passed around).

>
> @ProduceMime("application/atom+xml")
> public class AtomFeed {
>
> @HttpMethod
> public Entry postEntry(Entity<InputStream> media) {
> ...
> }
>
Without the Entity class the developer
> would either have to create a new class to do the same job along with
> a serializer and deserializer for that class or use a low level API
> to extract the Content-Type (and possibly other) header from the
> request.


I would say that this problem could also be solved like so:

@HttpMethod
public Entry postEntry(InputStream media, EntityMetadata metadata) {
 ...
}

With the understanding that the presence of the second parameter is entirely
optional. I would even prever a more granular and flexible extension than a
catchall Entity metadata wrapper:

@HttpMethod
public Entry postEntry(InputStream media, @RequestParameters Map<String,
String[]> params, @Headers String[] headers) { //etc.
 ...
}

Which would let you choose from a set of predefined breakdowns of various
granularity (@RequestContext HttpServletRequest?). This somewhat ameliorates
the issue of having a too low-level api that I saw raised in an earlier
thread (the welcome thread), as it lets the user pick and choose how
low-level her service consumption api is.

The same problems occur when a method needs to return
> something where the metadata isn't known in advance. I think these
> are common enough use cases that its worthwhile standardizing the
> Entity interface and Representation class to save developers the
> additional effort their omission would cause.


To sum up, I am for the Representation<T> as an optional return when
warranted. But I feel that I have not clearly understood the purpose of
Entity<T> (beyond the fact that it carries metadata--which I think can be
addressed differently).

Marc.


Dhanji.