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 class="plain"> 104 * <caption>Overview of kind of presence detected by different AnnotatedElement methods</caption> 105 * <thead> 106 * <tr><th colspan=2 scope="col">Method</th> 107 * <th colspan=4 scope="col">Kind of Presence</th> 108 * <tr><th scope="col">Return Type</th> 109 * <th scope="col">Signature</th> 110 * <th scope="col">Directly Present</th> 111 * <th scope="col">Indirectly Present</th> 112 * <th scope="col">Present</th> 113 * <th scope="col">Associated</th> 114 * </thead> 115 * <tbody> 116 * <tr><td style="text-align:right">{@code T}</td> 117 * <th scope="row" style="font-weight:normal; text-align:left">{@link #getAnnotation(Class) getAnnotation(Class<T>)} 118 * <td></td><td></td><td style="text-align:center">X</td><td></td> 119 * </tr> 120 * <tr><td style="text-align:right">{@code Annotation[]}</td> 121 * <th scope="row" style="font-weight:normal; text-align:left">{@link #getAnnotations getAnnotations()} 122 * <td></td><td></td><td style="text-align:center">X</td><td></td> 123 * </tr> 124 * <tr><td style="text-align:right">{@code T[]}</td> 125 * <th scope="row" style="font-weight:normal; text-align:left">{@link #getAnnotationsByType(Class) getAnnotationsByType(Class<T>)} 126 * <td></td><td></td><td></td><td style="text-align:center">X</td> 127 * </tr> 128 * <tr><td style="text-align:right">{@code T}</td> 129 * <th scope="row" style="font-weight:normal; text-align:left">{@link #getDeclaredAnnotation(Class) getDeclaredAnnotation(Class<T>)} 130 * <td style="text-align:center">X</td><td></td><td></td><td></td> 131 * </tr> 132 * <tr><td style="text-align:right">{@code Annotation[]}</td> 133 * <th scope="row" style="font-weight:normal; text-align:left">{@link #getDeclaredAnnotations getDeclaredAnnotations()} 134 * <td style="text-align:center">X</td><td></td><td></td><td></td> 135 * </tr> 136 * <tr><td style="text-align:right">{@code T[]}</td> 137 * <th scope="row" style="font-weight:normal; text-align:left">{@link #getDeclaredAnnotationsByType(Class) getDeclaredAnnotationsByType(Class<T>)} 138 * <td style="text-align:center">X</td><td style="text-align:center">X</td><td></td><td></td> 139 * </tr> 140 * </tbody> 141 * </table> 142 * 143 * <p>For an invocation of {@code get[Declared]AnnotationsByType( Class < 144 * T >)}, the order of annotations which are directly or indirectly 145 * present on an element <i>E</i> is computed as if indirectly present 146 * annotations on <i>E</i> are directly present on <i>E</i> in place 147 * of their container annotation, in the order in which they appear in 148 * the value element of the container annotation. 149 * 150 * <p>There are several compatibility concerns to keep in mind if an 151 * annotation type <i>T</i> is originally <em>not</em> repeatable and 152 * later modified to be repeatable. 153 * 154 * The containing annotation type for <i>T</i> is <i>TC</i>. 155 * 156 * <ul> 157 * 158 * <li>Modifying <i>T</i> to be repeatable is source and binary 159 * compatible with existing uses of <i>T</i> and with existing uses 160 * of <i>TC</i>. 161 * 162 * That is, for source compatibility, source code with annotations of 163 * type <i>T</i> or of type <i>TC</i> will still compile. For binary 164 * compatibility, class files with annotations of type <i>T</i> or of 165 * type <i>TC</i> (or with other kinds of uses of type <i>T</i> or of 166 * type <i>TC</i>) will link against the modified version of <i>T</i> 167 * if they linked against the earlier version. 168 * 169 * (An annotation type <i>TC</i> may informally serve as an acting 170 * containing annotation type before <i>T</i> is modified to be 171 * formally repeatable. Alternatively, when <i>T</i> is made 172 * repeatable, <i>TC</i> can be introduced as a new type.) 173 * 174 * <li>If an annotation type <i>TC</i> is present on an element, and 175 * <i>T</i> is modified to be repeatable with <i>TC</i> as its 176 * containing annotation type then: 177 * 178 * <ul> 179 * 180 * <li>The change to <i>T</i> is behaviorally compatible with respect 181 * to the {@code get[Declared]Annotation(Class<T>)} (called with an 182 * argument of <i>T</i> or <i>TC</i>) and {@code 183 * get[Declared]Annotations()} methods because the results of the 184 * methods will not change due to <i>TC</i> becoming the containing 185 * annotation type for <i>T</i>. 186 * 187 * <li>The change to <i>T</i> changes the results of the {@code 188 * get[Declared]AnnotationsByType(Class<T>)} methods called with an 189 * argument of <i>T</i>, because those methods will now recognize an 190 * annotation of type <i>TC</i> as a container annotation for <i>T</i> 191 * and will "look through" it to expose annotations of type <i>T</i>. 192 * 193 * </ul> 194 * 195 * <li>If an annotation of type <i>T</i> is present on an 196 * element and <i>T</i> is made repeatable and more annotations of 197 * type <i>T</i> are added to the element: 198 * 199 * <ul> 200 * 201 * <li> The addition of the annotations of type <i>T</i> is both 202 * source compatible and binary compatible. 203 * 204 * <li>The addition of the annotations of type <i>T</i> changes the results 205 * of the {@code get[Declared]Annotation(Class<T>)} methods and {@code 206 * get[Declared]Annotations()} methods, because those methods will now 207 * only see a container annotation on the element and not see an 208 * annotation of type <i>T</i>. 209 * 210 * <li>The addition of the annotations of type <i>T</i> changes the 211 * results of the {@code get[Declared]AnnotationsByType(Class<T>)} 212 * methods, because their results will expose the additional 213 * annotations of type <i>T</i> whereas previously they exposed only a 214 * single annotation of type <i>T</i>. 215 * 216 * </ul> 217 * 218 * </ul> 219 * 220 * <p>If an annotation returned by a method in this interface contains 221 * (directly or indirectly) a {@link Class}-valued member referring to 222 * a class that is not accessible in this VM, attempting to read the class 223 * by calling the relevant Class-returning method on the returned annotation 224 * will result in a {@link TypeNotPresentException}. 225 * 226 * <p>Similarly, attempting to read an enum-valued member will result in 227 * a {@link EnumConstantNotPresentException} if the enum constant in the 228 * annotation is no longer present in the enum type. 229 * 230 * <p>If an annotation type <i>T</i> is (meta-)annotated with an 231 * {@code @Repeatable} annotation whose value element indicates a type 232 * <i>TC</i>, but <i>TC</i> does not declare a {@code value()} method 233 * with a return type of <i>T</i>{@code []}, then an exception of type 234 * {@link java.lang.annotation.AnnotationFormatError} is thrown. 235 * 236 * <p>Finally, attempting to read a member whose definition has evolved 237 * incompatibly will result in a {@link 238 * java.lang.annotation.AnnotationTypeMismatchException} or an 239 * {@link java.lang.annotation.IncompleteAnnotationException}. 240 * 241 * @see java.lang.EnumConstantNotPresentException 242 * @see java.lang.TypeNotPresentException 243 * @see AnnotationFormatError 244 * @see java.lang.annotation.AnnotationTypeMismatchException 245 * @see java.lang.annotation.IncompleteAnnotationException 246 * @since 1.5 247 * @author Josh Bloch 248 */ 249 public interface AnnotatedElement { 250 /** 251 * Returns true if an annotation for the specified type 252 * is <em>present</em> on this element, else false. This method 253 * is designed primarily for convenient access to marker annotations. 254 * 255 * <p>The truth value returned by this method is equivalent to: 256 * {@code getAnnotation(annotationClass) != null} 257 * 258 * <p>The body of the default method is specified to be the code 259 * above. 260 * 261 * @param annotationClass the Class object corresponding to the 262 * annotation type 263 * @return true if an annotation for the specified annotation 264 * type is present on this element, else false 265 * @throws NullPointerException if the given annotation class is null 266 * @since 1.5 267 */ isAnnotationPresent(Class<? extends Annotation> annotationClass)268 default boolean isAnnotationPresent(Class<? extends Annotation> annotationClass) { 269 return getAnnotation(annotationClass) != null; 270 } 271 272 /** 273 * Returns this element's annotation for the specified type if 274 * such an annotation is <em>present</em>, else null. 275 * 276 * @param <T> the type of the annotation to query for and return if present 277 * @param annotationClass the Class object corresponding to the 278 * annotation type 279 * @return this element's annotation for the specified annotation type if 280 * present on this element, else null 281 * @throws NullPointerException if the given annotation class is null 282 * @since 1.5 283 */ getAnnotation(Class<T> annotationClass)284 <T extends Annotation> T getAnnotation(Class<T> annotationClass); 285 286 /** 287 * Returns annotations that are <em>present</em> on this element. 288 * 289 * If there are no annotations <em>present</em> on this element, the return 290 * value is an array of length 0. 291 * 292 * The caller of this method is free to modify the returned array; it will 293 * have no effect on the arrays returned to other callers. 294 * 295 * @return annotations present on this element 296 * @since 1.5 297 */ getAnnotations()298 Annotation[] getAnnotations(); 299 300 /** 301 * Returns annotations that are <em>associated</em> with this element. 302 * 303 * If there are no annotations <em>associated</em> with this element, the return 304 * value is an array of length 0. 305 * 306 * The difference between this method and {@link #getAnnotation(Class)} 307 * is that this method detects if its argument is a <em>repeatable 308 * annotation type</em> (JLS 9.6), and if so, attempts to find one or 309 * more annotations of that type by "looking through" a container 310 * annotation. 311 * 312 * The caller of this method is free to modify the returned array; it will 313 * have no effect on the arrays returned to other callers. 314 * 315 * @implSpec The default implementation first calls {@link 316 * #getDeclaredAnnotationsByType(Class)} passing {@code 317 * annotationClass} as the argument. If the returned array has 318 * length greater than zero, the array is returned. If the returned 319 * array is zero-length and this {@code AnnotatedElement} is a 320 * class and the argument type is an inheritable annotation type, 321 * and the superclass of this {@code AnnotatedElement} is non-null, 322 * then the returned result is the result of calling {@link 323 * #getAnnotationsByType(Class)} on the superclass with {@code 324 * annotationClass} as the argument. Otherwise, a zero-length 325 * array is returned. 326 * 327 * @param <T> the type of the annotation to query for and return if present 328 * @param annotationClass the Class object corresponding to the 329 * annotation type 330 * @return all this element's annotations for the specified annotation type if 331 * associated with this element, else an array of length zero 332 * @throws NullPointerException if the given annotation class is null 333 * @since 1.8 334 */ getAnnotationsByType(Class<T> annotationClass)335 default <T extends Annotation> T[] getAnnotationsByType(Class<T> annotationClass) { 336 // Android-changed: Altered method implementation for getAnnotationsByType(Class). 337 // Android's annotation code is customized because of the use of the DEX format on Android 338 // and code sharing with the runtime. 339 // This method does not handle inherited annotations and is intended for use for 340 // {@code Method}, {@code Field}, {@code Package}. The {@link Class#getAnnotationsByType} 341 // is implemented explicitly. Therefore this implementation does not fulfill the documented 342 // default implementation for {@link AnnotatedElement#getAnnotationsByType(Class)} but in an 343 // undetectable way because Class is final. 344 return AnnotatedElements.getDirectOrIndirectAnnotationsByType(this, annotationClass); 345 } 346 347 /** 348 * Returns this element's annotation for the specified type if 349 * such an annotation is <em>directly present</em>, else null. 350 * 351 * This method ignores inherited annotations. (Returns null if no 352 * annotations are directly present on this element.) 353 * 354 * @implSpec The default implementation first performs a null check 355 * and then loops over the results of {@link 356 * #getDeclaredAnnotations} returning the first annotation whose 357 * annotation type matches the argument type. 358 * 359 * @param <T> the type of the annotation to query for and return if directly present 360 * @param annotationClass the Class object corresponding to the 361 * annotation type 362 * @return this element's annotation for the specified annotation type if 363 * directly present on this element, else null 364 * @throws NullPointerException if the given annotation class is null 365 * @since 1.8 366 */ getDeclaredAnnotation(Class<T> annotationClass)367 default <T extends Annotation> T getDeclaredAnnotation(Class<T> annotationClass) { 368 Objects.requireNonNull(annotationClass); 369 // Loop over all directly-present annotations looking for a matching one 370 for (Annotation annotation : getDeclaredAnnotations()) { 371 if (annotationClass.equals(annotation.annotationType())) { 372 // More robust to do a dynamic cast at runtime instead 373 // of compile-time only. 374 return annotationClass.cast(annotation); 375 } 376 } 377 return null; 378 } 379 380 /** 381 * Returns this element's annotation(s) for the specified type if 382 * such annotations are either <em>directly present</em> or 383 * <em>indirectly present</em>. This method ignores inherited 384 * annotations. 385 * 386 * If there are no specified annotations directly or indirectly 387 * present on this element, the return value is an array of length 388 * 0. 389 * 390 * The difference between this method and {@link 391 * #getDeclaredAnnotation(Class)} is that this method detects if its 392 * argument is a <em>repeatable annotation type</em> (JLS 9.6), and if so, 393 * attempts to find one or more annotations of that type by "looking 394 * through" a container annotation if one is present. 395 * 396 * The caller of this method is free to modify the returned array; it will 397 * have no effect on the arrays returned to other callers. 398 * 399 * @implSpec The default implementation may call {@link 400 * #getDeclaredAnnotation(Class)} one or more times to find a 401 * directly present annotation and, if the annotation type is 402 * repeatable, to find a container annotation. If annotations of 403 * the annotation type {@code annotationClass} are found to be both 404 * directly and indirectly present, then {@link 405 * #getDeclaredAnnotations()} will get called to determine the 406 * order of the elements in the returned array. 407 * 408 * <p>Alternatively, the default implementation may call {@link 409 * #getDeclaredAnnotations()} a single time and the returned array 410 * examined for both directly and indirectly present 411 * annotations. The results of calling {@link 412 * #getDeclaredAnnotations()} are assumed to be consistent with the 413 * results of calling {@link #getDeclaredAnnotation(Class)}. 414 * 415 * @param <T> the type of the annotation to query for and return 416 * if directly or indirectly present 417 * @param annotationClass the Class object corresponding to the 418 * annotation type 419 * @return all this element's annotations for the specified annotation type if 420 * directly or indirectly present on this element, else an array of length zero 421 * @throws NullPointerException if the given annotation class is null 422 * @since 1.8 423 */ getDeclaredAnnotationsByType(Class<T> annotationClass)424 default <T extends Annotation> T[] getDeclaredAnnotationsByType(Class<T> annotationClass) { 425 // Android-changed: Altered method implementation for getAnnotationsByType(Class). 426 // Android's annotation code is customized because of the use of the DEX format on Android 427 // and code sharing with the runtime. 428 return AnnotatedElements.getDirectOrIndirectAnnotationsByType(this, annotationClass); 429 } 430 431 /** 432 * Returns annotations that are <em>directly present</em> on this element. 433 * This method ignores inherited annotations. 434 * 435 * If there are no annotations <em>directly present</em> on this element, 436 * the return value is an array of length 0. 437 * 438 * The caller of this method is free to modify the returned array; it will 439 * have no effect on the arrays returned to other callers. 440 * 441 * @return annotations directly present on this element 442 * @since 1.5 443 */ getDeclaredAnnotations()444 Annotation[] getDeclaredAnnotations(); 445 } 446