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
