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
>