1 /* 2 * Copyright (C) 2016 The Android Open Source Project 3 * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. 4 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 5 * 6 * This code is free software; you can redistribute it and/or modify it 7 * under the terms of the GNU General Public License version 2 only, as 8 * published by the Free Software Foundation. Oracle designates this 9 * particular file as subject to the "Classpath" exception as provided 10 * by Oracle in the LICENSE file that accompanied this code. 11 * 12 * This code is distributed in the hope that it will be useful, but WITHOUT 13 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 14 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 15 * version 2 for more details (a copy is included in the LICENSE file that 16 * accompanied this code). 17 * 18 * You should have received a copy of the GNU General Public License version 19 * 2 along with this work; if not, write to the Free Software Foundation, 20 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 21 * 22 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 23 * or visit www.oracle.com if you need additional information or have any 24 * questions. 25 */ 26 27 package java.lang.reflect; 28 29 import java.lang.annotation.Annotation; 30 import java.lang.annotation.AnnotationFormatError; 31 import java.util.Objects; 32 import libcore.reflect.AnnotatedElements; 33 34 // Android-changed: Removed some references to bytecode spec below that do not 35 // apply to DEX and added a note about annotation ordering. 36 /** 37 * Represents an annotated element of the program currently running in this 38 * VM. This interface allows annotations to be read reflectively. All 39 * annotations returned by methods in this interface are immutable and 40 * serializable. The arrays returned by methods of this interface may be modified 41 * by callers without affecting the arrays returned to other callers. 42 * 43 * <p>Android note: methods that return multiple annotations of different types such as 44 * {@link #getAnnotations()} and {@link #getDeclaredAnnotations()} can be affected 45 * by the explicit character-code ordering of annotations types specified by the DEX format. 46 * Annotations of different types on a single element are not guaranteed to be returned in the order 47 * they are declared in source. 48 * 49 * <p>The {@link #getAnnotationsByType(Class)} and {@link 50 * #getDeclaredAnnotationsByType(Class)} methods support multiple 51 * annotations of the same type on an element. If the argument to 52 * either method is a repeatable annotation type (JLS 9.6), then the 53 * method will "look through" a container annotation (JLS 9.7), if 54 * present, and return any annotations inside the container. Container 55 * annotations may be generated at compile-time to wrap multiple 56 * annotations of the argument type. 57 * 58 * <p>The terms <em>directly present</em>, <em>indirectly present</em>, 59 * <em>present</em>, and <em>associated</em> are used throughout this 60 * interface to describe precisely which annotations are returned by 61 * methods: 62 * 63 * <ul> 64 * 65 * <li> An annotation <i>A</i> is <em>directly present</em> on an 66 * element <i>E</i> if <i>E</i> is annotated by <i>A</i> in the original source. 67 * 68 * <li>An annotation <i>A</i> is <em>indirectly present</em> on an 69 * element <i>E</i> if <i>E</i> is annotated by a container annotation 70 * of <i>A</i>. 71 * 72 * <li>An annotation <i>A</i> is present on an element <i>E</i> if either: 73 * 74 * <ul> 75 * 76 * <li><i>A</i> is directly present on <i>E</i>; or 77 * 78 * <li>No annotation of <i>A</i> 's type is directly present on 79 * <i>E</i>, and <i>E</i> is a class, and <i>A</i> 's type is 80 * inheritable, and <i>A</i> is present on the superclass of <i>E</i>. 81 * 82 * </ul> 83 * 84 * <li>An annotation <i>A</i> is <em>associated</em> with an element <i>E</i> 85 * if either: 86 * 87 * <ul> 88 * 89 * <li><i>A</i> is directly or indirectly present on <i>E</i>; or 90 * 91 * <li>No annotation of <i>A</i> 's type is directly or indirectly 92 * present on <i>E</i>, and <i>E</i> is a class, and <i>A</i>'s type 93 * is inheritable, and <i>A</i> is associated with the superclass of 94 * <i>E</i>. 95 * 96 * </ul> 97 * 98 * </ul> 99 * 100 * <p>The table below summarizes which kind of annotation presence 101 * different methods in this interface examine. 102 * 103 * <table border> 104 * <caption>Overview of kind of presence detected by different AnnotatedElement methods</caption> 105 * <tr><th colspan=2></th><th colspan=4>Kind of Presence</th> 106 * <tr><th colspan=2>Method</th><th>Directly Present</th><th>Indirectly Present</th><th>Present</th><th>Associated</th> 107 * <tr><td align=right>{@code T}</td><td>{@link #getAnnotation(Class) getAnnotation(Class<T>)} 108 * <td></td><td></td><td>X</td><td></td> 109 * </tr> 110 * <tr><td align=right>{@code Annotation[]}</td><td>{@link #getAnnotations getAnnotations()} 111 * <td></td><td></td><td>X</td><td></td> 112 * </tr> 113 * <tr><td align=right>{@code T[]}</td><td>{@link #getAnnotationsByType(Class) getAnnotationsByType(Class<T>)} 114 * <td></td><td></td><td></td><td>X</td> 115 * </tr> 116 * <tr><td align=right>{@code T}</td><td>{@link #getDeclaredAnnotation(Class) getDeclaredAnnotation(Class<T>)} 117 * <td>X</td><td></td><td></td><td></td> 118 * </tr> 119 * <tr><td align=right>{@code Annotation[]}</td><td>{@link #getDeclaredAnnotations getDeclaredAnnotations()} 120 * <td>X</td><td></td><td></td><td></td> 121 * </tr> 122 * <tr><td align=right>{@code T[]}</td><td>{@link #getDeclaredAnnotationsByType(Class) getDeclaredAnnotationsByType(Class<T>)} 123 * <td>X</td><td>X</td><td></td><td></td> 124 * </tr> 125 * </table> 126 * 127 * <p>For an invocation of {@code get[Declared]AnnotationsByType( Class < 128 * T >)}, the order of annotations which are directly or indirectly 129 * present on an element <i>E</i> is computed as if indirectly present 130 * annotations on <i>E</i> are directly present on <i>E</i> in place 131 * of their container annotation, in the order in which they appear in 132 * the value element of the container annotation. 133 * 134 * <p>There are several compatibility concerns to keep in mind if an 135 * annotation type <i>T</i> is originally <em>not</em> repeatable and 136 * later modified to be repeatable. 137 * 138 * The containing annotation type for <i>T</i> is <i>TC</i>. 139 * 140 * <ul> 141 * 142 * <li>Modifying <i>T</i> to be repeatable is source and binary 143 * compatible with existing uses of <i>T</i> and with existing uses 144 * of <i>TC</i>. 145 * 146 * That is, for source compatibility, source code with annotations of 147 * type <i>T</i> or of type <i>TC</i> will still compile. For binary 148 * compatibility, class files with annotations of type <i>T</i> or of 149 * type <i>TC</i> (or with other kinds of uses of type <i>T</i> or of 150 * type <i>TC</i>) will link against the modified version of <i>T</i> 151 * if they linked against the earlier version. 152 * 153 * (An annotation type <i>TC</i> may informally serve as an acting 154 * containing annotation type before <i>T</i> is modified to be 155 * formally repeatable. Alternatively, when <i>T</i> is made 156 * repeatable, <i>TC</i> can be introduced as a new type.) 157 * 158 * <li>If an annotation type <i>TC</i> is present on an element, and 159 * <i>T</i> is modified to be repeatable with <i>TC</i> as its 160 * containing annotation type then: 161 * 162 * <ul> 163 * 164 * <li>The change to <i>T</i> is behaviorally compatible with respect 165 * to the {@code get[Declared]Annotation(Class<T>)} (called with an 166 * argument of <i>T</i> or <i>TC</i>) and {@code 167 * get[Declared]Annotations()} methods because the results of the 168 * methods will not change due to <i>TC</i> becoming the containing 169 * annotation type for <i>T</i>. 170 * 171 * <li>The change to <i>T</i> changes the results of the {@code 172 * get[Declared]AnnotationsByType(Class<T>)} methods called with an 173 * argument of <i>T</i>, because those methods will now recognize an 174 * annotation of type <i>TC</i> as a container annotation for <i>T</i> 175 * and will "look through" it to expose annotations of type <i>T</i>. 176 * 177 * </ul> 178 * 179 * <li>If an annotation of type <i>T</i> is present on an 180 * element and <i>T</i> is made repeatable and more annotations of 181 * type <i>T</i> are added to the element: 182 * 183 * <ul> 184 * 185 * <li> The addition of the annotations of type <i>T</i> is both 186 * source compatible and binary compatible. 187 * 188 * <li>The addition of the annotations of type <i>T</i> changes the results 189 * of the {@code get[Declared]Annotation(Class<T>)} methods and {@code 190 * get[Declared]Annotations()} methods, because those methods will now 191 * only see a container annotation on the element and not see an 192 * annotation of type <i>T</i>. 193 * 194 * <li>The addition of the annotations of type <i>T</i> changes the 195 * results of the {@code get[Declared]AnnotationsByType(Class<T>)} 196 * methods, because their results will expose the additional 197 * annotations of type <i>T</i> whereas previously they exposed only a 198 * single annotation of type <i>T</i>. 199 * 200 * </ul> 201 * 202 * </ul> 203 * 204 * <p>If an annotation returned by a method in this interface contains 205 * (directly or indirectly) a {@link Class}-valued member referring to 206 * a class that is not accessible in this VM, attempting to read the class 207 * by calling the relevant Class-returning method on the returned annotation 208 * will result in a {@link TypeNotPresentException}. 209 * 210 * <p>Similarly, attempting to read an enum-valued member will result in 211 * a {@link EnumConstantNotPresentException} if the enum constant in the 212 * annotation is no longer present in the enum type. 213 * 214 * <p>If an annotation type <i>T</i> is (meta-)annotated with an 215 * {@code @Repeatable} annotation whose value element indicates a type 216 * <i>TC</i>, but <i>TC</i> does not declare a {@code value()} method 217 * with a return type of <i>T</i>{@code []}, then an exception of type 218 * {@link java.lang.annotation.AnnotationFormatError} is thrown. 219 * 220 * <p>Finally, attempting to read a member whose definition has evolved 221 * incompatibly will result in a {@link 222 * java.lang.annotation.AnnotationTypeMismatchException} or an 223 * {@link java.lang.annotation.IncompleteAnnotationException}. 224 * 225 * @see java.lang.EnumConstantNotPresentException 226 * @see java.lang.TypeNotPresentException 227 * @see AnnotationFormatError 228 * @see java.lang.annotation.AnnotationTypeMismatchException 229 * @see java.lang.annotation.IncompleteAnnotationException 230 * @since 1.5 231 * @author Josh Bloch 232 */ 233 public interface AnnotatedElement { 234 /** 235 * Returns true if an annotation for the specified type 236 * is <em>present</em> on this element, else false. This method 237 * is designed primarily for convenient access to marker annotations. 238 * 239 * <p>The truth value returned by this method is equivalent to: 240 * {@code getAnnotation(annotationClass) != null} 241 * 242 * <p>The body of the default method is specified to be the code 243 * above. 244 * 245 * @param annotationClass the Class object corresponding to the 246 * annotation type 247 * @return true if an annotation for the specified annotation 248 * type is present on this element, else false 249 * @throws NullPointerException if the given annotation class is null 250 * @since 1.5 251 */ isAnnotationPresent(Class<? extends Annotation> annotationClass)252 default boolean isAnnotationPresent(Class<? extends Annotation> annotationClass) { 253 return getAnnotation(annotationClass) != null; 254 } 255 256 /** 257 * Returns this element's annotation for the specified type if 258 * such an annotation is <em>present</em>, else null. 259 * 260 * @param <T> the type of the annotation to query for and return if present 261 * @param annotationClass the Class object corresponding to the 262 * annotation type 263 * @return this element's annotation for the specified annotation type if 264 * present on this element, else null 265 * @throws NullPointerException if the given annotation class is null 266 * @since 1.5 267 */ getAnnotation(Class<T> annotationClass)268 <T extends Annotation> T getAnnotation(Class<T> annotationClass); 269 270 /** 271 * Returns annotations that are <em>present</em> on this element. 272 * 273 * If there are no annotations <em>present</em> on this element, the return 274 * value is an array of length 0. 275 * 276 * The caller of this method is free to modify the returned array; it will 277 * have no effect on the arrays returned to other callers. 278 * 279 * @return annotations present on this element 280 * @since 1.5 281 */ getAnnotations()282 Annotation[] getAnnotations(); 283 284 /** 285 * Returns annotations that are <em>associated</em> with this element. 286 * 287 * If there are no annotations <em>associated</em> with this element, the return 288 * value is an array of length 0. 289 * 290 * The difference between this method and {@link #getAnnotation(Class)} 291 * is that this method detects if its argument is a <em>repeatable 292 * annotation type</em> (JLS 9.6), and if so, attempts to find one or 293 * more annotations of that type by "looking through" a container 294 * annotation. 295 * 296 * The caller of this method is free to modify the returned array; it will 297 * have no effect on the arrays returned to other callers. 298 * 299 * @implSpec The default implementation first calls {@link 300 * #getDeclaredAnnotationsByType(Class)} passing {@code 301 * annotationClass} as the argument. If the returned array has 302 * length greater than zero, the array is returned. If the returned 303 * array is zero-length and this {@code AnnotatedElement} is a 304 * class and the argument type is an inheritable annotation type, 305 * and the superclass of this {@code AnnotatedElement} is non-null, 306 * then the returned result is the result of calling {@link 307 * #getAnnotationsByType(Class)} on the superclass with {@code 308 * annotationClass} as the argument. Otherwise, a zero-length 309 * array is returned. 310 * 311 * @param <T> the type of the annotation to query for and return if present 312 * @param annotationClass the Class object corresponding to the 313 * annotation type 314 * @return all this element's annotations for the specified annotation type if 315 * associated with this element, else an array of length zero 316 * @throws NullPointerException if the given annotation class is null 317 * @since 1.8 318 */ getAnnotationsByType(Class<T> annotationClass)319 default <T extends Annotation> T[] getAnnotationsByType(Class<T> annotationClass) { 320 // Android-changed: Altered method implementation for getAnnotationsByType(Class). 321 // Android's annotation code is customized because of the use of the DEX format on Android 322 // and code sharing with the runtime. 323 // This method does not handle inherited annotations and is intended for use for 324 // {@code Method}, {@code Field}, {@code Package}. The {@link Class#getAnnotationsByType} 325 // is implemented explicitly. Therefore this implementation does not fulfill the documented 326 // default implementation for {@link AnnotatedElement#getAnnotationsByType(Class)} but in an 327 // undetectable way because Class is final. 328 return AnnotatedElements.getDirectOrIndirectAnnotationsByType(this, annotationClass); 329 } 330 331 /** 332 * Returns this element's annotation for the specified type if 333 * such an annotation is <em>directly present</em>, else null. 334 * 335 * This method ignores inherited annotations. (Returns null if no 336 * annotations are directly present on this element.) 337 * 338 * @implSpec The default implementation first performs a null check 339 * and then loops over the results of {@link 340 * #getDeclaredAnnotations} returning the first annotation whose 341 * annotation type matches the argument type. 342 * 343 * @param <T> the type of the annotation to query for and return if directly present 344 * @param annotationClass the Class object corresponding to the 345 * annotation type 346 * @return this element's annotation for the specified annotation type if 347 * directly present on this element, else null 348 * @throws NullPointerException if the given annotation class is null 349 * @since 1.8 350 */ getDeclaredAnnotation(Class<T> annotationClass)351 default <T extends Annotation> T getDeclaredAnnotation(Class<T> annotationClass) { 352 Objects.requireNonNull(annotationClass); 353 // Loop over all directly-present annotations looking for a matching one 354 for (Annotation annotation : getDeclaredAnnotations()) { 355 if (annotationClass.equals(annotation.annotationType())) { 356 // More robust to do a dynamic cast at runtime instead 357 // of compile-time only. 358 return annotationClass.cast(annotation); 359 } 360 } 361 return null; 362 } 363 364 /** 365 * Returns this element's annotation(s) for the specified type if 366 * such annotations are either <em>directly present</em> or 367 * <em>indirectly present</em>. This method ignores inherited 368 * annotations. 369 * 370 * If there are no specified annotations directly or indirectly 371 * present on this element, the return value is an array of length 372 * 0. 373 * 374 * The difference between this method and {@link 375 * #getDeclaredAnnotation(Class)} is that this method detects if its 376 * argument is a <em>repeatable annotation type</em> (JLS 9.6), and if so, 377 * attempts to find one or more annotations of that type by "looking 378 * through" a container annotation if one is present. 379 * 380 * The caller of this method is free to modify the returned array; it will 381 * have no effect on the arrays returned to other callers. 382 * 383 * @implSpec The default implementation may call {@link 384 * #getDeclaredAnnotation(Class)} one or more times to find a 385 * directly present annotation and, if the annotation type is 386 * repeatable, to find a container annotation. If annotations of 387 * the annotation type {@code annotationClass} are found to be both 388 * directly and indirectly present, then {@link 389 * #getDeclaredAnnotations()} will get called to determine the 390 * order of the elements in the returned array. 391 * 392 * <p>Alternatively, the default implementation may call {@link 393 * #getDeclaredAnnotations()} a single time and the returned array 394 * examined for both directly and indirectly present 395 * annotations. The results of calling {@link 396 * #getDeclaredAnnotations()} are assumed to be consistent with the 397 * results of calling {@link #getDeclaredAnnotation(Class)}. 398 * 399 * @param <T> the type of the annotation to query for and return 400 * if directly or indirectly present 401 * @param annotationClass the Class object corresponding to the 402 * annotation type 403 * @return all this element's annotations for the specified annotation type if 404 * directly or indirectly present on this element, else an array of length zero 405 * @throws NullPointerException if the given annotation class is null 406 * @since 1.8 407 */ getDeclaredAnnotationsByType(Class<T> annotationClass)408 default <T extends Annotation> T[] getDeclaredAnnotationsByType(Class<T> annotationClass) { 409 // Android-changed: Altered method implementation for getAnnotationsByType(Class). 410 // Android's annotation code is customized because of the use of the DEX format on Android 411 // and code sharing with the runtime. 412 return AnnotatedElements.getDirectOrIndirectAnnotationsByType(this, annotationClass); 413 } 414 415 /** 416 * Returns annotations that are <em>directly present</em> on this element. 417 * This method ignores inherited annotations. 418 * 419 * If there are no annotations <em>directly present</em> on this element, 420 * the return value is an array of length 0. 421 * 422 * The caller of this method is free to modify the returned array; it will 423 * have no effect on the arrays returned to other callers. 424 * 425 * @return annotations directly present on this element 426 * @since 1.5 427 */ getDeclaredAnnotations()428 Annotation[] getDeclaredAnnotations(); 429 } 430