1 /* 2 * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.lang.reflect; 27 28 import java.lang.annotation.Annotation; 29 import java.lang.annotation.AnnotationFormatError; 30 import java.lang.annotation.Repeatable; 31 import java.util.Objects; 32 import sun.reflect.annotation.AnnotationSupport; 33 import sun.reflect.annotation.AnnotationType; 34 35 /** 36 * Represents an annotated element of the program currently running in this 37 * VM. This interface allows annotations to be read reflectively. All 38 * annotations returned by methods in this interface are immutable and 39 * serializable. The arrays returned by methods of this interface may be modified 40 * by callers without affecting the arrays returned to other callers. 41 * 42 * <p>The {@link #getAnnotationsByType(Class)} and {@link 43 * #getDeclaredAnnotationsByType(Class)} methods support multiple 44 * annotations of the same type on an element. If the argument to 45 * either method is a repeatable annotation type (JLS 9.6), then the 46 * method will "look through" a container annotation (JLS 9.7), if 47 * present, and return any annotations inside the container. Container 48 * annotations may be generated at compile-time to wrap multiple 49 * annotations of the argument type. 50 * 51 * <p>The terms <em>directly present</em>, <em>indirectly present</em>, 52 * <em>present</em>, and <em>associated</em> are used throughout this 53 * interface to describe precisely which annotations are returned by 54 * methods: 55 * 56 * <ul> 57 * 58 * <li> An annotation <i>A</i> is <em>directly present</em> on an 59 * element <i>E</i> if <i>E</i> has a {@code 60 * RuntimeVisibleAnnotations} or {@code 61 * RuntimeVisibleParameterAnnotations} or {@code 62 * RuntimeVisibleTypeAnnotations} attribute, and the attribute 63 * contains <i>A</i>. 64 * 65 * <li>An annotation <i>A</i> is <em>indirectly present</em> on an 66 * element <i>E</i> if <i>E</i> has a {@code RuntimeVisibleAnnotations} or 67 * {@code RuntimeVisibleParameterAnnotations} or {@code RuntimeVisibleTypeAnnotations} 68 * attribute, and <i>A</i> 's type is repeatable, and the attribute contains 69 * exactly one annotation whose value element contains <i>A</i> and whose 70 * type is the containing annotation type of <i>A</i> 's type. 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>If an annotation returned by a method in this interface contains 135 * (directly or indirectly) a {@link Class}-valued member referring to 136 * a class that is not accessible in this VM, attempting to read the class 137 * by calling the relevant Class-returning method on the returned annotation 138 * will result in a {@link TypeNotPresentException}. 139 * 140 * <p>Similarly, attempting to read an enum-valued member will result in 141 * a {@link EnumConstantNotPresentException} if the enum constant in the 142 * annotation is no longer present in the enum type. 143 * 144 * <p>If an annotation type <i>T</i> is (meta-)annotated with an 145 * {@code @Repeatable} annotation whose value element indicates a type 146 * <i>TC</i>, but <i>TC</i> does not declare a {@code value()} method 147 * with a return type of <i>T</i>{@code []}, then an exception of type 148 * {@link java.lang.annotation.AnnotationFormatError} is thrown. 149 * 150 * <p>Finally, attempting to read a member whose definition has evolved 151 * incompatibly will result in a {@link 152 * java.lang.annotation.AnnotationTypeMismatchException} or an 153 * {@link java.lang.annotation.IncompleteAnnotationException}. 154 * 155 * @see java.lang.EnumConstantNotPresentException 156 * @see java.lang.TypeNotPresentException 157 * @see AnnotationFormatError 158 * @see java.lang.annotation.AnnotationTypeMismatchException 159 * @see java.lang.annotation.IncompleteAnnotationException 160 * @since 1.5 161 * @author Josh Bloch 162 */ 163 public interface AnnotatedElement { 164 /** 165 * Returns true if an annotation for the specified type 166 * is <em>present</em> on this element, else false. This method 167 * is designed primarily for convenient access to marker annotations. 168 * 169 * <p>The truth value returned by this method is equivalent to: 170 * {@code getAnnotation(annotationClass) != null} 171 * 172 * <p>The body of the default method is specified to be the code 173 * above. 174 * 175 * @param annotationClass the Class object corresponding to the 176 * annotation type 177 * @return true if an annotation for the specified annotation 178 * type is present on this element, else false 179 * @throws NullPointerException if the given annotation class is null 180 * @since 1.5 181 */ 182 default boolean isAnnotationPresent(Class<? extends Annotation> annotationClass) { 183 return getAnnotation(annotationClass) != null; 184 } 185 186 /** 187 * Returns this element's annotation for the specified type if 188 * such an annotation is <em>present</em>, else null. 189 * 190 * @param <T> the type of the annotation to query for and return if present 191 * @param annotationClass the Class object corresponding to the 192 * annotation type 193 * @return this element's annotation for the specified annotation type if 194 * present on this element, else null 195 * @throws NullPointerException if the given annotation class is null 196 * @since 1.5 197 */ 198 <T extends Annotation> T getAnnotation(Class<T> annotationClass); 199 200 /** 201 * Returns annotations that are <em>present</em> on this element. 202 * 203 * If there are no annotations <em>present</em> on this element, the return 204 * value is an array of length 0. 205 * 206 * The caller of this method is free to modify the returned array; it will 207 * have no effect on the arrays returned to other callers. 208 * 209 * @return annotations present on this element 210 * @since 1.5 211 */ 212 Annotation[] getAnnotations(); 213 214 /** 215 * Returns annotations that are <em>associated</em> with this element. 216 * 217 * If there are no annotations <em>associated</em> with this element, the return 218 * value is an array of length 0. 219 * 220 * The difference between this method and {@link #getAnnotation(Class)} 221 * is that this method detects if its argument is a <em>repeatable 222 * annotation type</em> (JLS 9.6), and if so, attempts to find one or 223 * more annotations of that type by "looking through" a container 224 * annotation. 225 * 226 * The caller of this method is free to modify the returned array; it will 227 * have no effect on the arrays returned to other callers. 228 * 229 * @implSpec The default implementation first calls {@link 230 * #getDeclaredAnnotationsByType(Class)} on the argument type. If 231 * the returned array has size greater than zero, the array is 232 * returned. If the returned array has size zero and this {@code 233 * AnnotatedElement} is a class and the argument type is an 234 * inheritable annotation, and the superclass of this {@code 235 * AnnoatedElement} is non-null, then the result of {@code 236 * getAnnotationsByType(annotationClass)} on the superclass is 237 * returned. Otherwise, a zero-length array is returned. 238 * 239 * @param <T> the type of the annotation to query for and return if present 240 * @param annotationClass the Class object corresponding to the 241 * annotation type 242 * @return all this element's annotations for the specified annotation type if 243 * associated with this element, else an array of length zero 244 * @throws NullPointerException if the given annotation class is null 245 * @since 1.8 246 */ 247 default <T extends Annotation> T[] getAnnotationsByType(Class<T> annotationClass) { 248 /* 249 * Definition of associated: directly or indirectly present OR 250 * neither directly nor indirectly present AND the element is 251 * a Class, the annotation type is inheritable, and the 252 * annotation type is associated with the superclass of the 253 * element. 254 */ 255 T[] result = getDeclaredAnnotationsByType(annotationClass); 256 257 if (result.length == 0 && // Neither directly nor indirectly present 258 this instanceof Class && // the element is a class 259 AnnotationType.getInstance(annotationClass).isInherited()) { // Inheritable 260 Class<?> clazz = ((Class<?>) this).getSuperclass(); 261 if (clazz != null) { 262 // Determine if the annotation is associated with the 263 // superclass 264 result = clazz.getAnnotationsByType(annotationClass); 265 } 266 } 267 268 return result; 269 } 270 271 /** 272 * Returns this element's annotation for the specified type if 273 * such an annotation is <em>directly present</em>, else null. 274 * 275 * This method ignores inherited annotations. (Returns null if no 276 * annotations are directly present on this element.) 277 * 278 * @implSpec The default implementation first performs a null check 279 * and then loops over the results of {@link 280 * getDeclaredAnnotations} returning the first annotation whose 281 * annotation type matches the argument type. 282 * 283 * @param <T> the type of the annotation to query for and return if directly present 284 * @param annotationClass the Class object corresponding to the 285 * annotation type 286 * @return this element's annotation for the specified annotation type if 287 * directly present on this element, else null 288 * @throws NullPointerException if the given annotation class is null 289 * @since 1.8 290 */ 291 default <T extends Annotation> T getDeclaredAnnotation(Class<T> annotationClass) { 292 Objects.requireNonNull(annotationClass); 293 // Loop over all directly-present annotations looking for a matching one 294 for (Annotation annotation : getDeclaredAnnotations()) { 295 if (annotationClass.equals(annotation.annotationType())) { 296 // More robust to do a dynamic cast at runtime instead 297 // of compile-time only. 298 return annotationClass.cast(annotation); 299 } 300 } 301 return null; 302 } 303 304 /** 305 * Returns this element's annotation(s) for the specified type if 306 * such annotations are either <em>directly present</em> or 307 * <em>indirectly present</em>. This method ignores inherited 308 * annotations. 309 * 310 * If there are no specified annotations directly or indirectly 311 * present on this element, the return value is an array of length 312 * 0. 313 * 314 * The difference between this method and {@link 315 * #getDeclaredAnnotation(Class)} is that this method detects if its 316 * argument is a <em>repeatable annotation type</em> (JLS 9.6), and if so, 317 * attempts to find one or more annotations of that type by "looking 318 * through" a container annotation if one is present. 319 * 320 * The caller of this method is free to modify the returned array; it will 321 * have no effect on the arrays returned to other callers. 322 * 323 * @implSpec The default implementation may call {@link 324 * #getDeclaredAnnotation(Class)} one or more times to find a 325 * directly present annotation and, if the annotation type is 326 * repeatable, to find a container annotation. If the annotation 327 * type is both directly and indirectly present, {@link 328 * getDeclaredAnnotations()} will get called to determine the 329 * order of the elements in the returned array. Alternatively, 330 * {@link getDeclaredAnnotations()} may be called a single time 331 * and the returned array examined for both directly and 332 * indirectly present annotations. The results of calling {@link 333 * getDeclaredAnnotations()} are assumed to be consistent with the 334 * results of calling {@code #getDeclaredAnnotation} 335 * 336 * @param <T> the type of the annotation to query for and return 337 * if directly or indirectly present 338 * @param annotationClass the Class object corresponding to the 339 * annotation type 340 * @return all this element's annotations for the specified annotation type if 341 * directly or indirectly present on this element, else an array of length zero 342 * @throws NullPointerException if the given annotation class is null 343 * @since 1.8 344 */ 345 default <T extends Annotation> T[] getDeclaredAnnotationsByType(Class<T> annotationClass) { 346 Objects.requireNonNull(annotationClass); 347 int resultSize = 0; 348 T directlyPresent = getDeclaredAnnotation(annotationClass); 349 @SuppressWarnings("unchecked") 350 T[] indirectlyPresent = (T[]) Array.newInstance(annotationClass, 0); 351 352 if (directlyPresent != null) { 353 resultSize++; 354 } 355 356 // If the annotation type is repeatable, look through a 357 // container if one is present 358 Repeatable repeatable = annotationClass.getAnnotation(Repeatable.class); 359 Class<? extends Annotation> containerType = null; 360 if (repeatable != null) { // T is a repeatable annotation type 361 containerType = repeatable.value(); 362 Annotation container = this.getDeclaredAnnotation(containerType); 363 if (container != null) { 364 indirectlyPresent = AnnotationSupport.getValueArray(container); 365 resultSize += indirectlyPresent.length; 366 } 367 } 368 369 if (resultSize == indirectlyPresent.length) { 370 assert resultSize == 0 || directlyPresent == null; 371 /* 372 * If resultSize is 0, indirectlyPresent is either 373 * assigned to the result of the initial Array.newInstance 374 * call or indirectlyPresent is assigned to a zero-length 375 * value array from an empty container annotation. In 376 * either case, a zero-length array is immutable and does 377 * not need to reallocated before being returned. 378 * 379 * If resultSize is nonzero, then indirectlyPresent points 380 * to the result calling a method on an annotation and 381 * annotations are required to implement a no sharing 382 * policy. Therefore, it is not required to copy the 383 * elements of indirectlyPresent into a new array of the 384 * same size. 385 */ 386 return indirectlyPresent; 387 } else { 388 assert resultSize > 0 && (directlyPresent != null || indirectlyPresent.length > 0); 389 @SuppressWarnings("unchecked") 390 T[] returnValue = (T[]) Array.newInstance(annotationClass, resultSize); 391 392 if (indirectlyPresent.length == 0) { 393 assert resultSize == 1; 394 returnValue[0] = directlyPresent; 395 } else { 396 assert directlyPresent != null && indirectlyPresent.length > 0; 397 // Determine whether the directly present annotation 398 // comes before or after the indirectly present ones. 399 400 int indirectOffset = 0; 401 402 for (Annotation a : getDeclaredAnnotations()) { 403 if (a.annotationType().equals(annotationClass)) { 404 indirectOffset = 1; 405 break; 406 } else if (a.annotationType().equals(containerType)) { 407 break; 408 } 409 } 410 411 for (int i = 0; i < resultSize; i++) { 412 returnValue[i + indirectOffset] = indirectlyPresent[i]; 413 } 414 415 returnValue[(indirectOffset == 1) ? 0 : resultSize - 1] = directlyPresent; 416 } 417 return returnValue; 418 } 419 } 420 421 422 /** 423 * Returns annotations that are <em>directly present</em> on this element. 424 * This method ignores inherited annotations. 425 * 426 * If there are no annotations <em>directly present</em> on this element, 427 * the return value is an array of length 0. 428 * 429 * The caller of this method is free to modify the returned array; it will 430 * have no effect on the arrays returned to other callers. 431 * 432 * @return annotations directly present on this element 433 * @since 1.5 434 */ 435 Annotation[] getDeclaredAnnotations(); 436 }