1 /* 2 * Copyright (c) 2005, 2019, 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 * @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 * @return the type defined by this element 76 */ 77 TypeMirror asType(); 78 79 /** 80 * Returns the {@code kind} of this element. 81 * 82 * @return the kind of this element 83 */ 84 ElementKind getKind(); 85 86 /** 87 * Returns the modifiers of this element, excluding annotations. 88 * Implicit modifiers, such as the {@code public} and {@code static} 89 * modifiers of interface members, are included. 90 * 91 * @return the modifiers of this element, or an empty set if there are none 92 */ 93 Set<Modifier> getModifiers(); 94 95 /** 96 * Returns the simple (unqualified) name of this element. The 97 * name of a generic type does not include any reference to its 98 * formal type parameters. 99 * 100 * For example, the simple name of the type element {@code 101 * java.util.Set<E>} is {@code "Set"}. 102 * 103 * If this element represents an unnamed {@linkplain 104 * PackageElement#getSimpleName package} or unnamed {@linkplain 105 * ModuleElement#getSimpleName module}, an empty name is returned. 106 * 107 * If it represents a {@linkplain ExecutableElement#getSimpleName 108 * constructor}, the name "{@code <init>}" is returned. If it 109 * represents a {@linkplain ExecutableElement#getSimpleName static 110 * initializer}, the name "{@code <clinit>}" is returned. 111 * 112 * If it represents an {@linkplain TypeElement#getSimpleName 113 * anonymous class} or {@linkplain ExecutableElement#getSimpleName 114 * instance initializer}, an empty name is returned. 115 * 116 * @return the simple name of this element 117 * @see PackageElement#getSimpleName 118 * @see ExecutableElement#getSimpleName 119 * @see TypeElement#getSimpleName 120 * @see VariableElement#getSimpleName 121 * @see ModuleElement#getSimpleName 122 * @revised 9 123 * @spec JPMS 124 */ 125 Name getSimpleName(); 126 127 /** 128 * Returns the innermost element 129 * within which this element is, loosely speaking, enclosed. 130 * <ul> 131 * <li> If this element is one whose declaration is lexically enclosed 132 * immediately within the declaration of another element, that other 133 * element is returned. 134 * 135 * <li> If this is a {@linkplain TypeElement#getEnclosingElement 136 * top-level type}, its package is returned. 137 * 138 * <li> If this is a {@linkplain 139 * PackageElement#getEnclosingElement package}, its module is 140 * returned if such a module exists. Otherwise, {@code null} is returned. 141 * 142 * <li> If this is a {@linkplain 143 * TypeParameterElement#getEnclosingElement type parameter}, 144 * {@linkplain TypeParameterElement#getGenericElement the 145 * generic element} of the type parameter is returned. 146 * 147 * <li> If this is a {@linkplain 148 * VariableElement#getEnclosingElement method or constructor 149 * parameter}, {@linkplain ExecutableElement the executable 150 * element} which declares the parameter is returned. 151 * 152 * <li> If this is a {@linkplain ModuleElement#getEnclosingElement 153 * module}, {@code null} is returned. 154 * 155 * </ul> 156 * 157 * @return the enclosing element, or {@code null} if there is none 158 * @see Elements#getPackageOf 159 * @revised 9 160 * @spec JPMS 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 * Enclosed elements may include implicitly declared {@linkplain 180 * Elements.Origin#MANDATED mandated} elements. 181 * 182 * Other kinds of elements are not currently considered to enclose 183 * any elements; however, that may change as this API or the 184 * programming language evolves. 185 * 186 * @apiNote Elements of certain kinds can be isolated using 187 * methods in {@link ElementFilter}. 188 * 189 * @return the enclosed elements, or an empty list if none 190 * @see TypeElement#getEnclosedElements 191 * @see PackageElement#getEnclosedElements 192 * @see ModuleElement#getEnclosedElements 193 * @see Elements#getAllMembers 194 * @jls 8.8.9 Default Constructor 195 * @jls 8.9 Enum Types 196 * @revised 9 197 * @spec JPMS 198 */ 199 List<? extends Element> getEnclosedElements(); 200 201 /** 202 * Returns {@code true} if the argument represents the same 203 * element as {@code this}, or {@code false} otherwise. 204 * 205 * @apiNote The identity of an element involves implicit state 206 * not directly accessible from the element's methods, including 207 * state about the presence of unrelated types. Element objects 208 * created by different implementations of these interfaces should 209 * <i>not</i> be expected to be equal even if "the same" 210 * element is being modeled; this is analogous to the inequality 211 * of {@code Class} objects for the same class file loaded through 212 * different class loaders. 213 * 214 * @param obj the object to be compared with this element 215 * @return {@code true} if the specified object represents the same 216 * element as this 217 */ 218 @Override 219 boolean equals(Object obj); 220 221 /** 222 * Obeys the general contract of {@link Object#hashCode Object.hashCode}. 223 * 224 * @see #equals 225 */ 226 @Override 227 int hashCode(); 228 229 230 /** 231 * {@inheritDoc} 232 * 233 * <p> To get inherited annotations as well, use {@link 234 * Elements#getAllAnnotationMirrors(Element) 235 * getAllAnnotationMirrors}. 236 * 237 * @since 1.6 238 */ 239 @Override 240 List<? extends AnnotationMirror> getAnnotationMirrors(); 241 242 /** 243 * {@inheritDoc} 244 * @since 1.6 245 */ 246 @Override 247 <A extends Annotation> A getAnnotation(Class<A> annotationType); 248 249 /** 250 * Applies a visitor to this element. 251 * 252 * @param <R> the return type of the visitor's methods 253 * @param <P> the type of the additional parameter to the visitor's methods 254 * @param v the visitor operating on this element 255 * @param p additional parameter to the visitor 256 * @return a visitor-specified result 257 */ 258 <R, P> R accept(ElementVisitor<R, P> v, P p); 259 }