Suggestion for additional discussion of annotation evolution vis a vis repeatability in JLS 13.5.7 (original) (raw)

Alex Buckley alex.buckley at oracle.com
Thu Jan 31 16:59:44 PST 2013

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) 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) 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) 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) 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

More information about the enhanced-metadata-spec-discuss mailing list