1 /*
2 * Copyright (c) 2005, 2020, 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 javax.lang.model.element;
27
28
29 import java.lang.annotation.Annotation;
30 import java.lang.annotation.AnnotationTypeMismatchException;
31 import java.lang.annotation.IncompleteAnnotationException;
32 import java.util.List;
33 import java.util.Set;
34
35 import javax.lang.model.type.*;
36 import javax.lang.model.util.*;
37
38 /**
39 * Represents a program element such as a module, package, class, or method.
40 * Each element represents a static, language-level construct
41 * (and not, for example, a runtime construct of the virtual machine).
42 *
43 * <p> Elements should be compared using the {@link #equals(Object)}
44 * method. There is no guarantee that any particular element will
45 * always be represented by the same object.
46 *
47 * <p> To implement operations based on the class of an {@code
48 * Element} object, either use a {@linkplain ElementVisitor visitor} or
49 * use the result of the {@link #getKind} method. Using {@code
50 * instanceof} is <em>not</em> necessarily a reliable idiom for
51 * determining the effective class of an object in this modeling
52 * hierarchy since an implementation may choose to have a single object
53 * implement multiple {@code Element} subinterfaces.
54 *
55 * @author Joseph D. Darcy
56 * @author Scott Seligman
57 * @author Peter von der Ahé
58 * @see Elements
59 * @see TypeMirror
60 * @since 1.6
61 */
62 public interface Element extends javax.lang.model.AnnotatedConstruct {
63 /**
64 * Returns the type defined by this element.
65 * @return the type defined by this element
66 *
67 * @see Types
68 * @see ExecutableElement#asType
69 * @see ModuleElement#asType
70 * @see PackageElement#asType
71 * @see TypeElement#asType
72 * @see TypeParameterElement#asType
73 * @see VariableElement#asType
74 */
75 TypeMirror asType();
76
77 /**
78 * Returns the {@code kind} of this element.
79 *
80 * <ul>
81 *
82 * <li> The kind of a {@linkplain PackageElement package} is
83 * {@link ElementKind#PACKAGE PACKAGE}.
84 *
85 * <li> The kind of a {@linkplain ModuleElement module} is {@link
86 * ElementKind#MODULE MODULE}.
87 *
88 * <li> The kind of a {@linkplain TypeElement type element} is one
89 * of {@link ElementKind#ANNOTATION_TYPE ANNOTATION_TYPE}, {@link
90 * ElementKind#CLASS CLASS}, {@link ElementKind#ENUM ENUM}, {@link
91 * ElementKind#INTERFACE INTERFACE}, or {@link ElementKind#RECORD
92 * RECORD}.
93 *
94 * <li> The kind of a {@linkplain VariableElement variable} is one
95 * of {@link ElementKind#ENUM_CONSTANT ENUM_CONSTANT}, {@link
96 * ElementKind#EXCEPTION_PARAMETER EXCEPTION_PARAMETER}, {@link
97 * ElementKind#FIELD FIELD}, {@link ElementKind#LOCAL_VARIABLE
98 * LOCAL_VARIABLE}, {@link ElementKind#PARAMETER PARAMETER},
99 * {@link ElementKind#RESOURCE_VARIABLE RESOURCE_VARIABLE}, or
100 * {@link ElementKind#BINDING_VARIABLE BINDING_VARIABLE}.
101 *
102 * <li> The kind of an {@linkplain ExecutableElement executable}
103 * is one of {@link ElementKind#CONSTRUCTOR CONSTRUCTOR}, {@link
104 * ElementKind#INSTANCE_INIT INSTANCE_INIT}, {@link
105 * ElementKind#METHOD METHOD}, or {@link ElementKind#STATIC_INIT
106 * STATIC_INIT}.
107 *
108 * <li> The kind of a {@linkplain TypeParameterElement type parameter} is
109 * {@link ElementKind#TYPE_PARAMETER TYPE_PARAMETER}.
110 *
111 * <li> The kind of a {@linkplain RecordComponentElement record
112 * component} is {@link ElementKind#RECORD_COMPONENT
113 * RECORD_COMPONENT}.
114 *
115 * </ul>
116 *
117 * @return the kind of this element
118 */
119 ElementKind getKind();
120
121 /**
122 * Returns the modifiers of this element, excluding annotations.
123 * Implicit modifiers, such as the {@code public} and {@code static}
124 * modifiers of interface members, are included.
125 *
126 * @return the modifiers of this element, or an empty set if there are none
127 */
128 Set<Modifier> getModifiers();
129
130 /**
131 * Returns the simple (unqualified) name of this element. The
132 * name of a generic type does not include any reference to its
133 * formal type parameters.
134 *
135 * For example, the simple name of the type element {@code
136 * java.util.Set<E>} is {@code "Set"}.
137 *
138 * If this element represents an unnamed {@linkplain
139 * PackageElement#getSimpleName package} or unnamed {@linkplain
140 * ModuleElement#getSimpleName module}, an empty name is returned.
141 *
142 * If it represents a {@linkplain ExecutableElement#getSimpleName
143 * constructor}, the name "{@code <init>}" is returned. If it
144 * represents a {@linkplain ExecutableElement#getSimpleName static
145 * initializer}, the name "{@code <clinit>}" is returned.
146 *
147 * If it represents an {@linkplain TypeElement#getSimpleName
148 * anonymous class} or {@linkplain ExecutableElement#getSimpleName
149 * instance initializer}, an empty name is returned.
150 *
151 * @return the simple name of this element
152 * @see PackageElement#getSimpleName
153 * @see ExecutableElement#getSimpleName
154 * @see TypeElement#getSimpleName
155 * @see VariableElement#getSimpleName
156 * @see ModuleElement#getSimpleName
157 * @see RecordComponentElement#getSimpleName
158 * @revised 9
159 * @spec JPMS
160 */
161 Name getSimpleName();
162
163 /**
164 * Returns the innermost element
165 * within which this element is, loosely speaking, enclosed.
166 * <ul>
167 * <li> If this element is one whose declaration is lexically enclosed
168 * immediately within the declaration of another element, that other
169 * element is returned.
170 *
171 * <li> If this is a {@linkplain TypeElement#getEnclosingElement
172 * top-level type}, its package is returned.
173 *
174 * <li> If this is a {@linkplain
175 * PackageElement#getEnclosingElement package}, its module is
176 * returned if such a module exists. Otherwise, {@code null} is returned.
177 *
178 * <li> If this is a {@linkplain
179 * TypeParameterElement#getEnclosingElement type parameter},
180 * {@linkplain TypeParameterElement#getGenericElement the
181 * generic element} of the type parameter is returned.
182 *
183 * <li> If this is a {@linkplain
184 * VariableElement#getEnclosingElement method or constructor
185 * parameter}, {@linkplain ExecutableElement the executable
186 * element} which declares the parameter is returned.
187 *
188 * <li> If this is a {@linkplain
189 * RecordComponentElement#getEnclosingElement record component},
190 * {@linkplain TypeElement the type} which declares the
191 * record component is returned.
192 *
193 * <li> If this is a {@linkplain ModuleElement#getEnclosingElement
194 * module}, {@code null} is returned.
195 *
196 * </ul>
197 *
198 * @return the enclosing element, or {@code null} if there is none
199 * @see Elements#getPackageOf
200 * @revised 9
201 * @spec JPMS
202 */
203 Element getEnclosingElement();
204
205 /**
206 * Returns the elements that are, loosely speaking, directly
207 * enclosed by this element.
208 *
209 * A {@linkplain TypeElement#getEnclosedElements class or
210 * interface} is considered to enclose the fields, methods,
211 * constructors, record components, and member types that it directly declares.
212 *
213 * A {@linkplain PackageElement#getEnclosedElements package}
214 * encloses the top-level classes and interfaces within it, but is
215 * not considered to enclose subpackages.
216 *
217 * A {@linkplain ModuleElement#getEnclosedElements module}
218 * encloses packages within it.
219 *
220 * Enclosed elements may include implicitly declared {@linkplain
221 * Elements.Origin#MANDATED mandated} elements.
222 *
223 * Other kinds of elements are not currently considered to enclose
224 * any elements; however, that may change as this API or the
225 * programming language evolves.
226 *
227 * @apiNote Elements of certain kinds can be isolated using
228 * methods in {@link ElementFilter}.
229 *
230 * @return the enclosed elements, or an empty list if none
231 * @see TypeElement#getEnclosedElements
232 * @see PackageElement#getEnclosedElements
233 * @see ModuleElement#getEnclosedElements
234 * @see Elements#getAllMembers
235 * @jls 8.8.9 Default Constructor
236 * @jls 8.9 Enum Types
237 * @revised 9
238 * @spec JPMS
239 */
240 List<? extends Element> getEnclosedElements();
241
242 /**
243 * Returns {@code true} if the argument represents the same
244 * element as {@code this}, or {@code false} otherwise.
245 *
246 * @apiNote The identity of an element involves implicit state
247 * not directly accessible from the element's methods, including
248 * state about the presence of unrelated types. Element objects
249 * created by different implementations of these interfaces should
250 * <i>not</i> be expected to be equal even if "the same"
251 * element is being modeled; this is analogous to the inequality
252 * of {@code Class} objects for the same class file loaded through
253 * different class loaders.
254 *
255 * @param obj the object to be compared with this element
256 * @return {@code true} if the specified object represents the same
257 * element as this
258 */
259 @Override
260 boolean equals(Object obj);
261
262 /**
263 * Obeys the general contract of {@link Object#hashCode Object.hashCode}.
264 *
265 * @see #equals
266 */
267 @Override
268 int hashCode();
269
270 /**
271 * {@inheritDoc}
272 *
273 * <p>To get inherited annotations as well, use {@link
274 * Elements#getAllAnnotationMirrors(Element)
275 * getAllAnnotationMirrors}.
276 *
277 * <p>Note that any annotations returned by this method are
278 * declaration annotations.
279 *
280 * @since 1.6
281 */
282 @Override
283 List<? extends AnnotationMirror> getAnnotationMirrors();
284
285 /**
286 * {@inheritDoc}
287 *
288 * <p>Note that any annotation returned by this method is a
289 * declaration annotation.
290 *
291 * @since 1.6
292 */
293 @Override
294 <A extends Annotation> A getAnnotation(Class<A> annotationType);
295
296 /**
297 * {@inheritDoc}
298 *
299 * <p>Note that any annotations returned by this method are
300 * declaration annotations.
301 *
302 * @since 8
303 */
304 @Override
305 <A extends Annotation> A[] getAnnotationsByType(Class<A> annotationType);
306
307 /**
308 * Applies a visitor to this element.
309 *
310 * @param <R> the return type of the visitor's methods
311 * @param <P> the type of the additional parameter to the visitor's methods
312 * @param v the visitor operating on this element
313 * @param p additional parameter to the visitor
314 * @return a visitor-specified result
315 */
316 <R, P> R accept(ElementVisitor<R, P> v, P p);
317 }