Skip to main content

[jax-rs-spec users] [jsr339-experts] Re: Re: Request interface duplicates MBRs, HttpHeaders and UriInfo

  • From: Marek Potociar <marek.potociar@...>
  • To: jsr339-experts@...
  • Cc: Bill Burke <bburke@...>
  • Subject: [jax-rs-spec users] [jsr339-experts] Re: Re: Request interface duplicates MBRs, HttpHeaders and UriInfo
  • Date: Mon, 30 Jan 2012 17:21:46 +0100
  • List-id: <jsr339-experts.jax-rs-spec.java.net>



On 01/30/2012 03:08 PM, Bill Burke wrote:
> 
> 
> On 1/27/12 10:28 AM, Marek Potociar wrote:
>> The #2 is the current plan. We just cannot officially deprecate 
>> HttpHeaders now. We can only javadoc against using them.
>> I'll consider moving the constants. I'll also re-consider option #1. 
>> Please file a Jira issue.
>>
> 
> Yeah, can you elaborate more on why we have Request/ResponseHeaders and not 
> a unified HttpHeaders?  I just don't feel
> this approach is consistent with what you've done with Request/Response.

The sole reason for not reusing HttpHeaders was that the interface comes with 
the following JAX-RS 1.x heritage:

    /**
     * Get the values of a HTTP request header. The returned List is 
read-only.
     * This is a shortcut for <code>getRequestHeaders().get(name)</code>.
     * @param name the header name, case insensitive
     * @return a read-only list of header values.
     * @throws java.lang.IllegalStateException if called outside the scope of 
a request
     */
    public List<String> getRequestHeader(String name);

    /**
     * Get the values of HTTP request headers. The returned Map is 
case-insensitive
     * wrt keys and is read-only.
     * @return a read-only map of header names and values.
     * @throws java.lang.IllegalStateException if called outside the scope of 
a request
     */
    public MultivaluedMap<String, String> getRequestHeaders();

    /**
     * Get a list of media types that are acceptable for the response.
     * @return a read-only list of requested response media types sorted 
according
     * to their q-value, with highest preference first.
     * @throws java.lang.IllegalStateException if called outside the scope of 
a request
     */
    public List<MediaType> getAcceptableMediaTypes();

    /**
     * Get a list of languages that are acceptable for the response.
     * @return a read-only list of acceptable languages sorted according
     * to their q-value, with highest preference first.
     * @throws java.lang.IllegalStateException if called outside the scope of 
a request
     */
    public List<Locale> getAcceptableLanguages();

    /**
     * Get the media type of the request entity
     * @return the media type or null if there is no request entity.
     * @throws java.lang.IllegalStateException if called outside the scope of 
a request
     */
    public MediaType getMediaType();

    /**
     * Get the language of the request entity
     * @return the language of the entity or null if not specified
     * @throws java.lang.IllegalStateException if called outside the scope of 
a request
     */
    public Locale getLanguage();

    /**
     * Get any cookies that accompanied the request.
     * @return a read-only map of cookie name (String) to Cookie.
     * @throws java.lang.IllegalStateException if called outside the scope of 
a request
     */
    public Map<String, Cookie> getCookies();

Clearly, the interface is too request oriented, not only in terms of javadoc, 
but also in terms of method signatures - 5
out of 7 methods are request-specific. Here are the options we had:

O1. Keep & extend HttpHeaders
O2. Keep HttpHeaders for request and introduce ResponseHeaders for response
O3. Discourage HttpHeaders in javadoc and introduce new set of interfaces: 
new ResponseHeaders as well as new
RequestHeaders (that extends HttpHeaders to preserve BW compatibility).

We chose O3. It introduces consistent naming pattern (Request/Response -> 
RequestHeaders/Response/Headers). It
acknowledges the fact that there are request and response specific headers. 
It is backward compatible (RequestHeaders
extends HttpHeaders). It keeps the door open for future pruning of 
HttpHeaders.

I can see one more alternative that I haven't consider before:

O4. Keep the HttpHeaders as is (with the goal to prune them later); add 
HttpHelper static utility class that would
contain static methods for type-safe header extraction from a MultivaluedMap 
as well as constants for HTTP header names;
introduce a new method into Request and Response that would return headers in 
the form of MultivaluedMap:
    public MultivaluedMap<String, String> getHeaders();

O4 means one less component in the API compared to O1. It however means we 
would loose the ability to inject response
headers. There are 2 potential solutions:

S4a. introduce a new injection qualifier @Headers (which brings us on par 
with O1 in numbers of new API components.
S4b. since one can inject Request and Response, we can accept the trade-off.

Let me know what are your thoughts on the whole subj.

Thanks,
Marek

> 
> Bill
> 


[jax-rs-spec users] [jsr339-experts] Re: Request interface duplicates MBRs, HttpHeaders and UriInfo

Sergey Beryozkin 01/26/2012

[jax-rs-spec users] [jsr339-experts] Re: Request interface duplicates MBRs, HttpHeaders and UriInfo

Bill Burke 01/26/2012

[jax-rs-spec users] [jsr339-experts] Re: Request interface duplicates MBRs, HttpHeaders and UriInfo

Marek Potociar 01/27/2012

[jax-rs-spec users] [jsr339-experts] Re: Request interface duplicates MBRs, HttpHeaders and UriInfo

Bill Burke 01/30/2012

[jax-rs-spec users] [jsr339-experts] Re: Re: Request interface duplicates MBRs, HttpHeaders and UriInfo

Marek Potociar 01/30/2012

[jax-rs-spec users] [jsr339-experts] Re: Re: Request interface duplicates MBRs, HttpHeaders and UriInfo

Bill Burke 01/30/2012

[jax-rs-spec users] [jsr339-experts] Re: Re: Request interface duplicates MBRs, HttpHeaders and UriInfo

Sergey Beryozkin 01/30/2012

[jax-rs-spec users] [jsr339-experts] Re: Re: Request interface duplicates MBRs, HttpHeaders and UriInfo

Bill Burke 01/30/2012
 
 
Close
loading
Please Confirm
Close