jtulach@258
|
1 |
/*
|
jtulach@258
|
2 |
* Copyright (c) 2003, 2005, Oracle and/or its affiliates. All rights reserved.
|
jtulach@258
|
3 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
jtulach@258
|
4 |
*
|
jtulach@258
|
5 |
* This code is free software; you can redistribute it and/or modify it
|
jtulach@258
|
6 |
* under the terms of the GNU General Public License version 2 only, as
|
jtulach@258
|
7 |
* published by the Free Software Foundation. Oracle designates this
|
jtulach@258
|
8 |
* particular file as subject to the "Classpath" exception as provided
|
jtulach@258
|
9 |
* by Oracle in the LICENSE file that accompanied this code.
|
jtulach@258
|
10 |
*
|
jtulach@258
|
11 |
* This code is distributed in the hope that it will be useful, but WITHOUT
|
jtulach@258
|
12 |
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
jtulach@258
|
13 |
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
jtulach@258
|
14 |
* version 2 for more details (a copy is included in the LICENSE file that
|
jtulach@258
|
15 |
* accompanied this code).
|
jtulach@258
|
16 |
*
|
jtulach@258
|
17 |
* You should have received a copy of the GNU General Public License version
|
jtulach@258
|
18 |
* 2 along with this work; if not, write to the Free Software Foundation,
|
jtulach@258
|
19 |
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
jtulach@258
|
20 |
*
|
jtulach@258
|
21 |
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
|
jtulach@258
|
22 |
* or visit www.oracle.com if you need additional information or have any
|
jtulach@258
|
23 |
* questions.
|
jtulach@258
|
24 |
*/
|
jtulach@258
|
25 |
|
jtulach@258
|
26 |
package java.lang.reflect;
|
jtulach@258
|
27 |
|
jtulach@258
|
28 |
import java.lang.annotation.Annotation;
|
jtulach@258
|
29 |
|
jtulach@258
|
30 |
/**
|
jtulach@258
|
31 |
* Represents an annotated element of the program currently running in this
|
jtulach@258
|
32 |
* VM. This interface allows annotations to be read reflectively. All
|
jtulach@258
|
33 |
* annotations returned by methods in this interface are immutable and
|
jtulach@258
|
34 |
* serializable. It is permissible for the caller to modify the
|
jtulach@258
|
35 |
* arrays returned by accessors for array-valued enum members; it will
|
jtulach@258
|
36 |
* have no affect on the arrays returned to other callers.
|
jtulach@258
|
37 |
*
|
jtulach@258
|
38 |
* <p>If an annotation returned by a method in this interface contains
|
jtulach@258
|
39 |
* (directly or indirectly) a {@link Class}-valued member referring to
|
jtulach@258
|
40 |
* a class that is not accessible in this VM, attempting to read the class
|
jtulach@258
|
41 |
* by calling the relevant Class-returning method on the returned annotation
|
jtulach@258
|
42 |
* will result in a {@link TypeNotPresentException}.
|
jtulach@258
|
43 |
*
|
jtulach@258
|
44 |
* <p>Similarly, attempting to read an enum-valued member will result in
|
jtulach@258
|
45 |
* a {@link EnumConstantNotPresentException} if the enum constant in the
|
jtulach@258
|
46 |
* annotation is no longer present in the enum type.
|
jtulach@258
|
47 |
*
|
jtulach@258
|
48 |
* <p>Finally, Attempting to read a member whose definition has evolved
|
jtulach@258
|
49 |
* incompatibly will result in a {@link
|
jtulach@258
|
50 |
* java.lang.annotation.AnnotationTypeMismatchException} or an
|
jtulach@258
|
51 |
* {@link java.lang.annotation.IncompleteAnnotationException}.
|
jtulach@258
|
52 |
*
|
jtulach@258
|
53 |
* @see java.lang.EnumConstantNotPresentException
|
jtulach@258
|
54 |
* @see java.lang.TypeNotPresentException
|
jtulach@258
|
55 |
* @see java.lang.annotation.AnnotationFormatError
|
jtulach@258
|
56 |
* @see java.lang.annotation.AnnotationTypeMismatchException
|
jtulach@258
|
57 |
* @see java.lang.annotation.IncompleteAnnotationException
|
jtulach@258
|
58 |
* @since 1.5
|
jtulach@258
|
59 |
* @author Josh Bloch
|
jtulach@258
|
60 |
*/
|
jtulach@258
|
61 |
public interface AnnotatedElement {
|
jtulach@258
|
62 |
/**
|
jtulach@258
|
63 |
* Returns true if an annotation for the specified type
|
jtulach@258
|
64 |
* is present on this element, else false. This method
|
jtulach@258
|
65 |
* is designed primarily for convenient access to marker annotations.
|
jtulach@258
|
66 |
*
|
jtulach@258
|
67 |
* @param annotationClass the Class object corresponding to the
|
jtulach@258
|
68 |
* annotation type
|
jtulach@258
|
69 |
* @return true if an annotation for the specified annotation
|
jtulach@258
|
70 |
* type is present on this element, else false
|
jtulach@258
|
71 |
* @throws NullPointerException if the given annotation class is null
|
jtulach@258
|
72 |
* @since 1.5
|
jtulach@258
|
73 |
*/
|
jtulach@258
|
74 |
boolean isAnnotationPresent(Class<? extends Annotation> annotationClass);
|
jtulach@258
|
75 |
|
jtulach@258
|
76 |
/**
|
jtulach@258
|
77 |
* Returns this element's annotation for the specified type if
|
jtulach@258
|
78 |
* such an annotation is present, else null.
|
jtulach@258
|
79 |
*
|
jtulach@258
|
80 |
* @param annotationClass the Class object corresponding to the
|
jtulach@258
|
81 |
* annotation type
|
jtulach@258
|
82 |
* @return this element's annotation for the specified annotation type if
|
jtulach@258
|
83 |
* present on this element, else null
|
jtulach@258
|
84 |
* @throws NullPointerException if the given annotation class is null
|
jtulach@258
|
85 |
* @since 1.5
|
jtulach@258
|
86 |
*/
|
jtulach@258
|
87 |
<T extends Annotation> T getAnnotation(Class<T> annotationClass);
|
jtulach@258
|
88 |
|
jtulach@258
|
89 |
/**
|
jtulach@258
|
90 |
* Returns all annotations present on this element. (Returns an array
|
jtulach@258
|
91 |
* of length zero if this element has no annotations.) The caller of
|
jtulach@258
|
92 |
* this method is free to modify the returned array; it will have no
|
jtulach@258
|
93 |
* effect on the arrays returned to other callers.
|
jtulach@258
|
94 |
*
|
jtulach@258
|
95 |
* @return all annotations present on this element
|
jtulach@258
|
96 |
* @since 1.5
|
jtulach@258
|
97 |
*/
|
jtulach@258
|
98 |
Annotation[] getAnnotations();
|
jtulach@258
|
99 |
|
jtulach@258
|
100 |
/**
|
jtulach@258
|
101 |
* Returns all annotations that are directly present on this
|
jtulach@258
|
102 |
* element. Unlike the other methods in this interface, this method
|
jtulach@258
|
103 |
* ignores inherited annotations. (Returns an array of length zero if
|
jtulach@258
|
104 |
* no annotations are directly present on this element.) The caller of
|
jtulach@258
|
105 |
* this method is free to modify the returned array; it will have no
|
jtulach@258
|
106 |
* effect on the arrays returned to other callers.
|
jtulach@258
|
107 |
*
|
jtulach@258
|
108 |
* @return All annotations directly present on this element
|
jtulach@258
|
109 |
* @since 1.5
|
jtulach@258
|
110 |
*/
|
jtulach@258
|
111 |
Annotation[] getDeclaredAnnotations();
|
jtulach@258
|
112 |
}
|