Tue, 25 May 2010 15:54:51 -0700
6943119: Rebrand source copyright notices
Reviewed-by: darcy
1 /*
2 * Copyright (c) 2005, 2006, 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 */
26 package javax.lang.model.element;
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;
35 import javax.lang.model.element.Modifier;
36 import javax.lang.model.type.*;
37 import javax.lang.model.util.*;
40 /**
41 * Represents a program element such as a package, class, or method.
42 * Each element represents a static, language-level construct
43 * (and not, for example, a runtime construct of the virtual machine).
44 *
45 * <p> Elements should be compared using the {@link #equals(Object)}
46 * method. There is no guarantee that any particular element will
47 * always be represented by the same object.
48 *
49 * <p> To implement operations based on the class of an {@code
50 * Element} object, either use a {@linkplain ElementVisitor visitor} or
51 * use the result of the {@link #getKind} method. Using {@code
52 * instanceof} is <em>not</em> necessarily a reliable idiom for
53 * determining the effective class of an object in this modeling
54 * hierarchy since an implementation may choose to have a single object
55 * implement multiple {@code Element} subinterfaces.
56 *
57 * @author Joseph D. Darcy
58 * @author Scott Seligman
59 * @author Peter von der Ahé
60 * @see Elements
61 * @see TypeMirror
62 * @since 1.6
63 */
64 public interface Element {
66 /**
67 * Returns the type defined by this element.
68 *
69 * <p> A generic element defines a family of types, not just one.
70 * If this is a generic element, a <i>prototypical</i> type is
71 * returned. This is the element's invocation on the
72 * type variables corresponding to its own formal type parameters.
73 * For example,
74 * for the generic class element {@code C<N extends Number>},
75 * the parameterized type {@code C<N>} is returned.
76 * The {@link Types} utility interface has more general methods
77 * for obtaining the full range of types defined by an element.
78 *
79 * @see Types
80 *
81 * @return the type defined by this element
82 */
83 TypeMirror asType();
85 /**
86 * Returns the {@code kind} of this element.
87 *
88 * @return the kind of this element
89 */
90 ElementKind getKind();
92 /**
93 * Returns the annotations that are directly present on this element.
94 *
95 * <p> To get inherited annotations as well, use
96 * {@link Elements#getAllAnnotationMirrors(Element) getAllAnnotationMirrors}.
97 *
98 * @see ElementFilter
99 *
100 * @return the annotations directly present on this element;
101 * an empty list if there are none
102 */
103 List<? extends AnnotationMirror> getAnnotationMirrors();
105 /**
106 * Returns this element's annotation for the specified type if
107 * such an annotation is present, else {@code null}. The
108 * annotation may be either inherited or directly present on this
109 * element.
110 *
111 * <p> The annotation returned by this method could contain an element
112 * whose value is of type {@code Class}.
113 * This value cannot be returned directly: information necessary to
114 * locate and load a class (such as the class loader to use) is
115 * not available, and the class might not be loadable at all.
116 * Attempting to read a {@code Class} object by invoking the relevant
117 * method on the returned annotation
118 * will result in a {@link MirroredTypeException},
119 * from which the corresponding {@link TypeMirror} may be extracted.
120 * Similarly, attempting to read a {@code Class[]}-valued element
121 * will result in a {@link MirroredTypesException}.
122 *
123 * <blockquote>
124 * <i>Note:</i> This method is unlike others in this and related
125 * interfaces. It operates on runtime reflective information —
126 * representations of annotation types currently loaded into the
127 * VM — rather than on the representations defined by and used
128 * throughout these interfaces. Consequently, calling methods on
129 * the returned annotation object can throw many of the exceptions
130 * that can be thrown when calling methods on an annotation object
131 * returned by core reflection. This method is intended for
132 * callers that are written to operate on a known, fixed set of
133 * annotation types.
134 * </blockquote>
135 *
136 * @param <A> the annotation type
137 * @param annotationType the {@code Class} object corresponding to
138 * the annotation type
139 * @return this element's annotation for the specified annotation
140 * type if present on this element, else {@code null}
141 *
142 * @see #getAnnotationMirrors()
143 * @see java.lang.reflect.AnnotatedElement#getAnnotation
144 * @see EnumConstantNotPresentException
145 * @see AnnotationTypeMismatchException
146 * @see IncompleteAnnotationException
147 * @see MirroredTypeException
148 * @see MirroredTypesException
149 */
150 <A extends Annotation> A getAnnotation(Class<A> annotationType);
152 /**
153 * Returns the modifiers of this element, excluding annotations.
154 * Implicit modifiers, such as the {@code public} and {@code static}
155 * modifiers of interface members, are included.
156 *
157 * @return the modifiers of this element, or an empty set if there are none
158 */
159 Set<Modifier> getModifiers();
161 /**
162 * Returns the simple (unqualified) name of this element.
163 * The name of a generic type does not include any reference
164 * to its formal type parameters.
165 * For example, the simple name of the type element
166 * {@code java.util.Set<E>} is {@code "Set"}.
167 * If this element represents an unnamed package, an empty name is
168 * returned. If it represents a constructor, the name "{@code
169 * <init>}" is returned. If it represents a static initializer,
170 * the name "{@code <clinit>}" is returned. If it represents an
171 * anonymous class or instance initializer, an empty name is
172 * returned.
173 *
174 * @return the simple name of this element
175 */
176 Name getSimpleName();
178 /**
179 * Returns the innermost element
180 * within which this element is, loosely speaking, enclosed.
181 * <ul>
182 * <li> If this element is one whose declaration is lexically enclosed
183 * immediately within the declaration of another element, that other
184 * element is returned.
185 * <li> If this is a top-level type, its package is returned.
186 * <li> If this is a package, {@code null} is returned.
187 * <li> If this is a type parameter, {@code null} is returned.
188 * </ul>
189 *
190 * @return the enclosing element, or {@code null} if there is none
191 * @see Elements#getPackageOf
192 */
193 Element getEnclosingElement();
195 /**
196 * Returns the elements that are, loosely speaking, directly
197 * enclosed by this element.
198 *
199 * A class or interface is considered to enclose the fields,
200 * methods, constructors, and member types that it directly
201 * declares. This includes any (implicit) default constructor and
202 * the implicit {@code values} and {@code valueOf} methods of an
203 * enum type.
204 *
205 * A package encloses the top-level classes and interfaces within
206 * it, but is not considered to enclose subpackages.
207 *
208 * Other kinds of elements are not currently considered to enclose
209 * any elements; however, that may change as this API or the
210 * programming language evolves.
211 *
212 * <p>Note that elements of certain kinds can be isolated using
213 * methods in {@link ElementFilter}.
214 *
215 * @return the enclosed elements, or an empty list if none
216 * @see Elements#getAllMembers
217 * @jls3 8.8.9 Default Constructor
218 * @jls3 8.9 Enums
219 */
220 List<? extends Element> getEnclosedElements();
222 /**
223 * Returns {@code true} if the argument represents the same
224 * element as {@code this}, or {@code false} otherwise.
225 *
226 * <p>Note that the identity of an element involves implicit state
227 * not directly accessible from the element's methods, including
228 * state about the presence of unrelated types. Element objects
229 * created by different implementations of these interfaces should
230 * <i>not</i> be expected to be equal even if "the same"
231 * element is being modeled; this is analogous to the inequality
232 * of {@code Class} objects for the same class file loaded through
233 * different class loaders.
234 *
235 * @param obj the object to be compared with this element
236 * @return {@code true} if the specified object represents the same
237 * element as this
238 */
239 boolean equals(Object obj);
241 /**
242 * Obeys the general contract of {@link Object#hashCode Object.hashCode}.
243 *
244 * @see #equals
245 */
246 int hashCode();
248 /**
249 * Applies a visitor to this element.
250 *
251 * @param <R> the return type of the visitor's methods
252 * @param <P> the type of the additional parameter to the visitor's methods
253 * @param v the visitor operating on this element
254 * @param p additional parameter to the visitor
255 * @return a visitor-specified result
256 */
257 <R, P> R accept(ElementVisitor<R, P> v, P p);
258 }