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