[jax-rs-spec users] [jsr339-experts] General rule for exposing/manipulating header values

From: Bill Burke <>
Date: Fri, 24 Feb 2012 16:01:07 -0500

This is related to my last comment on:

Any interface that manipulates or exposed header values the client and
server side and within Filter or Interceptors has to follow certain
guidelines. You have to be extremely careful on whether the header
manipulation api deals with header values that are strings or

A ReaderInterceptorContext the header values can ONLY be strings as they
are ALWAYS provided from an HTTP message (request on server side,
response on client side). Vice-versa for WriterInterceptorContext.
Header values may be actual Objects rather than strings as they are
provided by user-code. This is specifically what I was referring to in
previous emails.

Both RequestHeader and ResponseHeader instances can either be populated
through an HTTP message or from user code since they can be used on both
client and server. Therefore their interfaces that manipulate or expose
header values must be more generic and return java.lang.Object.

Furthermore, header values must not be marshalled into string values
until you are about to send the bits on the wire. And the following
must be true:

FooHeader fh = new FooHeader();

Request/Response r = builder.header("foo", fh).build();
Object value = r.getReXXXXHeaders().getHeader("foo");

value == fh

Same reference equality must be true if the header value was set via the
Invocation.Builder interface. Why is this important? Well, consider a
digital signature header like DKIM. You really can't complete the
header until you calculate the signature of the entity and you might
need information contained in the header object to calculate the
signature (i.e. a private key).

Anyways, hope this sheds a bit of light on things.

Bill Burke
JBoss, a division of Red Hat