Request for revised terminology describing ways annotations can be present or not

[Alex Buckley]

On 3/26/2013 4:10 PM, Joe Darcy wrote:
> In brief, and processing API requires that the set of annotations
> present on a body of code be computed. To preserve behavioral
> compatibility, "present" in this context means directly present in the
> source code or class file representation of a declaration or present via
> inheritance. Container look-through should *not* be considered.
>
> I was hoping to describe this arrangement using the "directly present"
> and "present" terminology from java.lang.reflect.AnnotatedElement or
> javax.lang.model.AnnotatedConstruct. Unfortunately, those terms allow
> look though to occur based on which method is being called.
>
> So what I'd like to have is a set of definition in the
> AnnotatedElement/AnnotatedConstruct types which support the following
> distinctions:
>
> 1) directly present (no inheritance, no container look through)
> 2) present directly or present indirectly via inheritance
> 3) present directly or present indirectly via container look through
> 4) present directly or via the supported interaction of inheritance and
> look through

The building blocks are easy:

a) An annotation A is DIRECTLY PRESENT on an element E if E is 
associated with a RuntimeVisibleAnnotations or 
RuntimeVisibleParameterAnnotations attribute, and the attribute contains A.

b) An annotation A is INDIRECTLY PRESENT on an element E if E is 
associated with a RuntimeVisibleAnnotations or 
RuntimeVisibleParameterAnnotations attribute, and A's type is 
repeatable, and E contains exactly one annotation whose value element 
contains A and whose type is the containing annotation type of A's type 
(§9.6).

The trouble is PRESENT. If it's an SE7-era PRESENT - aware of 
inheritance but not containment - then it's very hard to find a term for 
an SE8-era PRESENT which knows both inheritance and containment. Still, 
let's start with an SE7-era PRESENT and see what happens:

c) An annotation A is PRESENT on an element E if either:
- A is DIRECTLY PRESENT on E; or
- No annotation of A's type is DIRECTLY PRESENT on E, and E is a class, 
and A's type is inheritable (§9.6.3.3), and A is PRESENT on the 
superclass of E.

The javadoc for getDeclaredAnnotationsByType(Class) can simply say:

"Returns the annotations which are directly or indirectly present on 
this element."

The javadoc for getAnnotationsByType(Class) will have to embody a 
recursive-lookup-with-overriding policy:

"Returns the annotations which are directly or indirectly present on 
this element. If there are none, then if this element is a class, 
returns the annotations of inheritable type which are returned by an 
invocation of getAnnotationsByType(Class) on the superclass of this 
element."

Yuk. This operational description is patterned after (c)'s definition of 
PRESENT, but you'd never guess that. I'm going to bite the bullet and 
introduce a new term:

d) An annotation A is ASSOCIATED with an element E if either:
- A is DIRECTLY OR INDIRECTLY PRESENT on E; or
- No annotation of A's type is DIRECTLY OR INDIRECTLY PRESENT on E, and 
E is a class, and A's type is inheritable (§9.6.3.3), and A is 
ASSOCIATED with the superclass of E.

The similarity of PRESENT and ASSOCIATED is clear. 
getAnnotationsByType(Class) is just:

"Returns the annotations which are associated with this element."

If that sounds OK, I'll modify the spec PDF and file a bug to change the 
core reflection and language model javadocs. No changes should be needed 
in any method implementation.

Alex