Elements.java revision 3976:65d446c80cdf
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 26package javax.lang.model.util; 27 28 29import java.util.List; 30import java.util.Map; 31 32import javax.lang.model.AnnotatedConstruct; 33import javax.lang.model.element.*; 34 35 36/** 37 * Utility methods for operating on program elements. 38 * 39 * <p><b>Compatibility Note:</b> Methods may be added to this interface 40 * in future releases of the platform. 41 * 42 * @author Joseph D. Darcy 43 * @author Scott Seligman 44 * @author Peter von der Ahé 45 * @see javax.annotation.processing.ProcessingEnvironment#getElementUtils 46 * @since 1.6 47 */ 48public interface Elements { 49 50 /** 51 * Returns a package given its fully qualified name if the package is unique in the environment. 52 * If running with modules, all modules in the modules graph are searched for matching packages. 53 * 54 * @param name fully qualified package name, or an empty string for an unnamed package 55 * @return the specified package, or {@code null} if it cannot be uniquely found 56 */ 57 PackageElement getPackageElement(CharSequence name); 58 59 /** 60 * Returns a package given its fully qualified name, as seen from the given module. 61 * 62 * @implSpec The default implementation of this method returns 63 * {@code null}. 64 * 65 * @param name fully qualified package name, or an empty string for an unnamed package 66 * @param module module relative to which the lookup should happen 67 * @return the specified package, or {@code null} if it cannot be found 68 * @since 9 69 */ 70 default PackageElement getPackageElement(ModuleElement module, CharSequence name) { 71 return null; 72 } 73 74 /** 75 * Returns a type element given its canonical name if the type element is unique in the environment. 76 * If running with modules, all modules in the modules graph are searched for matching 77 * type elements. 78 * 79 * @param name the canonical name 80 * @return the named type element, or {@code null} if it cannot be uniquely found 81 */ 82 TypeElement getTypeElement(CharSequence name); 83 84 /** 85 * Returns a type element given its canonical name, as seen from the given module. 86 * 87 * @implSpec The default implementation of this method returns 88 * {@code null}. 89 * 90 * @param name the canonical name 91 * @param module module relative to which the lookup should happen 92 * @return the named type element, or {@code null} if it cannot be found 93 * @since 9 94 */ 95 default TypeElement getTypeElement(ModuleElement module, CharSequence name) { 96 return null; 97 } 98 99 /** 100 * Returns a module element given its fully qualified name. 101 * If the named module cannot be found, null is returned. One situation where a module 102 * cannot be found is if the environment does not include modules, such as 103 * an annotation processing environment configured for 104 * a {@linkplain 105 * javax.annotation.processing.ProcessingEnvironment#getSourceVersion 106 * source version} without modules. 107 * 108 * @implSpec The default implementation of this method returns 109 * {@code null}. 110 * 111 * @param name the name 112 * @return the named module element, or {@code null} if it cannot be found 113 * @since 9 114 * @spec JPMS 115 */ 116 default ModuleElement getModuleElement(CharSequence name) { 117 return null; 118 } 119 120 /** 121 * Returns the values of an annotation's elements, including defaults. 122 * 123 * @see AnnotationMirror#getElementValues() 124 * @param a annotation to examine 125 * @return the values of the annotation's elements, including defaults 126 */ 127 Map<? extends ExecutableElement, ? extends AnnotationValue> 128 getElementValuesWithDefaults(AnnotationMirror a); 129 130 /** 131 * Returns the text of the documentation ("Javadoc") 132 * comment of an element. 133 * 134 * <p> A documentation comment of an element is a comment that 135 * begins with "{@code /**}" , ends with a separate 136 * "<code>*/</code>", and immediately precedes the element, 137 * ignoring white space. Therefore, a documentation comment 138 * contains at least three"{@code *}" characters. The text 139 * returned for the documentation comment is a processed form of 140 * the comment as it appears in source code. The leading "{@code 141 * /**}" and trailing "<code>*/</code>" are removed. For lines 142 * of the comment starting after the initial "{@code /**}", 143 * leading white space characters are discarded as are any 144 * consecutive "{@code *}" characters appearing after the white 145 * space or starting the line. The processed lines are then 146 * concatenated together (including line terminators) and 147 * returned. 148 * 149 * @param e the element being examined 150 * @return the documentation comment of the element, or {@code null} 151 * if there is none 152 * @jls 3.6 White Space 153 */ 154 String getDocComment(Element e); 155 156 /** 157 * Returns {@code true} if the element is deprecated, {@code false} otherwise. 158 * 159 * @param e the element being examined 160 * @return {@code true} if the element is deprecated, {@code false} otherwise 161 */ 162 boolean isDeprecated(Element e); 163 164 /** 165 * Returns the <em>origin</em> of the given element. 166 * 167 * <p>Note that if this method returns {@link Origin#EXPLICIT 168 * EXPLICIT} and the element was created from a class file, then 169 * the element may not, in fact, correspond to an explicitly 170 * declared construct in source code. This is due to limitations 171 * of the fidelity of the class file format in preserving 172 * information from source code. For example, at least some 173 * versions of the class file format do not preserve whether a 174 * constructor was explicitly declared by the programmer or was 175 * implicitly declared as the <em>default constructor</em>. 176 * 177 * @implSpec The default implementation of this method returns 178 * {@link Origin#EXPLICIT EXPLICIT}. 179 * 180 * @param e the element being examined 181 * @return the origin of the given element 182 * @since 9 183 */ 184 default Origin getOrigin(Element e) { 185 return Origin.EXPLICIT; 186 } 187 188 /** 189 * Returns the <em>origin</em> of the given annotation mirror. 190 * 191 * An annotation mirror is {@linkplain Origin#MANDATED mandated} 192 * if it is an implicitly declared <em>container annotation</em> 193 * used to hold repeated annotations of a repeatable annotation 194 * type. 195 * 196 * <p>Note that if this method returns {@link Origin#EXPLICIT 197 * EXPLICIT} and the annotation mirror was created from a class 198 * file, then the element may not, in fact, correspond to an 199 * explicitly declared construct in source code. This is due to 200 * limitations of the fidelity of the class file format in 201 * preserving information from source code. For example, at least 202 * some versions of the class file format do not preserve whether 203 * an annotation was explicitly declared by the programmer or was 204 * implicitly declared as a <em>container annotation</em>. 205 * 206 * @implSpec The default implementation of this method returns 207 * {@link Origin#EXPLICIT EXPLICIT}. 208 * 209 * @param c the construct the annotation mirror modifies 210 * @param a the annotation mirror being examined 211 * @return the origin of the given annotation mirror 212 * @jls 9.6.3 Repeatable Annotation Types 213 * @jls 9.7.5 Multiple Annotations of the Same Type 214 * @since 9 215 */ 216 default Origin getOrigin(AnnotatedConstruct c, 217 AnnotationMirror a) { 218 return Origin.EXPLICIT; 219 } 220 221 /** 222 * Returns the <em>origin</em> of the given module directive. 223 * 224 * <p>Note that if this method returns {@link Origin#EXPLICIT 225 * EXPLICIT} and the module directive was created from a class 226 * file, then the module directive may not, in fact, correspond to 227 * an explicitly declared construct in source code. This is due to 228 * limitations of the fidelity of the class file format in 229 * preserving information from source code. For example, at least 230 * some versions of the class file format do not preserve whether 231 * a {@code uses} directive was explicitly declared by the 232 * programmer or was added as a synthetic construct. 233 * 234 * <p>Note that an implementation may not be able to reliably 235 * determine the origin status of the directive if the directive 236 * is created from a class file due to limitations of the fidelity 237 * of the class file format in preserving information from source 238 * code. 239 * 240 * @implSpec The default implementation of this method returns 241 * {@link Origin#EXPLICIT EXPLICIT}. 242 * 243 * @param m the module of the directive 244 * @param directive the module directive being examined 245 * @return the origin of the given directive 246 * @since 9 247 */ 248 default Origin getOrigin(ModuleElement m, 249 ModuleElement.Directive directive) { 250 return Origin.EXPLICIT; 251 } 252 253 /** 254 * The <em>origin</em> of an element or other language model 255 * item. The origin of an element or item models how a construct 256 * in a program is declared in the source code, explicitly, 257 * implicitly, etc. 258 * 259 * <p>Note that it is possible additional kinds of origin values 260 * will be added in future versions of the platform. 261 * 262 * @jls 13.1 The Form of a Binary 263 * @since 9 264 */ 265 public enum Origin { 266 /** 267 * Describes a construct explicitly declared in source code. 268 */ 269 EXPLICIT, 270 271 /** 272 * A mandated construct is one that is not explicitly declared 273 * in the source code, but whose presence is mandated by the 274 * specification. Such a construct is said to be implicitly 275 * declared. 276 * 277 * One example of a mandated element is a <em>default 278 * constructor</em> in a class that contains no explicit 279 * constructor declarations. 280 * 281 * Another example of a mandated construct is an implicitly 282 * declared <em>container annotation</em> used to hold 283 * multiple annotations of a repeatable annotation type. 284 * 285 * @jls 8.8.9 Default Constructor 286 * @jls 8.9.3 Enum Members 287 * @jls 9.6.3 Repeatable Annotation Types 288 * @jls 9.7.5 Multiple Annotations of the Same Type 289 */ 290 MANDATED, 291 292 /** 293 * A synthetic construct is one that is neither implicitly nor 294 * explicitly declared in the source code. Such a construct is 295 * typically a translation artifact created by a compiler. 296 */ 297 SYNTHETIC; 298 299 /** 300 * Returns {@code true} for values corresponding to constructs 301 * that are implicitly or explicitly declared, {@code false} 302 * otherwise. 303 * @return {@code true} for {@link EXPLICIT} and {@link 304 * MANDATED}, {@code false} otherwise. 305 */ 306 public boolean isDeclared() { 307 return this != SYNTHETIC; 308 } 309 } 310 311 /** 312 * Returns {@code true} if the executable element is a bridge 313 * method, {@code false} otherwise. 314 * 315 * @implSpec The default implementation of this method returns {@code false}. 316 * 317 * @param e the executable being examined 318 * @return {@code true} if the executable element is a bridge 319 * method, {@code false} otherwise 320 * @since 9 321 */ 322 default boolean isBridge(ExecutableElement e) { 323 return false; 324 } 325 326 /** 327 * Returns the <i>binary name</i> of a type element. 328 * 329 * @param type the type element being examined 330 * @return the binary name 331 * 332 * @see TypeElement#getQualifiedName 333 * @jls 13.1 The Form of a Binary 334 */ 335 Name getBinaryName(TypeElement type); 336 337 338 /** 339 * Returns the package of an element. The package of a package is 340 * itself. 341 * 342 * @param type the element being examined 343 * @return the package of an element 344 */ 345 PackageElement getPackageOf(Element type); 346 347 /** 348 * Returns the module of an element. The module of a module is 349 * itself. 350 * If there is no module for the element, null is returned. One situation where there is 351 * no module for an element is if the environment does not include modules, such as 352 * an annotation processing environment configured for 353 * a {@linkplain 354 * javax.annotation.processing.ProcessingEnvironment#getSourceVersion 355 * source version} without modules. 356 * 357 * @implSpec The default implementation of this method returns 358 * {@code null}. 359 * 360 * @param type the element being examined 361 * @return the module of an element 362 * @since 9 363 * @spec JPMS 364 */ 365 default ModuleElement getModuleOf(Element type) { 366 return null; 367 } 368 369 /** 370 * Returns all members of a type element, whether inherited or 371 * declared directly. For a class the result also includes its 372 * constructors, but not local or anonymous classes. 373 * 374 * @apiNote Elements of certain kinds can be isolated using 375 * methods in {@link ElementFilter}. 376 * 377 * @param type the type being examined 378 * @return all members of the type 379 * @see Element#getEnclosedElements 380 */ 381 List<? extends Element> getAllMembers(TypeElement type); 382 383 /** 384 * Returns all annotations <i>present</i> on an element, whether 385 * directly present or present via inheritance. 386 * 387 * @param e the element being examined 388 * @return all annotations of the element 389 * @see Element#getAnnotationMirrors 390 * @see javax.lang.model.AnnotatedConstruct 391 */ 392 List<? extends AnnotationMirror> getAllAnnotationMirrors(Element e); 393 394 /** 395 * Tests whether one type, method, or field hides another. 396 * 397 * @param hider the first element 398 * @param hidden the second element 399 * @return {@code true} if and only if the first element hides 400 * the second 401 */ 402 boolean hides(Element hider, Element hidden); 403 404 /** 405 * Tests whether one method, as a member of a given type, 406 * overrides another method. 407 * When a non-abstract method overrides an abstract one, the 408 * former is also said to <i>implement</i> the latter. 409 * 410 * <p> In the simplest and most typical usage, the value of the 411 * {@code type} parameter will simply be the class or interface 412 * directly enclosing {@code overrider} (the possibly-overriding 413 * method). For example, suppose {@code m1} represents the method 414 * {@code String.hashCode} and {@code m2} represents {@code 415 * Object.hashCode}. We can then ask whether {@code m1} overrides 416 * {@code m2} within the class {@code String} (it does): 417 * 418 * <blockquote> 419 * {@code assert elements.overrides(m1, m2, 420 * elements.getTypeElement("java.lang.String")); } 421 * </blockquote> 422 * 423 * A more interesting case can be illustrated by the following example 424 * in which a method in type {@code A} does not override a 425 * like-named method in type {@code B}: 426 * 427 * <blockquote> 428 * {@code class A { public void m() {} } }<br> 429 * {@code interface B { void m(); } }<br> 430 * ...<br> 431 * {@code m1 = ...; // A.m }<br> 432 * {@code m2 = ...; // B.m }<br> 433 * {@code assert ! elements.overrides(m1, m2, 434 * elements.getTypeElement("A")); } 435 * </blockquote> 436 * 437 * When viewed as a member of a third type {@code C}, however, 438 * the method in {@code A} does override the one in {@code B}: 439 * 440 * <blockquote> 441 * {@code class C extends A implements B {} }<br> 442 * ...<br> 443 * {@code assert elements.overrides(m1, m2, 444 * elements.getTypeElement("C")); } 445 * </blockquote> 446 * 447 * @param overrider the first method, possible overrider 448 * @param overridden the second method, possibly being overridden 449 * @param type the type of which the first method is a member 450 * @return {@code true} if and only if the first method overrides 451 * the second 452 * @jls 8.4.8 Inheritance, Overriding, and Hiding 453 * @jls 9.4.1 Inheritance and Overriding 454 */ 455 boolean overrides(ExecutableElement overrider, ExecutableElement overridden, 456 TypeElement type); 457 458 /** 459 * Returns the text of a <i>constant expression</i> representing a 460 * primitive value or a string. 461 * The text returned is in a form suitable for representing the value 462 * in source code. 463 * 464 * @param value a primitive value or string 465 * @return the text of a constant expression 466 * @throws IllegalArgumentException if the argument is not a primitive 467 * value or string 468 * 469 * @see VariableElement#getConstantValue() 470 */ 471 String getConstantExpression(Object value); 472 473 /** 474 * Prints a representation of the elements to the given writer in 475 * the specified order. The main purpose of this method is for 476 * diagnostics. The exact format of the output is <em>not</em> 477 * specified and is subject to change. 478 * 479 * @param w the writer to print the output to 480 * @param elements the elements to print 481 */ 482 void printElements(java.io.Writer w, Element... elements); 483 484 /** 485 * Return a name with the same sequence of characters as the 486 * argument. 487 * 488 * @param cs the character sequence to return as a name 489 * @return a name with the same sequence of characters as the argument 490 */ 491 Name getName(CharSequence cs); 492 493 /** 494 * Returns {@code true} if the type element is a functional interface, {@code false} otherwise. 495 * 496 * @param type the type element being examined 497 * @return {@code true} if the element is a functional interface, {@code false} otherwise 498 * @jls 9.8 Functional Interfaces 499 * @since 1.8 500 */ 501 boolean isFunctionalInterface(TypeElement type); 502} 503