Re: New sketch of updated APIs

From: Paul Sandoz <Paul.Sandoz_at_Sun.COM>
Date: Fri, 20 Apr 2007 12:17:31 +0200

Dhanji R. Prasanna wrote:
> On 4/20/07, *Paul Sandoz* <
> <>> wrote:
> Response/ResponseProvider are not annotated. ResponseProvider defines:
> IMHO (at risk of repeating myself!) unless there are compelling
> use-cases for the latter the former is sufficient.

I may have caused some confusion: by 'latter' i was referring to the use
of annotations and by 'former' i was referring to Response and

> I like the idea that Response is an abstract impl of a (more) general
> low-level interface. It is useful for creating proxies, mock impls and
> such. I also do not like having an abstract class as an api-level
> contract for many reasons (the fact that they are prone to breakage with
> variable shadows, etc.).
> I would vote for the inclusion of both, but refine the nomenclature and
> separate their roles. "Provider" has connotations of factory-style
> artifacts, whereas Response is a more appropriate name for the contract.
> I propose calling the interface "Response" and the builder "Responder."

Your proposed naming sounds good.

> I would also hide the public constructor of Responder so that it is not
> externally constructable.
> The nice thing is the latter and former are rather independent. It
> appears we have some consensus on the former to take this forward,
> while still allowing use-cases for the latter to be
> proposed/discussed/investigated. Is that a reasonable way forward?
> I see that MultivaluedMap extends Map, which I would advise against as
> it is a contract breach. From the javadoc:
> "public interface *Map<K,V>*
> An object that maps keys to values. A map cannot contain duplicate keys;
> each key can map to at most one value."
> There is no elbow room (unlike the optional contract for "destructive"
> methods).

Can you explain a bit more about "destructive" methods?

In general we need to get the right abstraction for what is currently
MultivaluedMap for a thing where a key can have a one or more values. V
can also be List<T>. List<String> is used for request headers.

I noticed RESTlet uses something different around the concept of a
series. We chose Map because we thought the most common operation is
likely to be put/get using a key, either putting/getting a single value
or putting/getting a list of the values, and this can be efficiently and
easily supported using a HashMap implementation (which scales for large
number of keys).

A multivalued thing in general is rather common for query, request
header, matrix and, to some extent, URI parameters all of which are
consumed. But perhaps the same abstraction is not required for the
response headers that are produced?

> Rather than the visitor pattern, why not simply return an immutable map
> that the runtime can add to its value-set? It is more consistent with
> the rest of the methods (getEntity() etc.) too.

The reasons we thought for ResponseProvider (or Response as you propose)
adding its meta-data rather than returning the meta-data is:

1) the runtime can provide the implementation, which may be
    optimized/resued (e.g. the underlying container artifacts could be
    set/get directly using this interface); and

2) the particular ResponseProvider, e.g. for created, it is not
    necessary to create a map for when the common meta-data is used.

> Or is there a case for
> overwrite-support for values already in the multimap? Like a "default"
> header set that you can override perhaps (which I dont see the need
> for since this a low-level interface anyway).

That case did not occur to me. I do not see the need either for such a case.


| ? + ? = To question
    Paul Sandoz