JDK 8 RFR for JDK-8023471, , Add compatibility note to AnnotatedElement

[Alex Buckley]

On 12/3/2013 9:23 PM, Joe Darcy wrote:
> + *
> + * <p>There are several compatibility concerns to keep in mind if an
> + * annotation type <i>T</i> is <em>not</em> repeatable in one release
> + * of a library and retrofitted to be repeatable in a subsequent
> + * release.

The term "retrofitted" is linguistically correct but I think it's a bit 
jarring to say something is retrofitted in a _subsequent_ release. Too 
many frames of reference. How about just "modified" to be repeatable?

> + * <ul>
> + *
> + * <li>If an annotation of type <i>T</i> is present on an
> + * element and <i>T</i> is made repeatable and more annotations of
> + * type <i>T</i> are added to the element:
> + *
> + *
> + * <ul>
> + *
> + * <li> The addition of the additional annotations is both source
> + * compatible and binary compatible. That is, the source containing
> + * the element and its annotations will still compile and the class
> + * file resulting from the compilation will continue to link.
> + *
> + * <li>The addition of the additional annotations is <em>not</em>
> + * behaviorally compatible with respect to the {@code
> + * get[Declared]Annotation(Class<T>)} methods and {@code
> + * get[Declared]Annotations()} methods, because those methods will now
> + * only see a container annotations on the element and not see an
> + * annotation of type <i>T</i>.
> + *
> + * </ul>

"The addition of the annotations is both source compatible and binary 
compatible. That is, the _source code_ containing the annotated element 
will still compile, and class files will link against the newly compiled 
class file if they linked against the older class file."

"The addition of the annotations is not behaviorally ... because those 
methods will now return a _container annotation_ /* no plural */ on the 
element rather than an annotation of type T."

What happened to the paragraph about get[Declared]AnnotationsByType ?

> + * <li>If an annotation type <i>TC</i> is present
> + * on an element, then making some other annotation type <i>T</i>
> + * repeatable with <i>TC</i> as its containing annotation type then:

The first "then" should become "and some other annotation type T is made 
repeatable with TC as its containing annotation type, then:"

> + * <ul>
> + *
> + * <li>The change to <i>T</i>is source and binary compatible with
> + * existing uses of annotations of type <i>T</i> as well as
> + * annotations of type <i>TC</i>.

The effect of making T repeatable on existing annotations was covered 
earlier. This paragraph was meant to be about how code which said @TC is 
still compilable and linkable even after TC became someone's containing 
annotation type:

"The change to T is both source compatible and binary compatible for TC. 
That is, source code containing annotations of type TC will still 
compile, and class files will still link against the resulting class file."

> + * <li>The change to <i>T</i> is behaviorally compatible with respect
> + * to the {@code get[Declared]Annotation(Class<T>)} (called with an
> + * argument of <i>T</i> or <i>TC</i>) and {@code
> + * get[Declared]Annotations()} methods because the results of the
> + * methods will not change due to <i>TC</i> becoming the containing
> + * annotation type for <i>T</i>.
> + *
> + * <li>The change to <i>T</i> is <em>not</em> behaviorally compatible
> + * with respect to the {@code
> + * get[Declared]AnnotationsByType(Class<T>)} methods, because those
> + * methods will now recognize an annotation of type <i>TC</i> as a
> + * container annotation and "look through" it to expose annotations of
> + * type <i>T</i>.

Reading this, I would be inclined to swap the major order of the new 
text. First, say what happens when T is made repeatable _before even one 
more @T annotation is written anywhere_. Second, say what happens when 
@T is repeated.

Alex