dev@jsr311.java.net

RE: Representation<T> and Entity<T>

From: Jerome Louvel <jerome.louvel_at_noelios.com>
Date: Wed, 11 Apr 2007 12:07:42 +0200

Marc,

> > But this isn't stated in the Javadocs, and even if it was stated,
> > nothing
> > would technically prevent an API user to implement it in order to
> > extend his
> > custom representation class. Then, as soon as we touch the
> > interface, we
> > have many complaints.
>
> That is true of *any* interface. In this case we provide a mutable
> implementation of the interface in Representation so I think
> the risk
> is low. The javadoc could be clearer though I agree.

Usage of interfaces in public API is different than in custom code that you
fully control. The risk is low but does exist and I persist to say that it
isn't necessary (I was a big fan of interfaces before).

Interfaces in public APIs should have a very focused and stable contract and
consist of no more than one or two methods. Once they are defined they
should never change (or will require the usage of derived interfaces like
those that plague Eclipse's code base) Otherwise, usage of an abstract or
base class is just fine and allow the reuse on logic too.

> > And beside that it doesn't add lot of value and it
> > isn't that flexible.
> >
> It saves having two additional annotations for media type and
> language injection and has a nice mapping to request entity in HTTP.
> It could be extended to provide access to additional request
> metadata
> if that were felt to be useful.
>
> The value of an interface in this instance is that it can be used
> with whatever backing a container provides. The same applies to
> HttpRequestContext and HttpResponseContext.
 
I propose to unify Entity, HttpRequestContext and HttpResponseContext into a
single Context class that could be inject at the local variable level and
eventually at the parameter level.

It would be a two-way communication point with the API implementation and
could contains methods such as:

get/setInput(): Representation<T>
get/setOutput() : Representation<T>

> > The overuse of interface is a common mistake in API design that we
> > made in
> > the initial cycles of the Restlet API, until someone pointed me to
> > Joshua
> > Bloch and Eamonn McManus's recommendations on API design:
> > http://www.artima.com/weblogs/viewpost.jsp?thread=142428
> >
> I think we've steered between the rocks. We've used
> interfaces in one
> of two cases:
>
> - for things that client code needs to implement, e.g. a serializer
> in the streaming SPI
> - for things that an API runtime impl will provide where there's an
> advantage to the container being able to provide its own
> implementing
> class, e.g. HttpRequestContext can be wrapped around
> HttpServletRequest without lots of data copying between the two
 
But, wrapping is also very easy to do using the adapter design pattern. If
done well you don't need any data copying, just adaptation.

Best regards,
Jerome