Mercurial > jdk8-mips64-public > langtools / file comparison

comparison: src/share/classes/javax/lang/model/element/Element.java

src/share/classes/javax/lang/model/element/Element.java

changeset 0
959103a6100f
child 2525
2eb010b6cb22
equal deleted inserted replaced
-1:000000000000 0:959103a6100f
1 /*
2 * Copyright (c) 2005, 2013, 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 /**
40 * Represents a program element such as a 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 */
63 public 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}, an empty name is
109 * 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 */
126 Name getSimpleName();
127
128 /**
129 * Returns the innermost element
130 * within which this element is, loosely speaking, enclosed.
131 * <ul>
132 * <li> If this element is one whose declaration is lexically enclosed
133 * immediately within the declaration of another element, that other
134 * element is returned.
135 *
136 * <li> If this is a {@linkplain TypeElement#getEnclosingElement
137 * top-level type}, its package is returned.
138 *
139 * <li> If this is a {@linkplain
140 * PackageElement#getEnclosingElement package}, {@code null} is
141 * returned.
142 *
143 * <li> If this is a {@linkplain
144 * TypeParameterElement#getEnclosingElement type parameter},
145 * {@linkplain TypeParameterElement#getGenericElement the
146 * generic element} of the type parameter is returned.
147 *
148 * <li> If this is a {@linkplain
149 * VariableElement#getEnclosingElement method or constructor
150 * parameter}, {@linkplain ExecutableElement the executable
151 * element} which declares the parameter is returned.
152 *
153 * </ul>
154 *
155 * @return the enclosing element, or {@code null} if there is none
156 * @see Elements#getPackageOf
157 */
158 Element getEnclosingElement();
159
160 /**
161 * Returns the elements that are, loosely speaking, directly
162 * enclosed by this element.
163 *
164 * A {@linkplain TypeElement#getEnclosedElements class or
165 * interface} is considered to enclose the fields, methods,
166 * constructors, and member types that it directly declares.
167 *
168 * A {@linkplain PackageElement#getEnclosedElements package}
169 * encloses the top-level classes and interfaces within it, but is
170 * not considered to enclose subpackages.
171 *
172 * Other kinds of elements are not currently considered to enclose
173 * any elements; however, that may change as this API or the
174 * programming language evolves.
175 *
176 * <p>Note that elements of certain kinds can be isolated using
177 * methods in {@link ElementFilter}.
178 *
179 * @return the enclosed elements, or an empty list if none
180 * @see PackageElement#getEnclosedElements
181 * @see TypeElement#getEnclosedElements
182 * @see Elements#getAllMembers
183 * @jls 8.8.9 Default Constructor
184 * @jls 8.9 Enums
185 */
186 List<? extends Element> getEnclosedElements();
187
188 /**
189 * Returns {@code true} if the argument represents the same
190 * element as {@code this}, or {@code false} otherwise.
191 *
192 * <p>Note that the identity of an element involves implicit state
193 * not directly accessible from the element's methods, including
194 * state about the presence of unrelated types. Element objects
195 * created by different implementations of these interfaces should
196 * <i>not</i> be expected to be equal even if &quot;the same&quot;
197 * element is being modeled; this is analogous to the inequality
198 * of {@code Class} objects for the same class file loaded through
199 * different class loaders.
200 *
201 * @param obj the object to be compared with this element
202 * @return {@code true} if the specified object represents the same
203 * element as this
204 */
205 @Override
206 boolean equals(Object obj);
207
208 /**
209 * Obeys the general contract of {@link Object#hashCode Object.hashCode}.
210 *
211 * @see #equals
212 */
213 @Override
214 int hashCode();
215
216
217 /**
218 * {@inheritDoc}
219 *
220 * <p> To get inherited annotations as well, use {@link
221 * Elements#getAllAnnotationMirrors(Element)
222 * getAllAnnotationMirrors}.
223 *
224 * @since 1.6
225 */
226 @Override
227 List<? extends AnnotationMirror> getAnnotationMirrors();
228
229 /**
230 * {@inheritDoc}
231 * @since 1.6
232 */
233 @Override
234 <A extends Annotation> A getAnnotation(Class<A> annotationType);
235
236 /**
237 * Applies a visitor to this element.
238 *
239 * @param <R> the return type of the visitor's methods
240 * @param <P> the type of the additional parameter to the visitor's methods
241 * @param v the visitor operating on this element
242 * @param p additional parameter to the visitor
243 * @return a visitor-specified result
244 */
245 <R, P> R accept(ElementVisitor<R, P> v, P p);
246 }

Mercurial Repository: jdk8-mips64-public/langtools

mercurial