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
31 /**
32 * Represents an annotated element of the program currently running in this
33 * VM. This interface allows annotations to be read reflectively. All
34 * annotations returned by methods in this interface are immutable and
35 * serializable. The arrays returned by methods of this interface may be modified
36 * by callers without affecting the arrays returned to other callers.
37 *
38 * <p>The {@link #getAnnotationsByType(Class)} and {@link
39 * #getDeclaredAnnotationsByType(Class)} methods support multiple
40 * annotations of the same type on an element. If the argument to
41 * either method is a repeatable annotation type (JLS 9.6), then the
42 * method will "look through" a container annotation (JLS 9.7) and
43 * return the one or more annotations inside the container. Container
44 * annotations may be generated at compile-time to wrap multiple
45 * annotations of the argument type.
46 *
47 * <p>The terms <em>directly present</em>, <em>indirectly present</em>,
48 * <em>present</em>, and <em>associated</em> are used throughout this
49 * interface to describe precisely which annotations are returned by
50 * methods:
51 *
52 * <ul>
53 *
54 * <li> An annotation <i>A</i> is <em>directly present</em> on an
55 * element <i>E</i> if <i>E</i> has a {@code
56 * RuntimeVisibleAnnotations} or {@code
57 * RuntimeVisibleParameterAnnotations} or {@code
58 * RuntimeVisibleTypeAnnotations} attribute, and the attribute
59 * contains <i>A</i>.
60 *
61 * <li>An annotation <i>A</i> is <em>indirectly present</em> on an
62 * element <i>E</i> if <i>E</i> has a {@code RuntimeVisibleAnnotations} or
63 * {@code RuntimeVisibleParameterAnnotations} or {@code RuntimeVisibleTypeAnnotations}
64 * attribute, and <i>A</i> 's type is repeatable, and the attribute contains
65 * exactly one annotation whose value element contains <i>A</i> and whose
66 * type is the containing annotation type of <i>A</i> 's type.
67 *
68 * <li>An annotation <i>A</i> is present on an element <i>E</i> if either:
69 *
70 * <ul>
71 *
72 * <li><i>A</i> is directly present on <i>E</i>; or
73 *
74 * <li>No annotation of <i>A</i> 's type is directly present on
75 * <i>E</i>, and <i>E</i> is a class, and <i>A</i> 's type is
76 * inheritable, and <i>A</i> is present on the superclass of <i>E</i>.
77 *
78 * </ul>
79 *
80 * <li>An annotation <i>A</i> is <em>associated</em> with an element <i>E</i>
81 * if either:
82 *
83 * <ul>
84 *
85 * <li><i>A</i> is directly or indirectly present on <i>E</i>; or
86 *
87 * <li>No annotation of <i>A</i> 's type is directly or indirectly
88 * present on <i>E</i>, and <i>E</i> is a class, and <i>A</i>'s type
89 * is inheritable, and <i>A</i> is associated with the superclass of
90 * <i>E</i>.
91 *
92 * </ul>
93 *
94 * </ul>
95 *
96 * For an invocation of {@code get[Declared]AnnotationsByType( Class <
97 * T >)}, the order of annotations which are directly or indirectly
98 * present on an element <i>E</i> is computed as if indirectly present
99 * annotations on <i>E</i> are directly present on <i>E</i> in place
100 * of their container annotation, in the order in which they appear in
101 * the value element of the container annotation.
102
103 * <p>If an annotation returned by a method in this interface contains
104 * (directly or indirectly) a {@link Class}-valued member referring to
105 * a class that is not accessible in this VM, attempting to read the class
106 * by calling the relevant Class-returning method on the returned annotation
107 * will result in a {@link TypeNotPresentException}.
108 *
109 * <p>Similarly, attempting to read an enum-valued member will result in
110 * a {@link EnumConstantNotPresentException} if the enum constant in the
111 * annotation is no longer present in the enum type.
112 *
113 * <p>If an annotation type <i>T</i> is (meta-)annotated with an
114 * {@code @Repeatable} annotation whose value element indicates a type
115 * <i>TC</i>, but <i>TC</i> does not declare a {@code value()} method
116 * with a return type of <i>T</i>{@code []}, then an exception of type
117 * {@link java.lang.annotation.AnnotationFormatError} is thrown.
118 *
119 * <p>Finally, attempting to read a member whose definition has evolved
120 * incompatibly will result in a {@link
121 * java.lang.annotation.AnnotationTypeMismatchException} or an
122 * {@link java.lang.annotation.IncompleteAnnotationException}.
123 *
124 * @see java.lang.EnumConstantNotPresentException
125 * @see java.lang.TypeNotPresentException
126 * @see AnnotationFormatError
127 * @see java.lang.annotation.AnnotationTypeMismatchException
128 * @see java.lang.annotation.IncompleteAnnotationException
129 * @since 1.5
130 * @author Josh Bloch
131 */
132 public interface AnnotatedElement {
133 /**
134 * Returns true if an annotation for the specified type
135 * is <em>present</em> on this element, else false. This method
136 * is designed primarily for convenient access to marker annotations.
137 *
138 * <p>The truth value returned by this method is equivalent to:
139 * {@code getAnnotation(annotationClass) != null}
140 *
141 * <p>The body of the default method is specified to be the code
142 * above.
143 *
144 * @param annotationClass the Class object corresponding to the
145 * annotation type
146 * @return true if an annotation for the specified annotation
147 * type is present on this element, else false
148 * @throws NullPointerException if the given annotation class is null
149 * @since 1.5
150 */
151 default boolean isAnnotationPresent(Class<? extends Annotation> annotationClass) {
152 return getAnnotation(annotationClass) != null;
153 }
154
155 /**
156 * Returns this element's annotation for the specified type if
157 * such an annotation is <em>present</em>, else null.
158 *
159 * @param <T> the type of the annotation to query for and return if present
160 * @param annotationClass the Class object corresponding to the
161 * annotation type
162 * @return this element's annotation for the specified annotation type if
163 * present on this element, else null
164 * @throws NullPointerException if the given annotation class is null
165 * @since 1.5
166 */
167 <T extends Annotation> T getAnnotation(Class<T> annotationClass);
168
169 /**
170 * Returns annotations that are <em>associated</em> with this element.
171 *
172 * If there are no annotations <em>associated</em> with this element, the return
173 * value is an array of length 0.
174 *
175 * The difference between this method and {@link #getAnnotation(Class)}
176 * is that this method detects if its argument is a <em>repeatable
177 * annotation type</em> (JLS 9.6), and if so, attempts to find one or
178 * more annotations of that type by "looking through" a container
179 * annotation.
180 *
181 * The caller of this method is free to modify the returned array; it will
182 * have no effect on the arrays returned to other callers.
183 *
184 * @param <T> the type of the annotation to query for and return if present
185 * @param annotationClass the Class object corresponding to the
186 * annotation type
187 * @return all this element's annotations for the specified annotation type if
188 * associated with this element, else an array of length zero
189 * @throws NullPointerException if the given annotation class is null
190 * @since 1.8
191 */
192 <T extends Annotation> T[] getAnnotationsByType(Class<T> annotationClass);
193
194 /**
195 * Returns annotations that are <em>present</em> on this element.
196 *
197 * If there are no annotations <em>present</em> on this element, the return
198 * value is an array of length 0.
199 *
200 * The caller of this method is free to modify the returned array; it will
201 * have no effect on the arrays returned to other callers.
202 *
203 * @return annotations present on this element
204 * @since 1.5
205 */
206 Annotation[] getAnnotations();
207
208 /**
209 * Returns this element's annotation for the specified type if
210 * such an annotation is <em>directly present</em>, else null.
211 *
212 * This method ignores inherited annotations. (Returns null if no
213 * annotations are directly present on this element.)
214 *
215 * @param <T> the type of the annotation to query for and return if directly present
216 * @param annotationClass the Class object corresponding to the
217 * annotation type
218 * @return this element's annotation for the specified annotation type if
219 * directly present on this element, else null
220 * @throws NullPointerException if the given annotation class is null
221 * @since 1.8
222 */
223 <T extends Annotation> T getDeclaredAnnotation(Class<T> annotationClass);
224
225 /**
226 * Returns this element's annotation(s) for the specified type if
227 * such annotations are either <em>directly present</em> or
228 * <em>indirectly present</em>. This method ignores inherited
229 * annotations.
230 *
231 * If there are no specified annotations directly or indirectly
232 * present on this element, the return value is an array of length
233 * 0.
234 *
235 * The difference between this method and {@link
236 * #getDeclaredAnnotation(Class)} is that this method detects if its
237 * argument is a <em>repeatable annotation type</em> (JLS 9.6), and if so,
238 * attempts to find one or more annotations of that type by "looking
239 * through" a container annotation.
240 *
241 * The caller of this method is free to modify the returned array; it will
242 * have no effect on the arrays returned to other callers.
243 *
244 * @param <T> the type of the annotation to query for and return
245 * if directly or indirectly present
246 * @param annotationClass the Class object corresponding to the
247 * annotation type
248 * @return all this element's annotations for the specified annotation type if
249 * directly present on this element, else an array of length zero
250 * @throws NullPointerException if the given annotation class is null
251 * @since 1.8
252 */
253 <T extends Annotation> T[] getDeclaredAnnotationsByType(Class<T> annotationClass);
254
255 /**
256 * Returns annotations that are <em>directly present</em> on this element.
257 * This method ignores inherited annotations.
258 *
259 * If there are no annotations <em>directly present</em> on this element,
260 * the return value is an array of length 0.
261 *
262 * The caller of this method is free to modify the returned array; it will
263 * have no effect on the arrays returned to other callers.
264 *
265 * @return annotations directly present on this element
266 * @since 1.5
267 */
268 Annotation[] getDeclaredAnnotations();
269 }