1 /* 2 * Copyright (c) 2005, 2020, 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 * Represents a program element such as a module, package, class, or method. 40 * Each element represents a compile-time language-level construct 41 * (and not, for example, a runtime construct of the virtual machine). 42 * 43 * <p> Elements should be compared using the {@link #equals(Object)} 44 * method. There is no guarantee that any particular element will 45 * always be represented by the same object. 46 * 47 * <p> To implement operations based on the class of an {@code 48 * Element} object, either use a {@linkplain ElementVisitor visitor} or 49 * use the result of the {@link #getKind} method. Using {@code 50 * instanceof} is <em>not</em> necessarily a reliable idiom for 51 * determining the effective class of an object in this modeling 52 * hierarchy since an implementation may choose to have a single object 53 * implement multiple {@code Element} subinterfaces. 54 * 55 * @author Joseph D. Darcy 56 * @author Scott Seligman 57 * @author Peter von der Ahé 58 * @see Elements 59 * @see TypeMirror 60 * @since 1.6 61 */ 62 public interface Element extends javax.lang.model.AnnotatedConstruct { 63 /** 64 * Returns the type defined by this element. 65 * @return the type defined by this element 66 * 67 * @see Types 68 * @see ExecutableElement#asType 69 * @see ModuleElement#asType 70 * @see PackageElement#asType 71 * @see TypeElement#asType 72 * @see TypeParameterElement#asType 73 * @see VariableElement#asType 74 */ 75 TypeMirror asType(); 76 77 /** 78 * Returns the {@code kind} of this element. 79 * 80 * <ul> 81 * 82 * <li> The kind of a {@linkplain PackageElement package} is 83 * {@link ElementKind#PACKAGE PACKAGE}. 84 * 85 * <li> The kind of a {@linkplain ModuleElement module} is {@link 86 * ElementKind#MODULE MODULE}. 87 * 88 * <li> The kind of a {@linkplain TypeElement type element} is one 89 * of {@link ElementKind#ANNOTATION_TYPE ANNOTATION_TYPE}, {@link 90 * ElementKind#CLASS CLASS}, {@link ElementKind#ENUM ENUM}, {@link 91 * ElementKind#INTERFACE INTERFACE}, or {@link ElementKind#RECORD 92 * RECORD}. 93 * 94 * <li> The kind of a {@linkplain VariableElement variable} is one 95 * of {@link ElementKind#ENUM_CONSTANT ENUM_CONSTANT}, {@link 96 * ElementKind#EXCEPTION_PARAMETER EXCEPTION_PARAMETER}, {@link 97 * ElementKind#FIELD FIELD}, {@link ElementKind#LOCAL_VARIABLE 98 * LOCAL_VARIABLE}, {@link ElementKind#PARAMETER PARAMETER}, 99 * {@link ElementKind#RESOURCE_VARIABLE RESOURCE_VARIABLE}, or 100 * {@link ElementKind#BINDING_VARIABLE BINDING_VARIABLE}. 101 * 102 * <li> The kind of an {@linkplain ExecutableElement executable} 103 * is one of {@link ElementKind#CONSTRUCTOR CONSTRUCTOR}, {@link 104 * ElementKind#INSTANCE_INIT INSTANCE_INIT}, {@link 105 * ElementKind#METHOD METHOD}, or {@link ElementKind#STATIC_INIT 106 * STATIC_INIT}. 107 * 108 * <li> The kind of a {@linkplain TypeParameterElement type parameter} is 109 * {@link ElementKind#TYPE_PARAMETER TYPE_PARAMETER}. 110 * 111 * <li> The kind of a {@linkplain RecordComponentElement record 112 * component} is {@link ElementKind#RECORD_COMPONENT 113 * RECORD_COMPONENT}. 114 * 115 * </ul> 116 * 117 * @return the kind of this element 118 */ 119 ElementKind getKind(); 120 121 /** 122 * Returns the modifiers of this element, excluding annotations. 123 * Implicit modifiers, such as the {@code public} and {@code static} 124 * modifiers of interface members, are included. 125 * 126 * @return the modifiers of this element, or an empty set if there are none 127 */ 128 Set<Modifier> getModifiers(); 129 130 /** 131 * Returns the simple (unqualified) name of this element. The 132 * name of a generic type does not include any reference to its 133 * formal type parameters. 134 * 135 * For example, the simple name of the type element {@code 136 * java.util.Set<E>} is {@code "Set"}. 137 * 138 * If this element represents an unnamed {@linkplain 139 * PackageElement#getSimpleName package} or unnamed {@linkplain 140 * ModuleElement#getSimpleName module}, an <a href=Name.html#empty_name>empty name</a> is returned. 141 * 142 * If it represents a {@linkplain ExecutableElement#getSimpleName 143 * constructor}, the name "{@code <init>}" is returned. If it 144 * represents a {@linkplain ExecutableElement#getSimpleName static 145 * initializer}, the name "{@code <clinit>}" is returned. 146 * 147 * If it represents an {@linkplain TypeElement#getSimpleName 148 * anonymous class} or {@linkplain ExecutableElement#getSimpleName 149 * instance initializer}, an <a href=Name.html#empty_name>empty name</a> is returned. 150 * 151 * @return the simple name of this element 152 * @see PackageElement#getSimpleName 153 * @see ExecutableElement#getSimpleName 154 * @see TypeElement#getSimpleName 155 * @see VariableElement#getSimpleName 156 * @see ModuleElement#getSimpleName 157 * @see RecordComponentElement#getSimpleName 158 * @revised 9 159 * @spec JPMS 160 */ 161 Name getSimpleName(); 162 163 /** 164 * Returns the innermost element 165 * within which this element is, loosely speaking, enclosed. 166 * <ul> 167 * <li> If this element is one whose declaration is lexically enclosed 168 * immediately within the declaration of another element, that other 169 * element is returned. 170 * 171 * <li> If this is a {@linkplain TypeElement#getEnclosingElement 172 * top-level type}, its package is returned. 173 * 174 * <li> If this is a {@linkplain 175 * PackageElement#getEnclosingElement package}, its module is 176 * returned if such a module exists. Otherwise, {@code null} is returned. 177 * 178 * <li> If this is a {@linkplain 179 * TypeParameterElement#getEnclosingElement type parameter}, 180 * {@linkplain TypeParameterElement#getGenericElement the 181 * generic element} of the type parameter is returned. 182 * 183 * <li> If this is a {@linkplain 184 * VariableElement#getEnclosingElement method or constructor 185 * parameter}, {@linkplain ExecutableElement the executable 186 * element} which declares the parameter is returned. 187 * 188 * <li> If this is a {@linkplain 189 * RecordComponentElement#getEnclosingElement record component}, 190 * {@linkplain TypeElement the type} which declares the 191 * record component is returned. 192 * 193 * <li> If this is a {@linkplain ModuleElement#getEnclosingElement 194 * module}, {@code null} is returned. 195 * 196 * </ul> 197 * 198 * @return the enclosing element, or {@code null} if there is none 199 * @see Elements#getPackageOf 200 * @revised 9 201 * @spec JPMS 202 */ 203 Element getEnclosingElement(); 204 205 /** 206 * Returns the elements that are, loosely speaking, directly 207 * enclosed by this element. 208 * 209 * A {@linkplain TypeElement#getEnclosedElements class or 210 * interface} is considered to enclose the fields, methods, 211 * constructors, record components, and member types that it directly declares. 212 * 213 * A {@linkplain PackageElement#getEnclosedElements package} 214 * encloses the top-level classes and interfaces within it, but is 215 * not considered to enclose subpackages. 216 * 217 * A {@linkplain ModuleElement#getEnclosedElements module} 218 * encloses packages within it. 219 * 220 * Enclosed elements may include implicitly declared {@linkplain 221 * Elements.Origin#MANDATED mandated} elements. 222 * 223 * Other kinds of elements are not currently considered to enclose 224 * any elements; however, that may change as this API or the 225 * programming language evolves. 226 * 227 * @apiNote Elements of certain kinds can be isolated using 228 * methods in {@link ElementFilter}. 229 * 230 * @return the enclosed elements, or an empty list if none 231 * @see TypeElement#getEnclosedElements 232 * @see PackageElement#getEnclosedElements 233 * @see ModuleElement#getEnclosedElements 234 * @see Elements#getAllMembers 235 * @jls 8.8.9 Default Constructor 236 * @jls 8.9 Enum Types 237 * @revised 9 238 * @spec JPMS 239 */ 240 List<? extends Element> getEnclosedElements(); 241 242 /** 243 * Returns {@code true} if the argument represents the same 244 * element as {@code this}, or {@code false} otherwise. 245 * 246 * @apiNote The identity of an element involves implicit state 247 * not directly accessible from the element's methods, including 248 * state about the presence of unrelated types. Element objects 249 * created by different implementations of these interfaces should 250 * <i>not</i> be expected to be equal even if "the same" 251 * element is being modeled; this is analogous to the inequality 252 * of {@code Class} objects for the same class file loaded through 253 * different class loaders. 254 * 255 * @param obj the object to be compared with this element 256 * @return {@code true} if the specified object represents the same 257 * element as this 258 */ 259 @Override 260 boolean equals(Object obj); 261 262 /** 263 * Obeys the general contract of {@link Object#hashCode Object.hashCode}. 264 * 265 * @see #equals 266 */ 267 @Override 268 int hashCode(); 269 270 /** 271 * {@inheritDoc} 272 * 273 * <p>To get inherited annotations as well, use {@link 274 * Elements#getAllAnnotationMirrors(Element) 275 * getAllAnnotationMirrors}. 276 * 277 * <p>Note that any annotations returned by this method are 278 * declaration annotations. 279 * 280 * @since 1.6 281 */ 282 @Override 283 List<? extends AnnotationMirror> getAnnotationMirrors(); 284 285 /** 286 * {@inheritDoc} 287 * 288 * <p>Note that any annotation returned by this method is a 289 * declaration annotation. 290 * 291 * @since 1.6 292 */ 293 @Override 294 <A extends Annotation> A getAnnotation(Class<A> annotationType); 295 296 /** 297 * {@inheritDoc} 298 * 299 * <p>Note that any annotations returned by this method are 300 * declaration annotations. 301 * 302 * @since 8 303 */ 304 @Override 305 <A extends Annotation> A[] getAnnotationsByType(Class<A> annotationType); 306 307 /** 308 * Applies a visitor to this element. 309 * 310 * @param <R> the return type of the visitor's methods 311 * @param <P> the type of the additional parameter to the visitor's methods 312 * @param v the visitor operating on this element 313 * @param p additional parameter to the visitor 314 * @return a visitor-specified result 315 */ 316 <R, P> R accept(ElementVisitor<R, P> v, P p); 317 }