jsr339-experts@jax-rs-spec.java.net

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

From: Santiago Pericas-Geertsen <Santiago.PericasGeertsen_at_oracle.com>
Date: Mon, 5 Mar 2012 15:17:25 -0500

On Mar 5, 2012, at 11:17 AM, Bill Burke wrote:

> Give me a usecase where a filter implementation (other than logging) *WOULD* be shared between client and server. In my experience, it will usually be the case that you *cannot* share filters between client and server. For example, an authentication filter is server-only. A browser-like cache is client-only. In both of these examples, you would actually make the client or server unusable at runtime if they were shared by accident (like say via scanning).
>
> All this is because the semantics of a RequestFilter are totally different from client and server. A RequestFilter on the server is reading and processing incoming requests. On the client, a RequestFilter is writing and sending outgoing requests. Sharing will occur mostly within Reader/Writer interceptors because the semantics of incoming/outgoing are encapsulated within these interfaces already.

 I understand your proposal now. At first glance, I thought you were proposing to split everything, including interceptors. I tend to agree with your observation about filters.

 I'm still not sure I prefer an API with more types to discern these cases in favor of a more general one with some illegal state exceptions. Need to think this through more. There's value in keeping the number of interfaces down.

 As for the scanning problem, I agree it's an issue that needs to be resolved one way or the other.

-- Santiago

>
> On 3/5/12 10:55 AM, Santiago Pericas-Geertsen wrote:
>> Bill,
>>
>> Just catching up with this e-mail thread. Many of the decisions that you are challenging are there to be able to _share_ filter implementations between servers and clients. Are you suggesting that we forego this design principle?
>>
>> Seems like a bad idea to me, but I'll look at the details before any further comments ...
>>
>> -- Santiago
>>
>> On Feb 28, 2012, at 12:20 PM, 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):
>>>
>>> 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
>>
>
> --
> Bill Burke
> JBoss, a division of Red Hat
> http://bill.burkecentral.com