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  ;
12  import java.lang.annotation.AnnotationTypeMismatchException  ;
13  import java.lang.annotation.IncompleteAnnotationException  ;
14  import java.util.List  ;
15  import java.util.Set  ;
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  <? 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  > A getAnnotation(Class  <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  <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  <? 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   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags