Suggestion for additional discussion of annotation evolution vis a vis repeatability in JLS 13.5.7

[Alex Buckley]

On 8/30/2012 5:09 PM, Joseph Darcy wrote:
> Chapter 13 of the JLS discusses binary compatibility and 13.5.7
> discussions some considerations specific to annotation types.
>
> I think it would be appropriate and helpful for this discussion to
> include repeatability of annotation types, binary compatibility is not
> changed, source and behavioral might be, etc.

I'll add the act of making an annotation type repeatable to 13.5.7 as an 
_example_ of a change to an annotation type. However, ch.13 does not 
traditionally describe source or behavioral compatibility. Behavioral 
compatibility in this case means "the behavior of a reflective API", so 
the proper place to document it is in the API spec.

Joel, can the following text go in the type-level javadoc of 
AnnotatedElement as something to be going on with:

--
If an annotation of type T is present on an element, and T is made 
repeatable, then adding more annotations of type T to the element is 
source compatible and binary compatible.

It is not behaviorally compatible for the 
get[Declared]Annotation(Class<T>) methods and get[Declared]Annotations() 
methods, because they will now see only a container annotation on the 
element rather than any annotation of type T.

It is not behaviorally compatible for the 
get[Declared]AnnotationsByType(Class<T>) methods, because their results 
will expose the additional annotations of type T whereas previously they 
exposed only a single annotation of type T.

If an annotation of type TC is present on an element, then making
some other annotation type T repeatable (with TC as its containing 
annotation type) is source compatible and binary compatible.

It is behaviorally compatible for the get[Declared]Annotation(Class<T>) 
methods and get[Declared]Annotations() methods, in that their results 
will not change just because TC is a containing annotation type.

However, it is not behaviorally compatible for the 
get[Declared]AnnotationsByType(Class<T>) methods, because they will now 
recognize an annotation of type TC as a container annotation and "look 
through" it to expose annotations of type T.
--

Alex