Re: Representation<T> and Entity<T>

From: Marc Hadley <Marc.Hadley_at_Sun.COM>
Date: Tue, 10 Apr 2007 14:57:12 -0400

On Apr 10, 2007, at 2:27 PM, Jerome Louvel wrote:
>> No, only JSR 311 implementations are expected to implement Entity<T>
>> so its OK to add new methods in a later revision of the API.
>> Representation<T> is concrete, so again its OK to add new methods
>> since a revised 311 impl will support them.
> 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.

> 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.

> 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:
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


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