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: }
|