[jax-rs-spec users] [jsr339-experts] Re: Consistency and awkwardness issues with Request/Response/Filter API

From: Sergey Beryozkin <>
Date: Wed, 29 Feb 2012 11:39:50 +0000

Hi Bill
On 28/02/12 17:20, Bill Burke wrote:
> I just wanted to list all the inconsistencies and awkwardness with the
> current Request/Response/Filter API and to suggest a different proposal
> here (read the readme):
> * Clients don't use the Request interface at all. Only within a client
> filter.
> * THere are methods that don't make sense on Request and Response
> depending on the semantics:
> - Request.selectVariant(), evaluatePreconditions(), etc. don't make
> sense on the client side.
> - Request.readEntity() methods don't make sense on the client side.
> - Response.readEntity(), close(), and bufferEntity methods don't make
> sense on the server side

So indeed it possibly make sense introducing a client side Request
As for Response, I do think that the close() method was redundant, one
can get the InputStream and close if needed but you also was keen on
having that method :-); indeed the semantics of close() on the server
side are not clear to me at all and as I indicated earlier on it might
interfere with other framework-specific features to do with calling
post-destroy methods on server resource classes.

As for bufferEntity - it should go IMHO - I agree it is possible that
occasionally the entity may need to be preserved for some later
processing but it is out of scope for Response itself - the InputStream
can be easily copied and preserved without having Response to manage it.

Not sure about readEntity on the server side - perhaps it should throw
IllegalStateException when called on the server ?

> * Header values aren't always objects or strings. On the server side,
> Request headers are strings, on the client side, they are Objects. Vice
> versa with Response headers.
I think Objects (on the client or server sides) should only be settable
when headers are set initially. On the get side - should always be strings.

> * Server-side deployment scanning is unusable if you have client-only
> Request or ResponseFilters in your classpath:
> This will require extra metadata (annotation or otherwise).
Not worried about this one :-)

> * On the server-side, we're changing how developers interact with
> JAX-RS. Instead of HttpHeaders we want them to inject RequestHeaders or
> a Request object.

I do want HttpHeaders be preserved as the main representation of the
request headers on the server side as having both HttpHeaders &
RequestHeaders does seem controversial to me, but I do not see why
replacing them with RequestHeaders changes the interaction pattern; as
for Request offering the reference to headers - this seems simply
another option as opposed to the pattern change

> * The RequestBuilder API creates weird filter states. You could call
> readEntity() before calling setRequest() on the filter context. Sure,
> you could modify the javadoc, but its just another fine-print item
> semantic the user has to be aware of. These fine-print javadoc comments
> are starting to add up!
> * The whole builder API is very awkward (not to mention unoptimized) for
> modifying reqeusts/responses within filters. A complete copy of the
> request or response needs to be created, then modified, then reset.
> There's also a lot of fine-print about this. If you set the entity of a
> server-side Request to be an InputStream, then this stream should be
> used to to unmarshal the request. Vice versa for client-side Response
> and OutputStream. More fine print!
> It make much more sense to modify Request/Response directly through APIs
> that are specific to the context you are in.
> * RequestBUilder API allows you to modify the URI on the server side.
> This makes some of the behavior UriInfo methods undefined in scenarios
> where it cannot figure out Base URI. More fine print!

I'll comment more asap
Thanks, Sergey


Sergey Beryozkin
Talend Community Coders