22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.lang.model;
27
28 import java.lang.annotation.*;
29 import java.util.List;
30 import javax.lang.model.element.*;
31 import javax.lang.model.type.*;
32
33 /**
34 * Represents a construct that can be annotated.
35 *
36 * A construct is either an {@linkplain
37 * javax.lang.model.element.Element element} or a {@linkplain
38 * javax.lang.model.type.TypeMirror type}. Annotations on an element
39 * are on a <em>declaration</em>, whereas annotations on a type are on
40 * a specific <em>use</em> of a type name.
41 *
42 * The terms <em>directly present</em>, <em>present</em>,
43 * <em>indirectly present</em>, and <em>associated </em> are used
44 * throughout this interface to describe precisely which annotations
45 * are returned by the methods defined herein.
46 *
47 * <p>In the definitions below, an annotation <i>A</i> has an
48 * annotation type <i>AT</i>. If <i>AT</i> is a repeatable annotation
49 * type, the type of the containing annotation is <i>ATC</i>.
50 *
51 * <p>Annotation <i>A</i> is <em>directly present</em> on a construct
52 * <i>C</i> if either:
53 *
54 * <ul>
55 *
56 * <li><i>A</i> is explicitly or implicitly declared as applying to
57 * the source code representation of <i>C</i>.
58 *
59 * <p>Typically, if exactly one annotation of type <i>AT</i> appears in
60 * the source code of representation of <i>C</i>, then <i>A</i> is
61 * explicitly declared as applying to <i>C</i>.
62 *
63 * An annotation of type <i>AT</i> on a {@linkplain
64 * RecordComponentElement record component} can be implicitly propagated
65 * down to affiliated mandated members. Type annotations modifying the
66 * type of a record component can be also propagated to mandated
67 * members. Propagation of the annotations to mandated members is
68 * governed by rules given in the <cite>The Java™ Language
69 * Specification</cite>.
70 *
71 * If there are multiple annotations of type <i>AT</i> present on
72 * <i>C</i>, then if <i>AT</i> is repeatable annotation type, an
73 * annotation of type <i>ATC</i> is {@linkplain javax.lang.model.util.Elements#getOrigin(AnnotatedConstruct, AnnotationMirror) implicitly declared} on <i>C</i>.
74 * <li> A representation of <i>A</i> appears in the executable output
75 * for <i>C</i>, such as the {@code RuntimeVisibleAnnotations} or
76 * {@code RuntimeVisibleParameterAnnotations} attributes of a class
105 *
106 * </ul>
107 *
108 * An annotation <i>A</i> is <em>associated</em> with a construct
109 * <i>C</i> if either:
110 *
111 * <ul>
112 *
113 * <li> <i>A</i> is directly or indirectly present on <i>C</i>.
114 *
115 * <li> No annotation of type <i>AT</i> is directly or indirectly
116 * present on <i>C</i>, and <i>C</i> is a class, and <i>AT</i> is
117 * inheritable, and <i>A</i> is associated with the superclass of
118 * <i>C</i>.
119 *
120 * </ul>
121 *
122 * @since 1.8
123 * @jls 9.6 Annotation Types
124 * @jls 9.6.4.3 {@code @Inherited}
125 */
126 public interface AnnotatedConstruct {
127 /**
128 * Returns the annotations that are <em>directly present</em> on
129 * this construct.
130 *
131 * @return the annotations <em>directly present</em> on this
132 * construct; an empty list if there are none
133 */
134 List<? extends AnnotationMirror> getAnnotationMirrors();
135
136 /**
137 * Returns this construct's annotation of the specified type if
138 * such an annotation is <em>present</em>, else {@code null}.
139 *
140 * <p> The annotation returned by this method could contain an element
141 * whose value is of type {@code Class}.
142 * This value cannot be returned directly: information necessary to
143 * locate and load a class (such as the class loader to use) is
144 * not available, and the class might not be loadable at all.
|
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.lang.model;
27
28 import java.lang.annotation.*;
29 import java.util.List;
30 import javax.lang.model.element.*;
31 import javax.lang.model.type.*;
32
33 /**
34 * Represents a construct that can be annotated.
35 *
36 * A construct is either an {@linkplain
37 * javax.lang.model.element.Element element} or a {@linkplain
38 * javax.lang.model.type.TypeMirror type}. Annotations on an element
39 * are on a <em>declaration</em>, whereas annotations on a type are on
40 * a specific <em>use</em> of a type name.
41 *
42 * As defined by <cite>The Java™ Language Specification</cite>
43 * section {@jls 9.7.4}, an annotation on an element is a
44 * <em>declaration annotation</em> and an annotation on a type is a
45 * <em>type annotation</em>.
46 *
47 * The terms <em>directly present</em>, <em>present</em>,
48 * <em>indirectly present</em>, and <em>associated </em> are used
49 * throughout this interface to describe precisely which annotations,
50 * either declarations annotations or type annotations,
51 * are returned by the methods in this interface.
52 *
53 * <p>In the definitions below, an annotation <i>A</i> has an
54 * annotation type <i>AT</i>. If <i>AT</i> is a repeatable annotation
55 * type, the type of the containing annotation is <i>ATC</i>.
56 *
57 * <p>Annotation <i>A</i> is <em>directly present</em> on a construct
58 * <i>C</i> if either:
59 *
60 * <ul>
61 *
62 * <li><i>A</i> is {@linkplain
63 * javax.lang.model.util.Elements#getOrigin(AnnotatedConstruct,
64 * AnnotationMirror) explicitly or implicitly}
65 * declared as applying to
66 * the source code representation of <i>C</i>.
67 *
68 * <p>Typically, if exactly one annotation of type <i>AT</i> appears in
69 * the source code of representation of <i>C</i>, then <i>A</i> is
70 * explicitly declared as applying to <i>C</i>.
71 *
72 * An annotation of type <i>AT</i> on a {@linkplain
73 * RecordComponentElement record component} can be implicitly propagated
74 * down to affiliated mandated members. Type annotations modifying the
75 * type of a record component can be also propagated to mandated
76 * members. Propagation of the annotations to mandated members is
77 * governed by rules given in the <cite>The Java™ Language
78 * Specification</cite>.
79 *
80 * If there are multiple annotations of type <i>AT</i> present on
81 * <i>C</i>, then if <i>AT</i> is repeatable annotation type, an
82 * annotation of type <i>ATC</i> is {@linkplain javax.lang.model.util.Elements#getOrigin(AnnotatedConstruct, AnnotationMirror) implicitly declared} on <i>C</i>.
83 * <li> A representation of <i>A</i> appears in the executable output
84 * for <i>C</i>, such as the {@code RuntimeVisibleAnnotations} or
85 * {@code RuntimeVisibleParameterAnnotations} attributes of a class
114 *
115 * </ul>
116 *
117 * An annotation <i>A</i> is <em>associated</em> with a construct
118 * <i>C</i> if either:
119 *
120 * <ul>
121 *
122 * <li> <i>A</i> is directly or indirectly present on <i>C</i>.
123 *
124 * <li> No annotation of type <i>AT</i> is directly or indirectly
125 * present on <i>C</i>, and <i>C</i> is a class, and <i>AT</i> is
126 * inheritable, and <i>A</i> is associated with the superclass of
127 * <i>C</i>.
128 *
129 * </ul>
130 *
131 * @since 1.8
132 * @jls 9.6 Annotation Types
133 * @jls 9.6.4.3 {@code @Inherited}
134 * @jls 9.7.4 Where Annotations May Appear
135 * @jls 9.7.5 Multiple Annotations of the Same Type
136 */
137 public interface AnnotatedConstruct {
138 /**
139 * Returns the annotations that are <em>directly present</em> on
140 * this construct.
141 *
142 * @return the annotations <em>directly present</em> on this
143 * construct; an empty list if there are none
144 */
145 List<? extends AnnotationMirror> getAnnotationMirrors();
146
147 /**
148 * Returns this construct's annotation of the specified type if
149 * such an annotation is <em>present</em>, else {@code null}.
150 *
151 * <p> The annotation returned by this method could contain an element
152 * whose value is of type {@code Class}.
153 * This value cannot be returned directly: information necessary to
154 * locate and load a class (such as the class loader to use) is
155 * not available, and the class might not be loadable at all.
|