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

[Joe Darcy]

On 12/04/2013 11:58 AM, Stuart Marks wrote:
>
>
> On 12/4/13 11:30 AM, Alex Buckley wrote:
>> On 12/3/2013 9:23 PM, Joe Darcy wrote:
>>> + * <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.
>>
>> "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."
>
> Thanks Alex, this addresses the concern I had raised about use of the 
> term "binary compatible."
>
>

Thanks all for the feedback. I revised patch below to address the 
concerns that have been raised. Additionally, I added a "see 
compatibility discussion in AnnotatedElement" note to 
java.lang.annotation.Annotation.

Thanks,

-Joe

diff -r cd4aabc40f72 src/share/classes/java/lang/annotation/Annotation.java
--- a/src/share/classes/java/lang/annotation/Annotation.java    Tue Dec 
03 11:52:18 2013 -0800
+++ b/src/share/classes/java/lang/annotation/Annotation.java    Wed Dec 
04 17:56:47 2013 -0800
@@ -34,6 +34,10 @@
   * More information about annotation types can be found in section 9.6 of
   * <cite>The Java™ Language Specification</cite>.
   *
+ * The {@link java.lang.reflect.AnnotatedElement} interface discusses
+ * compatibility concerns when evolving an annotation type from being
+ * non-repeatable to being repeatable.
+ *
   * @author  Josh Bloch
   * @since   1.5
   */
diff -r cd4aabc40f72 
src/share/classes/java/lang/reflect/AnnotatedElement.java
--- a/src/share/classes/java/lang/reflect/AnnotatedElement.java Tue Dec 
03 11:52:18 2013 -0800
+++ b/src/share/classes/java/lang/reflect/AnnotatedElement.java Wed Dec 
04 17:56:47 2013 -0800
@@ -135,7 +135,78 @@
   * annotations on <i>E</i> are directly present on <i>E</i> in place
   * of their container annotation, in the order in which they appear in
   * the value element of the container annotation.
-
+ *
+ * <p>There are several compatibility concerns to keep in mind if an
+ * annotation type <i>T</i> is originally <em>not</em> repeatable and
+ * later modified to be repeatable.
+ *
+ * The containing annotation type for <i>T</i> is <i>TC</i>.
+ *
+ * <ul>
+ *
+ * <li>Modifying <i>T</i> to be repeatable is source and binary
+ * compatible with existing uses of <i>T</i> and with existing uses
+ * of <i>TC</i>.
+ *
+ * That is, for source compatibility, source code with annotations of
+ * type <i>T</i> or of type <i>TC</i> will still compile. For binary
+ * compatibility, class files with annotations of type <i>T</i> or of
+ * type <i>TC</i> (or with other kinds of uses of type <i>T</i> or of
+ * type <i>TC</i>) will link against the modified version of <i>T</i>
+ * if they linked against the earlier version.
+ *
+ * (An annotation type <i>TC</i> may informally serve as an acting
+ * containing annotation type before <i>T</i> is modified to be
+ * formally repeatable. Alternatively, when <i>T</i> is made
+ * repeatable, <i>TC</i> can be introduced as a new type.)
+ *
+ * <li>If an annotation type <i>TC</i> is present on an element, and
+ * <i>T</i> is modified to be repeatable with <i>TC</i> as its
+ * containing annotation type then:
+ *
+ * <ul>
+ *
+ * <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 will "look through" it to expose
+ * annotations of type <i>T</i>.
+ *
+ * </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.
+ *
+ * <li>The addition of the additional annotations changes the results
+ * of the {@code get[Declared]Annotation(Class<T>)} methods and {@code
+ * get[Declared]Annotations()} methods, because those methods will now
+ * only see a container annotation on the element and not see an
+ * annotation of type <i>T</i>.
+ *
+ * <li>The addition of the additional annotations changes the results
+ * of the {@code get[Declared]AnnotationsByType(Class<T>)} methods,
+ * because their results will expose the additional annotations of
+ * type <i>T</i> whereas previously they exposed only a single
+ * annotation of type <i>T</i>.
+ *
+ * </ul>
+ *
+ * </ul>
+ *
   * <p>If an annotation returned by a method in this interface contains
   * (directly or indirectly) a {@link Class}-valued member referring to
   * a class that is not accessible in this VM, attempting to read the class