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