RE: Sketch of updated APIs (was Re: Redirection and creation)

From: Jerome Louvel <>
Date: Thu, 19 Apr 2007 19:47:59 +0200


I understand your concerns.

(i) For the performance, I'm sure there would be ways to optimize the
introspection if necessary to not have to do it for each call for example.

(ii) At first is does seem scaring but once we have a clear mind about the
API, I hope that every piece will fall in nicely. The issue with starting
with an extensive API like your prototype, is that it forces us to embrace
the full complexity in one shot instead of progressively add complexity.

(iii) In most cases, those HTTP metadata may not even be needed. I'm not
sure that ROME/Atom is the best sample use case as it seems to me to be a
rather advanced use case already. Probably we should start with a simpler
case (but realistic one) and worry about Atom a bit later.
It seems to me that we went quite far in the design alternatives
discussions. As Stefan pointed out, we should focus on illustrating those
alternatives with concrete examples. I've started working on illustrating my
view using the Blinksale API as suggested by Dhanji. It won't run, but just
articulate the pieces together (annotations, POJOs, etc.).
Best regards,
> -----Message d'origine-----
> De : Marc.Hadley_at_Sun.COM [mailto:Marc.Hadley_at_Sun.COM] 
> Envoyé : mardi 17 avril 2007 20:15
> À :
> Objet : Re: Sketch of updated APIs (was Re: Redirection and creation)
> On Apr 16, 2007, at 11:39 AM, Marc Hadley wrote:
> > - Reworked Representation and HttpResponse to use annotations to  
> > mark their properties as I'd outlined earlier in the thread.  
> > Essentially the representation and response classes become "pre- 
> > baked" instances of return types but the annotation 
> approach allows  
> > an application to use their own classes instead if they so wish.
> >
> There are a few things that bother me about this approach:
> (i) Performance - an implementation would have to do a *lot* of  
> reflection to extract the metadata. Each field and bean getter will  
> have to be checked for each of the metadata annotations we define  
> and, because annotations on methods are not inherited, an  
> implementation would also have to walk the inheritance hierarchy to  
> look for metadata annotations on superclasses too.
> (ii) Complexity - the specification will need to define rules for co- 
> occurrence, cardinality, inheritance and overriding for each of the  
> metadata annotations. Rules may turn out to be different for  
> different annotations. E.g. one would expect it to be an error to  
> have multiple @HttpStatus annotations on a bean but it would OK to  
> have multiple @HttpHeader annotations, possibly even multiple 
> for the  
> same header depending on the header. The specification will 
> also need  
> to define precedence rules where the metadata can be obtained from  
> multiple sources
> (iii) Benefit - the usefulness of this approach hinges on whether it  
> will be common for existing application classes to have fields or  
> properties that map directly to HTTP metadata. E.g. will it 
> be common  
> for an application class to have an existing field or property that  
> provides the HTTP status code for a response that contains the data  
> encapsulated by the class. Personally I find this quite unlikely:  
> even looking at something like the ROME library classes for the Atom  
> format one finds gaps where additional metadata would be required. I  
> suspect that many application classes will be quite devoid of HTTP  
> metadata and that the primary use of the JSR 311 API will be to  
> develop RESTful facades to existing application data classes.
> Thoughts, comments ?
> Marc.
> ---
> Marc Hadley <marc.hadley at>
> CTO Office, Sun Microsystems.