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