1 /* 2 * Copyright (C) 2016 The Android Open Source Project 3 * Copyright (c) 2003, 2005, 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 libcore.reflect.AnnotatedElements; 31 32 /** 33 * Represents an annotated element of the program currently running in this 34 * VM. This interface allows annotations to be read reflectively. All 35 * annotations returned by methods in this interface are immutable and 36 * serializable. It is permissible for the caller to modify the 37 * arrays returned by accessors for array-valued enum members; it will 38 * have no affect on the arrays returned to other callers. 39 * 40 * <p>If an annotation returned by a method in this interface contains 41 * (directly or indirectly) a {@link Class}-valued member referring to 42 * a class that is not accessible in this VM, attempting to read the class 43 * by calling the relevant Class-returning method on the returned annotation 44 * will result in a {@link TypeNotPresentException}. 45 * 46 * <p>Similarly, attempting to read an enum-valued member will result in 47 * a {@link EnumConstantNotPresentException} if the enum constant in the 48 * annotation is no longer present in the enum type. 49 * 50 * <p>Finally, Attempting to read a member whose definition has evolved 51 * incompatibly will result in a {@link 52 * java.lang.annotation.AnnotationTypeMismatchException} or an 53 * {@link java.lang.annotation.IncompleteAnnotationException}. 54 * 55 * @see java.lang.EnumConstantNotPresentException 56 * @see java.lang.TypeNotPresentException 57 * @see java.lang.annotation.AnnotationFormatError 58 * @see java.lang.annotation.AnnotationTypeMismatchException 59 * @see java.lang.annotation.IncompleteAnnotationException 60 * @since 1.5 61 * @author Josh Bloch 62 */ 63 public interface AnnotatedElement { 64 /** 65 * Returns true if an annotation for the specified type 66 * is present on this element, else false. This method 67 * is designed primarily for convenient access to marker annotations. 68 * 69 * @param annotationClass the Class object corresponding to the 70 * annotation type 71 * @return true if an annotation for the specified annotation 72 * type is present on this element, else false 73 * @throws NullPointerException if the given annotation class is null 74 * @since 1.5 75 */ isAnnotationPresent(Class<? extends Annotation> annotationClass)76 default boolean isAnnotationPresent(Class<? extends Annotation> annotationClass) { 77 return getAnnotation(annotationClass) != null; 78 } 79 80 /** 81 * Returns this element's annotation for the specified type if 82 * such an annotation is present, else null. 83 * 84 * @param annotationClass the Class object corresponding to the 85 * annotation type 86 * @return this element's annotation for the specified annotation type if 87 * present on this element, else null 88 * @throws NullPointerException if the given annotation class is null 89 * @since 1.5 90 */ getAnnotation(Class<T> annotationClass)91 <T extends Annotation> T getAnnotation(Class<T> annotationClass); 92 93 /** 94 * Returns all annotations present on this element. (Returns an array 95 * of length zero if this element has no annotations.) The caller of 96 * this method is free to modify the returned array; it will have no 97 * effect on the arrays returned to other callers. 98 * 99 * @return all annotations present on this element 100 * @since 1.5 101 */ getAnnotations()102 Annotation[] getAnnotations(); 103 104 /** 105 * Returns all annotations that are directly present on this 106 * element. Unlike the other methods in this interface, this method 107 * ignores inherited annotations. (Returns an array of length zero if 108 * no annotations are directly present on this element.) The caller of 109 * this method is free to modify the returned array; it will have no 110 * effect on the arrays returned to other callers. 111 * 112 * @return All annotations directly present on this element 113 * @since 1.5 114 */ getDeclaredAnnotations()115 Annotation[] getDeclaredAnnotations(); 116 117 /** 118 * Returns a directly-present annotation on {@code this} element, whose class is 119 * {@code annotationClass}, or {@code null} if nothing was found. 120 * 121 * @since 1.8 122 */ getDeclaredAnnotation(Class<T> annotationClass)123 default <T extends Annotation> Annotation getDeclaredAnnotation(Class<T> annotationClass) { 124 return AnnotatedElements.getDeclaredAnnotation(this, annotationClass); 125 } 126 127 /** 128 * Returns a directly or indirectly present list of annotations on {@code this} element, 129 * whose class is {@code annotationClass}, or an empty array if nothing was found. 130 * 131 * @since 1.8 132 */ getDeclaredAnnotationsByType(Class<T> annotationClass)133 default <T extends Annotation> T[] getDeclaredAnnotationsByType(Class<T> annotationClass) { 134 return AnnotatedElements.getDeclaredAnnotationsByType(this, annotationClass); 135 } 136 137 /** 138 * Returns an associated list of annotations on {@code this} element, 139 * whose class is {@code annotationClass}, or an empty array if nothing was found. 140 * 141 * @since 1.8 142 */ getAnnotationsByType(Class<T> annotationClass)143 default <T extends Annotation> T[] getAnnotationsByType(Class<T> annotationClass) { 144 return AnnotatedElements.getAnnotationsByType(this, annotationClass); 145 } 146 } 147