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 * @revised 9 127 * @spec JPMS 128 */ 129 Name getSimpleName(); 130 131 /** 132 * Returns the innermost element 133 * within which this element is, loosely speaking, enclosed. 134 * <ul> 135 * <li> If this element is one whose declaration is lexically enclosed 136 * immediately within the declaration of another element, that other 137 * element is returned. 138 * 139 * <li> If this is a {@linkplain TypeElement#getEnclosingElement 140 * top-level type}, its package is returned. 141 * 142 * <li> If this is a {@linkplain 143 * PackageElement#getEnclosingElement package}, its module is 144 * returned if such a module exists. Otherwise, {@code null} is returned. 145 * 146 * <li> If this is a {@linkplain 147 * TypeParameterElement#getEnclosingElement type parameter}, 148 * {@linkplain TypeParameterElement#getGenericElement the 149 * generic element} of the type parameter is returned. 150 * 151 * <li> If this is a {@linkplain 152 * VariableElement#getEnclosingElement method or constructor 153 * parameter}, {@linkplain ExecutableElement the executable 154 * element} which declares the parameter is returned. 155 * 156 * <li> If this is a {@linkplain ModuleElement#getEnclosingElement 157 * module}, {@code null} is returned. 158 * 159 * </ul> 160 * 161 * @return the enclosing element, or {@code null} if there is none 162 * @see Elements#getPackageOf 163 * @revised 9 164 * @spec JPMS 165 */ 166 Element getEnclosingElement(); 167 168 /** 169 * Returns the elements that are, loosely speaking, directly 170 * enclosed by this element. 171 * 172 * A {@linkplain TypeElement#getEnclosedElements class or 173 * interface} is considered to enclose the fields, methods, 174 * constructors, and member types that it directly declares. 175 * 176 * A {@linkplain PackageElement#getEnclosedElements package} 177 * encloses the top-level classes and interfaces within it, but is 178 * not considered to enclose subpackages. 179 * 180 * A {@linkplain ModuleElement#getEnclosedElements module} 181 * encloses packages within it. 182 * 183 * Enclosed elements may include implicitly declared {@linkplain 184 * Elements.Origin#MANDATED mandated} elements. 185 * 186 * Other kinds of elements are not currently considered to enclose 187 * any elements; however, that may change as this API or the 188 * programming language evolves. 189 * 190 * @apiNote Elements of certain kinds can be isolated using 191 * methods in {@link ElementFilter}. 192 * 193 * @return the enclosed elements, or an empty list if none 194 * @see TypeElement#getEnclosedElements 195 * @see PackageElement#getEnclosedElements 196 * @see ModuleElement#getEnclosedElements 197 * @see Elements#getAllMembers 198 * @jls 8.8.9 Default Constructor 199 * @jls 8.9 Enums 200 * @revised 9 201 * @spec JPMS 202 */ 203 List<? extends Element> getEnclosedElements(); 204 205 /** 206 * Returns {@code true} if the argument represents the same 207 * element as {@code this}, or {@code false} otherwise. 208 * 209 * @apiNote The identity of an element involves implicit state 210 * not directly accessible from the element's methods, including 211 * state about the presence of unrelated types. Element objects 212 * created by different implementations of these interfaces should 213 * <i>not</i> be expected to be equal even if "the same" 214 * element is being modeled; this is analogous to the inequality 215 * of {@code Class} objects for the same class file loaded through 216 * different class loaders. 217 * 218 * @param obj the object to be compared with this element 219 * @return {@code true} if the specified object represents the same 220 * element as this 221 */ 222 @Override 223 boolean equals(Object obj); 224 225 /** 226 * Obeys the general contract of {@link Object#hashCode Object.hashCode}. 227 * 228 * @see #equals 229 */ 230 @Override 231 int hashCode(); 232 233 234 /** 235 * {@inheritDoc} 236 * 237 * <p> To get inherited annotations as well, use {@link 238 * Elements#getAllAnnotationMirrors(Element) 239 * getAllAnnotationMirrors}. 240 * 241 * @since 1.6 242 */ 243 @Override 244 List<? extends AnnotationMirror> getAnnotationMirrors(); 245 246 /** 247 * {@inheritDoc} 248 * @since 1.6 249 */ 250 @Override 251 <A extends Annotation> A getAnnotation(Class<A> annotationType); 252 253 /** 254 * Applies a visitor to this element. 255 * 256 * @param <R> the return type of the visitor's methods 257 * @param <P> the type of the additional parameter to the visitor's methods 258 * @param v the visitor operating on this element 259 * @param p additional parameter to the visitor 260 * @return a visitor-specified result 261 */ 262 <R, P> R accept(ElementVisitor<R, P> v, P p); 263 }