New method ResourceInfo.getAnnotation()

[mkarg]

This PR is a draft for further discussion of ResourceInfo.getAnnotation().

It is not intended for code review, voting, or merge. Please use it solely for discussion, unless we agreed upon the final API and have added TCK tests.

Closes #1292

[mkarg]

Kindly requesting to continue our discussion here. :-)

In particular the question is: What to do with custom annotations like @Tracing (where possible the annotation author wants to treat it as a JAX-RS annotation) or @RolesAllowed (where there is a published spec mandating inheritance always, independent of JAX-RS annotation). What first came to my mind (and is found in this first draft) is to have an option for custom annotations: JAX_RS (treat it as it would be a JAX-RS annotation), INHERIT (performan inheritance always) or NONE (never inherit it).

WDYT?

[chkal]

Shouldn't a JAX-RS API for retrieving the effective annotations for a given resource method always use the JAX-RS annotation inheritance rules? Just thinking out loudly. I'm not 100% myself sure yet.

[mkarg]

Shouldn't a JAX-RS API for retrieving the effective annotations for a given resource method always use the JAX-RS annotation inheritance rules? Just thinking out loudly. I'm not 100% myself sure yet.

You missed the point that the customization of the algorithm is for custom annotations only. For JAX-RS annotations certainly always the JAX-RS algorithm is used. This customization is needed as e. g. @RolesAllowed is commonly used with JAX-RS, but is not a JAX-RS annotation itself, and mandates a different "always-inherit" policy.

[jamezp]

Shouldn't a JAX-RS API for retrieving the effective annotations for a given resource method always use the JAX-RS annotation inheritance rules? Just thinking out loudly. I'm not 100% myself sure yet.

You missed the point that the customization of the algorithm is for custom annotations only. For JAX-RS annotations certainly always the JAX-RS algorithm is used. This customization is needed as e. g. @RolesAllowed is commonly used with JAX-RS, but is not a JAX-RS annotation itself, and mandates a different "always-inherit" policy.

I'm not too sure how I feel about that. The enum feels a bit clumsy, but I might not fully understand the use-case. While I can appreciate that @RolesAllowed is no inherited via the annotation, there's nothing really stopping a user from doing ResourceInfo.getResourceAnnotation(RolesAllowed.class, CustomAnnotationsInheritancePolicy.JAX_RS). It feels out of scope for the Jakarta REST API.

Note, I'm not convinced one way or the other, this is just my initial take on it.

I also wonder if the return type should be something like List<A> for repeatable annotations if we're going to allow any annotation to be resolved.

I'm also not to clear on the meaning on CustomAnnotationsInheritancePolicy.INHERIT. It states:

Inherit custom annotations but do not treat them as JAX-RS annotation.

What does that mean? Is there an expectation that annotations on interfaces get included? Which annotation wins in a case where both an interface and implementation are annotated?