118 * <tr><td align=right>{@code T[]}</td><td>{@link #getAnnotationsByType(Class) getAnnotationsByType(Class<T>)}
119 * <td></td><td></td><td></td><td>X</td>
120 * </tr>
121 * <tr><td align=right>{@code T}</td><td>{@link #getDeclaredAnnotation(Class) getDeclaredAnnotation(Class<T>)}
122 * <td>X</td><td></td><td></td><td></td>
123 * </tr>
124 * <tr><td align=right>{@code Annotation[]}</td><td>{@link #getDeclaredAnnotations getDeclaredAnnotations()}
125 * <td>X</td><td></td><td></td><td></td>
126 * </tr>
127 * <tr><td align=right>{@code T[]}</td><td>{@link #getDeclaredAnnotationsByType(Class) getDeclaredAnnotationsByType(Class<T>)}
128 * <td>X</td><td>X</td><td></td><td></td>
129 * </tr>
130 * </table>
131 *
132 * <p>For an invocation of {@code get[Declared]AnnotationsByType( Class <
133 * T >)}, the order of annotations which are directly or indirectly
134 * present on an element <i>E</i> is computed as if indirectly present
135 * annotations on <i>E</i> are directly present on <i>E</i> in place
136 * of their container annotation, in the order in which they appear in
137 * the value element of the container annotation.
138
139 * <p>If an annotation returned by a method in this interface contains
140 * (directly or indirectly) a {@link Class}-valued member referring to
141 * a class that is not accessible in this VM, attempting to read the class
142 * by calling the relevant Class-returning method on the returned annotation
143 * will result in a {@link TypeNotPresentException}.
144 *
145 * <p>Similarly, attempting to read an enum-valued member will result in
146 * a {@link EnumConstantNotPresentException} if the enum constant in the
147 * annotation is no longer present in the enum type.
148 *
149 * <p>If an annotation type <i>T</i> is (meta-)annotated with an
150 * {@code @Repeatable} annotation whose value element indicates a type
151 * <i>TC</i>, but <i>TC</i> does not declare a {@code value()} method
152 * with a return type of <i>T</i>{@code []}, then an exception of type
153 * {@link java.lang.annotation.AnnotationFormatError} is thrown.
154 *
155 * <p>Finally, attempting to read a member whose definition has evolved
156 * incompatibly will result in a {@link
157 * java.lang.annotation.AnnotationTypeMismatchException} or an
158 * {@link java.lang.annotation.IncompleteAnnotationException}.
|
118 * <tr><td align=right>{@code T[]}</td><td>{@link #getAnnotationsByType(Class) getAnnotationsByType(Class<T>)}
119 * <td></td><td></td><td></td><td>X</td>
120 * </tr>
121 * <tr><td align=right>{@code T}</td><td>{@link #getDeclaredAnnotation(Class) getDeclaredAnnotation(Class<T>)}
122 * <td>X</td><td></td><td></td><td></td>
123 * </tr>
124 * <tr><td align=right>{@code Annotation[]}</td><td>{@link #getDeclaredAnnotations getDeclaredAnnotations()}
125 * <td>X</td><td></td><td></td><td></td>
126 * </tr>
127 * <tr><td align=right>{@code T[]}</td><td>{@link #getDeclaredAnnotationsByType(Class) getDeclaredAnnotationsByType(Class<T>)}
128 * <td>X</td><td>X</td><td></td><td></td>
129 * </tr>
130 * </table>
131 *
132 * <p>For an invocation of {@code get[Declared]AnnotationsByType( Class <
133 * T >)}, the order of annotations which are directly or indirectly
134 * present on an element <i>E</i> is computed as if indirectly present
135 * annotations on <i>E</i> are directly present on <i>E</i> in place
136 * of their container annotation, in the order in which they appear in
137 * the value element of the container annotation.
138 *
139 * <p>There are several compatibility concerns to keep in mind if an
140 * annotation type <i>T</i> is originally <em>not</em> repeatable and
141 * later modified to be repeatable.
142 *
143 * The containing annotation type for <i>T</i> is <i>TC</i>.
144 *
145 * <ul>
146 *
147 * <li>Modifying <i>T</i> to be repeatable is source and binary
148 * compatible with existing uses of <i>T</i> and with existing uses
149 * of <i>TC</i>.
150 *
151 * That is, for source compatibility, source code with annotations of
152 * type <i>T</i> or of type <i>TC</i> will still compile. For binary
153 * compatibility, class files with annotations of type <i>T</i> or of
154 * type <i>TC</i> (or with other kinds of uses of type <i>T</i> or of
155 * type <i>TC</i>) will link against the modified version of <i>T</i>
156 * if they linked against the earlier version.
157 *
158 * (An annotation type <i>TC</i> may informally serve as an acting
159 * containing annotation type before <i>T</i> is modified to be
160 * formally repeatable. Alternatively, when <i>T</i> is made
161 * repeatable, <i>TC</i> can be introduced as a new type.)
162 *
163 * <li>If an annotation type <i>TC</i> is present on an element, and
164 * <i>T</i> is modified to be repeatable with <i>TC</i> as its
165 * containing annotation type then:
166 *
167 * <ul>
168 *
169 * <li>The change to <i>T</i> is behaviorally compatible with respect
170 * to the {@code get[Declared]Annotation(Class<T>)} (called with an
171 * argument of <i>T</i> or <i>TC</i>) and {@code
172 * get[Declared]Annotations()} methods because the results of the
173 * methods will not change due to <i>TC</i> becoming the containing
174 * annotation type for <i>T</i>.
175 *
176 * <li>The change to <i>T</i> is <em>not</em> behaviorally compatible
177 * with respect to the {@code
178 * get[Declared]AnnotationsByType(Class<T>)} methods, because those
179 * methods will now recognize an annotation of type <i>TC</i> as a
180 * container annotation and will "look through" it to expose
181 * annotations of type <i>T</i>.
182 *
183 * </ul>
184 *
185 * <li>If an annotation of type <i>T</i> is present on an
186 * element and <i>T</i> is made repeatable and more annotations of
187 * type <i>T</i> are added to the element:
188 *
189 * <ul>
190 *
191 * <li> The addition of the additional annotations is both source
192 * compatible and binary compatible.
193 *
194 * <li>The addition of the additional annotations changes the results
195 * of the {@code get[Declared]Annotation(Class<T>)} methods and {@code
196 * get[Declared]Annotations()} methods, because those methods will now
197 * only see a container annotation on the element and not see an
198 * annotation of type <i>T</i>.
199 *
200 * <li>The addition of the additional annotations changes the results
201 * of the {@code get[Declared]AnnotationsByType(Class<T>)} methods,
202 * because their results will expose the additional annotations of
203 * type <i>T</i> whereas previously they exposed only a single
204 * annotation of type <i>T</i>.
205 *
206 * </ul>
207 *
208 * </ul>
209 *
210 * <p>If an annotation returned by a method in this interface contains
211 * (directly or indirectly) a {@link Class}-valued member referring to
212 * a class that is not accessible in this VM, attempting to read the class
213 * by calling the relevant Class-returning method on the returned annotation
214 * will result in a {@link TypeNotPresentException}.
215 *
216 * <p>Similarly, attempting to read an enum-valued member will result in
217 * a {@link EnumConstantNotPresentException} if the enum constant in the
218 * annotation is no longer present in the enum type.
219 *
220 * <p>If an annotation type <i>T</i> is (meta-)annotated with an
221 * {@code @Repeatable} annotation whose value element indicates a type
222 * <i>TC</i>, but <i>TC</i> does not declare a {@code value()} method
223 * with a return type of <i>T</i>{@code []}, then an exception of type
224 * {@link java.lang.annotation.AnnotationFormatError} is thrown.
225 *
226 * <p>Finally, attempting to read a member whose definition has evolved
227 * incompatibly will result in a {@link
228 * java.lang.annotation.AnnotationTypeMismatchException} or an
229 * {@link java.lang.annotation.IncompleteAnnotationException}.
|