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), if
43 * present, and return any 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
205 * @return annotations present on this element
206 * @since 1.5
207 */
208 Annotation[] getAnnotations();
209
210 /**
211 * Returns annotations that are <em>associated</em> with this element.
212 *
213 * If there are no annotations <em>associated</em> with this element, the return
214 * value is an array of length 0.
215 *
216 * The difference between this method and {@link #getAnnotation(Class)}
217 * is that this method detects if its argument is a <em>repeatable
218 * annotation type</em> (JLS 9.6), and if so, attempts to find one or
219 * more annotations of that type by "looking through" a container
220 * annotation.
221 *
222 * The caller of this method is free to modify the returned array; it will
223 * have no effect on the arrays returned to other callers.
224 *
225 * @param <T> the type of the annotation to query for and return if present
226 * @param annotationClass the Class object corresponding to the
227 * annotation type
228 * @return all this element's annotations for the specified annotation type if
229 * associated with this element, else an array of length zero
230 * @throws NullPointerException if the given annotation class is null
231 * @since 1.8
232 */
233 <T extends Annotation> T[] getAnnotationsByType(Class<T> annotationClass);
234
235 /**
236 * Returns this element's annotation for the specified type if
237 * such an annotation is <em>directly present</em>, else null.
238 *
239 * This method ignores inherited annotations. (Returns null if no
240 * annotations are directly present on this element.)
241 *
242 * @param <T> the type of the annotation to query for and return if directly present
243 * @param annotationClass the Class object corresponding to the
244 * annotation type
245 * @return this element's annotation for the specified annotation type if
246 * directly present on this element, else null
247 * @throws NullPointerException if the given annotation class is null
248 * @since 1.8
249 */
250 <T extends Annotation> T getDeclaredAnnotation(Class<T> annotationClass);
251
252 /**
253 * Returns this element's annotation(s) for the specified type if
254 * such annotations are either <em>directly present</em> or
255 * <em>indirectly present</em>. This method ignores inherited
256 * annotations.
257 *
258 * If there are no specified annotations directly or indirectly
259 * present on this element, the return value is an array of length
260 * 0.
261 *
262 * The difference between this method and {@link
263 * #getDeclaredAnnotation(Class)} is that this method detects if its
264 * argument is a <em>repeatable annotation type</em> (JLS 9.6), and if so,
265 * attempts to find one or more annotations of that type by "looking
266 * through" a container annotation if one is present.
267 *
268 * The caller of this method is free to modify the returned array; it will
269 * have no effect on the arrays returned to other callers.
270 *
271 * @param <T> the type of the annotation to query for and return
272 * if directly or indirectly present
273 * @param annotationClass the Class object corresponding to the
274 * annotation type
275 * @return all this element's annotations for the specified annotation type if
276 * directly or indirectly present on this element, else an array of length zero
277 * @throws NullPointerException if the given annotation class is null
278 * @since 1.8
279 */
280 <T extends Annotation> T[] getDeclaredAnnotationsByType(Class<T> annotationClass);
281
282 /**
283 * Returns annotations that are <em>directly present</em> on this element.
284 * This method ignores inherited annotations.
285 *
286 * If there are no annotations <em>directly present</em> on this element,
287 * the return value is an array of length 0.
288 *
289 * The caller of this method is free to modify the returned array; it will
290 * have no effect on the arrays returned to other callers.
291 *
292 * @return annotations directly present on this element
293 * @since 1.5
294 */
295 Annotation[] getDeclaredAnnotations();
296 }
|
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
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 }
|