[jax-rs-spec users] [jsr339-experts] Re: Re: ContainerResponseContext.getEntityAnnotations() discrepancy

From: Marek Potociar <>
Date: Mon, 20 May 2013 19:04:50 +0200

On May 17, 2013, at 4:45 PM, Bill Burke <> wrote:

> On 5/17/2013 10:41 AM, Sergey Beryozkin wrote:
>> Hi Bill
>> On 17/05/13 15:35, Bill Burke wrote:
>>> The TCK test lead and I are both interpreting
>>> ContainerResponseContext.getEntityAnnotations()
>>> IMO, if the app code has attached an entity view
>>> ResponseBuilder.entity(Object, Annotation[])
>>> then only those attached annotations should be returned by
>>> getEntityAnnotations().
>>> The TCK test lead is saying that both those annotations *AND* the
>>> annotations on the resource method should be returned.
>>> The language in the spec is a tiny bit unclear, but, IMO, it makes no
>>> sense to include both of them. The whole point of
>>> ResponseBuilder.entity(Object, Annotation[]) is so that you can
>>> exclusively provide the annotations attached to the entity.
>> We talked with Marek a lot about it, well, the rules are that
>> ResponseBuilder.entity method appends Annotations, and
>> ContainerResponseFilter replaces them, is that perfect, I'm not sure,
>> but I don't mind :-).
> I *DO* mind.
> Marek is absolutely wrong for taking this stance. With Marek's interpretation, you cannot override settings on the method. For example, maybe you are implementing an interface and want to override the entity annotations on that interface.

Quite naturally, I would disagree with the above. ;-)

I can remember having long discussions about how it should be, and after weighing all PROs and CONs, we decided this way.

To reiterate, here are the main reasons for the behavior for processing response entity annotations when invoking a resource method:

Annotations from a resource method have always been passed to JAX-RS 1.x MBWs. We do not want to break this.
We do not want to go against Liskov Substitution Principle by overriding annotations placed on the method.
If entity(Object, Annotation[]) would be overriding the default behavior of attaching method annotations to the response entity context, we would be exposing an API that breaks LSP and introduces a side effect that is not obvious from the code.
Further specialization (by adding more annotations) is the use case we consider more prevalent and the one that we want to support as it does not break LSP.

Now, to make sure that these method annotations can still be overridden, the lower-level response filter API was the right place to do it.

What I noticed is that the javadoc of the related methods is not completely clear in this regard. It's mostly a problem of changing the decisions based on the discussion back and forth. I have filed a new issue to make the javadoc clear:

FWIW, I understand that this is somewhat controversial topic, so if we can come up with strong concrete use cases that would support the behavior advocated by Bill, I would not object to adding a separate method to ResponseBuilder for this use case, e.g.: entity(Object entity, Annotations[] annotations, boolean overrideMethodAnnotations)

> --
> Bill Burke
> JBoss, a division of Red Hat