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):
https://github.com/patriot1burke/jaxrs2-proposal-2-24-12
* 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
* 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.
http://java.net/jira/browse/JAX_RS_SPEC-176
* Server-side deployment scanning is unusable if you have client-only
Request or ResponseFilters in your classpath:
http://java.net/jira/browse/JAX_RS_SPEC-170
This will require extra metadata (annotation or otherwise).
* 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.
* 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!
--
Bill Burke
JBoss, a division of Red Hat
http://bill.burkecentral.com