001 /*
002 * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.lang.model.element;
027
028 import java.lang.annotation.Annotation;
029 import java.lang.annotation.AnnotationTypeMismatchException;
030 import java.lang.annotation.IncompleteAnnotationException;
031 import java.util.List;
032 import java.util.Set;
033
034 import javax.lang.model.element.Modifier;
035 import javax.lang.model.type.*;
036 import javax.lang.model.util.*;
037
038 /**
039 * Represents a program element such as a package, class, or method.
040 * Each element represents a static, language-level construct
041 * (and not, for example, a runtime construct of the virtual machine).
042 *
043 * <p> Elements should be compared using the {@link #equals(Object)}
044 * method. There is no guarantee that any particular element will
045 * always be represented by the same object.
046 *
047 * <p> To implement operations based on the class of an {@code
048 * Element} object, either use a {@linkplain ElementVisitor visitor} or
049 * use the result of the {@link #getKind} method. Using {@code
050 * instanceof} is <em>not</em> necessarily a reliable idiom for
051 * determining the effective class of an object in this modeling
052 * hierarchy since an implementation may choose to have a single object
053 * implement multiple {@code Element} subinterfaces.
054 *
055 * @author Joseph D. Darcy
056 * @author Scott Seligman
057 * @author Peter von der Ahé
058 * @version 1.13 07/05/05
059 * @see Elements
060 * @see TypeMirror
061 * @since 1.6
062 */
063 public interface Element {
064
065 /**
066 * Returns the type defined by this element.
067 *
068 * <p> A generic element defines a family of types, not just one.
069 * If this is a generic element, a <i>prototypical</i> type is
070 * returned. This is the element's invocation on the
071 * type variables corresponding to its own formal type parameters.
072 * For example,
073 * for the generic class element {@code C<N extends Number>},
074 * the parameterized type {@code C<N>} is returned.
075 * The {@link Types} utility interface has more general methods
076 * for obtaining the full range of types defined by an element.
077 *
078 * @see Types
079 *
080 * @return the type defined by this element
081 */
082 TypeMirror asType();
083
084 /**
085 * Returns the {@code kind} of this element.
086 *
087 * @return the kind of this element
088 */
089 ElementKind getKind();
090
091 /**
092 * Returns the annotations that are directly present on this element.
093 *
094 * <p> To get inherited annotations as well, use
095 * {@link Elements#getAllAnnotationMirrors(Element) getAllAnnotationMirrors}.
096 *
097 * @see ElementFilter
098 *
099 * @return the annotations directly present on this element;
100 * an empty list if there are none
101 */
102 List<? extends AnnotationMirror> getAnnotationMirrors();
103
104 /**
105 * Returns this element's annotation for the specified type if
106 * such an annotation is present, else {@code null}. The
107 * annotation may be either inherited or directly present on this
108 * element.
109 *
110 * <p> The annotation returned by this method could contain an element
111 * whose value is of type {@code Class}.
112 * This value cannot be returned directly: information necessary to
113 * locate and load a class (such as the class loader to use) is
114 * not available, and the class might not be loadable at all.
115 * Attempting to read a {@code Class} object by invoking the relevant
116 * method on the returned annotation
117 * will result in a {@link MirroredTypeException},
118 * from which the corresponding {@link TypeMirror} may be extracted.
119 * Similarly, attempting to read a {@code Class[]}-valued element
120 * will result in a {@link MirroredTypesException}.
121 *
122 * <blockquote>
123 * <i>Note:</i> This method is unlike others in this and related
124 * interfaces. It operates on runtime reflective information —
125 * representations of annotation types currently loaded into the
126 * VM — rather than on the representations defined by and used
127 * throughout these interfaces. Consequently, calling methods on
128 * the returned annotation object can throw many of the exceptions
129 * that can be thrown when calling methods on an annotation object
130 * returned by core reflection. This method is intended for
131 * callers that are written to operate on a known, fixed set of
132 * annotation types.
133 * </blockquote>
134 *
135 * @param <A> the annotation type
136 * @param annotationType the {@code Class} object corresponding to
137 * the annotation type
138 * @return this element's annotation for the specified annotation
139 * type if present on this element, else {@code null}
140 *
141 * @see #getAnnotationMirrors()
142 * @see java.lang.reflect.AnnotatedElement#getAnnotation
143 * @see EnumConstantNotPresentException
144 * @see AnnotationTypeMismatchException
145 * @see IncompleteAnnotationException
146 * @see MirroredTypeException
147 * @see MirroredTypesException
148 */
149 <A extends Annotation> A getAnnotation(Class<A> annotationType);
150
151 /**
152 * Returns the modifiers of this element, excluding annotations.
153 * Implicit modifiers, such as the {@code public} and {@code static}
154 * modifiers of interface members, are included.
155 *
156 * @return the modifiers of this element, or an empty set if there are none
157 */
158 Set<Modifier> getModifiers();
159
160 /**
161 * Returns the simple (unqualified) name of this element.
162 * The name of a generic type does not include any reference
163 * to its formal type parameters.
164 * For example, the simple name of the type element
165 * {@code java.util.Set<E>} is {@code "Set"}.
166 * If this element represents an unnamed package, an empty name is
167 * returned. If it represents a constructor, the name "{@code
168 * <init>}" is returned. If it represents a static initializer,
169 * the name "{@code <clinit>}" is returned. If it represents an
170 * anonymous class or instance initializer, an empty name is
171 * returned.
172 *
173 * @return the simple name of this element
174 */
175 Name getSimpleName();
176
177 /**
178 * Returns the innermost element
179 * within which this element is, loosely speaking, enclosed.
180 * <ul>
181 * <li> If this element is one whose declaration is lexically enclosed
182 * immediately within the declaration of another element, that other
183 * element is returned.
184 * <li> If this is a top-level type, its package is returned.
185 * <li> If this is a package, {@code null} is returned.
186 * <li> If this is a type parameter, {@code null} is returned.
187 * </ul>
188 *
189 * @return the enclosing element, or {@code null} if there is none
190 * @see Elements#getPackageOf
191 */
192 Element getEnclosingElement();
193
194 /**
195 * Returns the elements that are, loosely speaking, directly
196 * enclosed by this element.
197 *
198 * A class or interface is considered to enclose the fields,
199 * methods, constructors, and member types that it directly
200 * declares. This includes any (implicit) default constructor and
201 * the implicit {@code values} and {@code valueOf} methods of an
202 * enum type.
203 *
204 * A package encloses the top-level classes and interfaces within
205 * it, but is not considered to enclose subpackages.
206 *
207 * Other kinds of elements are not currently considered to enclose
208 * any elements; however, that may change as this API or the
209 * programming language evolves.
210 *
211 * <p>Note that elements of certain kinds can be isolated using
212 * methods in {@link ElementFilter}.
213 *
214 * @return the enclosed elements, or an empty list if none
215 * @see Elements#getAllMembers
216 * @jls3 8.8.9 Default Constructor
217 * @jls3 8.9 Enums
218 */
219 List<? extends Element> getEnclosedElements();
220
221 /**
222 * Returns {@code true} if the argument represents the same
223 * element as {@code this}, or {@code false} otherwise.
224 *
225 * <p>Note that the identity of an element involves implicit state
226 * not directly accessible from the element's methods, including
227 * state about the presence of unrelated types. Element objects
228 * created by different implementations of these interfaces should
229 * <i>not</i> be expected to be equal even if "the same"
230 * element is being modeled; this is analogous to the inequality
231 * of {@code Class} objects for the same class file loaded through
232 * different class loaders.
233 *
234 * @param obj the object to be compared with this element
235 * @return {@code true} if the specified object represents the same
236 * element as this
237 */
238 boolean equals(Object obj);
239
240 /**
241 * Obeys the general contract of {@link Object#hashCode Object.hashCode}.
242 *
243 * @see #equals
244 */
245 int hashCode();
246
247 /**
248 * Applies a visitor to this element.
249 *
250 * @param <R> the return type of the visitor's methods
251 * @param <P> the type of the additional parameter to the visitor's methods
252 * @param v the visitor operating on this element
253 * @param p additional parameter to the visitor
254 * @return a visitor-specified result
255 */
256 <R, P> R accept(ElementVisitor<R, P> v, P p);
257 }
|