Re: Representation<T> and Entity<T>

From: Dhanji R. Prasanna <>
Date: Tue, 10 Apr 2007 21:01:47 +1000

On 4/10/07, Jerome Louvel <> wrote:
> Could you give me an example where the pure annotation approach wouldn't
> be
> flexible enough to carry additional metadata?

If there is a header that is decided dynamically (based on some computation)
you cant specify it with static metadata. I would much prefer the
Representation<T> wrapper to forcing adding the metadata to the returned
entity. I certainly would like to have the flexibility to use arbitrary
domain objects (that may be written by other developers) as my content
payload and register serializers for them. This is not uncommon in large

> I agree with you and believe that the combination of (iii) and (iv) solves
> this issue.
> Agreed.

 We are in good agreement! =)

If the POJO used as entity/representation doesn't know how to serialize
> itself (pure domain POJOs), then it isn't useful to add annotations
> directly
> to those classes. An external serialization service will be necessary. In
> other cases where the POJO know how to serialize itself (with toString(),
> toXML() and toJSON() methods for example), it might be interesting to
> annotate the class directly. It could also be possible that the Resource
> POJO itself knows how to expose its Representations (again, with toXML(),
> toJSON() methods for example). The annotations should be flexible enough
> to
> accommodate the various use cases, especially as we don't want to
> constraint
> the annotated POJOs.

I dont suggest getting rid of the entity-level annotations. I agree they are
a useful addition and generally like the idea.
I feel however, that the broader use case calls for external (registered)
serializers as you call them, for reasons mentioned above, and is a good
You could capture this with a static binding too:

@Externalizer(MyPojo.class, MyPojoExternalizer.class)
public class RestfulService {

> I generally agree with your approach. I would prefer to specify dedicated
> annotations for common metadata (media type, character set, encoding, last
> modification date, expiration date, language, tag and size). For the rest
> of
> the request/response data model, we could rely on a @Context annotation
> with
> a parameter containing the name of the data to inject:

Big +.

> public void post(
> @Input InputStream in,
> @Context("serverInfo.address") String serverAddress,
> @Context("serverInfo.userAgent") String userAgent){
> ...
> }

We would just need to standardize the list of property names.

I'd go a step further and make them typesafe enums.

This is very
> similar to the approach used for custom log formats. Here is a complete
> list
> of properties that we expose in a similar way in the Restlet API:

Thanks, as an aside, this is useful for me!

> 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).
> Personally, I don't see the need of either the Representation class or the
> Entity interface in our JSR API.

I agree viz. Entity<T>, however as stated above, I believe an optional
Representation<T> artifact would be an elegant and flexible solution to
dynamic metadata, especially in cases where I cant/dont want to annotate
entity classes.