KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > lang > model > element > Element


1 /*
2  * @(#)Element.java 1.7 06/08/07
3  *
4  * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package javax.lang.model.element;
9
10
11 import java.lang.annotation.Annotation JavaDoc;
12 import java.lang.annotation.AnnotationTypeMismatchException JavaDoc;
13 import java.lang.annotation.IncompleteAnnotationException JavaDoc;
14 import java.util.List JavaDoc;
15 import java.util.Set JavaDoc;
16
17 import javax.lang.model.element.Modifier;
18 import javax.lang.model.type.*;
19 import javax.lang.model.util.*;
20
21
22 /**
23  * Represents a program element such as a package, class, or method.
24  * Each element represents a static, language-level construct
25  * (and not, for example, a runtime construct of the virtual machine).
26  *
27  * <p> Elements should be compared using the {@link #equals(Object)}
28  * method. There is no guarantee that any particular element will
29  * always be represented by the same object.
30  *
31  * <p> To implement operations based on the class of an {@code
32  * Element} object, either use a {@linkplain ElementVisitor visitor} or
33  * use the result of the {@link #getKind} method. Using {@code
34  * instanceof} is <em>not</em> necessarily a reliable idiom for
35  * determining the effective class of an object in this modeling
36  * hierarchy since an implementation may choose to have a single object
37  * implement multiple {@code Element} subinterfaces.
38  *
39  * @author Joseph D. Darcy
40  * @author Scott Seligman
41  * @author Peter von der Ah&eacute;
42  * @version 1.7 06/08/07
43  * @see Elements
44  * @see TypeMirror
45  * @since 1.6
46  */

47 public interface Element {
48
49     /**
50      * Returns the type defined by this element.
51      *
52      * <p> A generic element defines a family of types, not just one.
53      * If this is a generic element, a <i>prototypical</i> type is
54      * returned. This is the element's invocation on the
55      * type variables corresponding to its own formal type parameters.
56      * For example,
57      * for the generic class element {@code C<N extends Number>},
58      * the parameterized type {@code C<N>} is returned.
59      * The {@link Types} utility interface has more general methods
60      * for obtaining the full range of types defined by an element.
61      *
62      * @see Types
63      *
64      * @return the type defined by this element
65      */

66     TypeMirror asType();
67
68     /**
69      * Returns the {@code kind} of this element.
70      *
71      * @return the kind of this element
72      */

73     ElementKind getKind();
74
75     /**
76      * Returns the annotations that are directly present on this element.
77      *
78      * <p> To get inherited annotations as well, use
79      * {@link Elements#getAllAnnotationMirrors(Element) getAllAnnotationMirrors}.
80      *
81      * @see ElementFilter
82      *
83      * @return the annotations directly present on this element;
84      * an empty list if there are none
85      */

86     List JavaDoc<? extends AnnotationMirror> getAnnotationMirrors();
87
88     /**
89      * Returns this element's annotation for the specified type if
90      * such an annotation is present, else {@code null}. The
91      * annotation may be either inherited or directly present on this
92      * element.
93      *
94      * <p> The annotation returned by this method could contain an element
95      * whose value is of type {@code Class}.
96      * This value cannot be returned directly: information necessary to
97      * locate and load a class (such as the class loader to use) is
98      * not available, and the class might not be loadable at all.
99      * Attempting to read a {@code Class} object by invoking the relevant
100      * method on the returned annotation
101      * will result in a {@link MirroredTypeException},
102      * from which the corresponding {@link TypeMirror} may be extracted.
103      * Similarly, attempting to read a {@code Class[]}-valued element
104      * will result in a {@link MirroredTypesException}.
105      *
106      * <blockquote>
107      * <i>Note:</i> This method is unlike others in this and related
108      * interfaces. It operates on runtime reflective information &mdash;
109      * representations of annotation types currently loaded into the
110      * VM &mdash; rather than on the representations defined by and used
111      * throughout these interfaces. Consequently, calling methods on
112      * the returned annotation object can throw many of the exceptions
113      * that can be thrown when calling methods on an annotation object
114      * returned by core reflection. This method is intended for
115      * callers that are written to operate on a known, fixed set of
116      * annotation types.
117      * </blockquote>
118      *
119      * @param <A> the annotation type
120      * @param annotationType the {@code Class} object corresponding to
121      * the annotation type
122      * @return this element's annotation for the specified annotation
123      * type if present on this element, else {@code null}
124      *
125      * @see #getAnnotationMirrors()
126      * @see java.lang.reflect.AnnotatedElement#getAnnotation
127      * @see EnumConstantNotPresentException
128      * @see AnnotationTypeMismatchException
129      * @see IncompleteAnnotationException
130      * @see MirroredTypeException
131      * @see MirroredTypesException
132      */

133     <A extends Annotation JavaDoc> A getAnnotation(Class JavaDoc<A> annotationType);
134
135     /**
136      * Returns the modifiers of this element, excluding annotations.
137      * Implicit modifiers, such as the {@code public} and {@code static}
138      * modifiers of interface members, are included.
139      *
140      * @return the modifiers of this element, or an empty set if there are none
141      */

142     Set JavaDoc<Modifier> getModifiers();
143
144     /**
145      * Returns the simple (unqualified) name of this element.
146      * The name of a generic type does not include any reference
147      * to its formal type parameters.
148      * For example, the simple name of the type element
149      * {@code java.util.Set<E>} is {@code "Set"}.
150      * If this element represents an unnamed package, an empty name is
151      * returned. If it represents a constructor, the name "{@code
152      * <init>}" is returned. If it represents a static initializer,
153      * the name "{@code <clinit>}" is returned. If it represents an
154      * anonymous class or instance initializer, an empty name is
155      * returned.
156      *
157      * @return the simple name of this element
158      */

159     Name getSimpleName();
160
161     /**
162      * Returns the innermost element
163      * within which this element is, loosely speaking, enclosed.
164      * <ul>
165      * <li> If this element is one whose declaration is lexically enclosed
166      * immediately within the declaration of another element, that other
167      * element is returned.
168      * <li> If this is a top-level type, its package is returned.
169      * <li> If this is a package, {@code null} is returned.
170      * <li> If this is a type parameter, {@code null} is returned.
171      * </ul>
172      *
173      * @return the enclosing element, or {@code null} if there is none
174      * @see Elements#getPackageOf
175      */

176     Element getEnclosingElement();
177
178     /**
179      * Returns the elements that are, loosely speaking, directly
180      * enclosed by this element.
181      *
182      * A class or interface is considered to enclose the fields,
183      * methods, constructors, and member types that it directly
184      * declares. This includes any (implicit) default constructor and
185      * the implicit {@code values} and {@code valueOf} methods of an
186      * enum type.
187      *
188      * A package encloses the top-level classes and interfaces within
189      * it, but is not considered to enclose subpackages.
190      *
191      * Other kinds of elements are not currently considered to enclose
192      * any elements; however, that may change as this API or the
193      * programming language evolves.
194      *
195      * <p>Note that elements of certain kinds can be isolated using
196      * methods in {@link ElementFilter}.
197      *
198      * @return the enclosed elements, or an empty list if none
199      * @see Elements#getAllMembers
200      * @jls3 8.8.9 Default Constructor
201      * @jls3 8.9 Enums
202      */

203     List JavaDoc<? 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      * <p>Note that 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     boolean equals(Object JavaDoc obj);
223
224     /**
225      * Obeys the general contract of {@link Object#hashCode Object.hashCode}.
226      *
227      * @see #equals
228      */

229     int hashCode();
230
231     /**
232      * Applies a visitor to this element.
233      *
234      * @param <R> the return type of the visitor's methods
235      * @param <P> the type of the additional parameter to the visitor's methods
236      * @param v the visitor operating on this element
237      * @param p additional parameter to the visitor
238      * @return a visitor-specified result
239      */

240     <R, P> R accept(ElementVisitor<R, P> v, P p);
241 }
242
Popular Tags