From: Marc Hadley <Marc.Hadley_at_Sun.COM>
Date: Wed, 25 Apr 2007 13:40:56 -0400

Jerome proposes an @Representation annotation as follows:

public @interface Representation {
     String mediaType() default "application/octet-stream";
     String language() default "en";
     String characterSet() default "UTF-8";
     String encoding() default "identity";
}

If I've understood the intent properly then I think the following
should be added to the annotation definition:

@Target({ElementType.PARAMETER, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)

I'm assuming quite a bit here since there wasn't much documentation
but this annotation seems to be trying to do a number of things:

(i) mark a method as being exposed as a resource method
(ii) mark a method parameter corresponding to a request entity
(iii) provide metadata for the entity returned by a method
(iv) provide conneg data for the entities in a request and response

Lets look at these one by one and compare to the sketch2 APIs.

(i) Marking a resource method

@Representation
public Client getClient() {}

public void put(@Representation Client client) {}

public void delete()

vs

@HttpMethod
public Client getClient() {}

@HttpMethod
public void put(Client client) {}

@HttpMethod
public void delete()

Since @Representation doesn't appear on the delete method its not
clear that it is really being used to mark a resource method or
whether the name of the resource method alone determines whether it
is exposed. I think the latter is dangerous since it can easily lead
to unforeseen consequences when an existing class method matches the
naming pattern. get in particular is a popular method prefix as is
put. I much prefer explicit marking as per @HttpMethod (though I'm
open to a name change as has been suggested).

(ii) Mark a method parameter corresponding to a request entity

public void put(@Representation Client client)

vs

public void put(Client client) {}

The @Representation annotation doesn't seem to add much here. In the
sketch2 API, a resource method may have zero or one method parameter
that isn't annotated and that parameter corresponds to the request
entity.

(iii) Provide metadata for the entity returned by a method

The default values could cause problems. There no way (AFAICT) when
using reflection to determine whether an annotation property value is
specified or is being defaulted. This means, e.g. that

@Representation
public Client getClient() {}

is equivalent to:

@Representation(mediaType="application/octet-stream", language="en",
characterSet="UTF-8" encoding="identity")
public Client getClient() {}

If (i) above is an intended usage then I'd suggest making the
defaults be "" since otherwise the presence of @Resource will fix the
metadata values in addition to marking the method.

Note that in the sketch2 API a single valued @ProduceMime annotation
will perform the same function for the media type of a response.

(iv) Provide conneg data for the entities in a request and response

In the sketch2 API, @ProduceMime and @ConsumeMime each provide a list
of media types that can be generated and consumed by a method.
@Representation is single valued so you can't easily write a method
that e.g. accepts multiple formats. There also doesn't appear to be
any way to use @Representation at the class level for a number of
methods with similar properties - at a minimum you'd need separate
properties or annotations for request and response I'd think.

I'd be interested to hear whether folks think that its important to
provide automatic conneg support for language, charset and encoding ?

Thanks,
Marc.

---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.