Elements.java revision 3825:6b18edbd77b7
1194246Smarius/* 2194246Smarius * Copyright (c) 2005, 2016, Oracle and/or its affiliates. All rights reserved. 3194246Smarius * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4194246Smarius * 5194246Smarius * This code is free software; you can redistribute it and/or modify it 6194246Smarius * under the terms of the GNU General Public License version 2 only, as 7194246Smarius * published by the Free Software Foundation. Oracle designates this 8194246Smarius * particular file as subject to the "Classpath" exception as provided 9194246Smarius * by Oracle in the LICENSE file that accompanied this code. 10194246Smarius * 11194246Smarius * This code is distributed in the hope that it will be useful, but WITHOUT 12194246Smarius * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13194246Smarius * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14194246Smarius * version 2 for more details (a copy is included in the LICENSE file that 15194246Smarius * accompanied this code). 16194246Smarius * 17194246Smarius * You should have received a copy of the GNU General Public License version 18194246Smarius * 2 along with this work; if not, write to the Free Software Foundation, 19194246Smarius * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20194246Smarius * 21194246Smarius * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22194246Smarius * or visit www.oracle.com if you need additional information or have any 23194246Smarius * questions. 24194246Smarius */ 25194246Smarius 26194246Smariuspackage javax.lang.model.util; 27194246Smarius 28194246Smarius 29194246Smariusimport java.util.List; 30194246Smariusimport java.util.Map; 31194246Smarius 32194246Smariusimport javax.lang.model.AnnotatedConstruct; 33194246Smariusimport javax.lang.model.element.*; 34194246Smarius 35194246Smarius 36194246Smarius/** 37194246Smarius * Utility methods for operating on program elements. 38194246Smarius * 39194246Smarius * <p><b>Compatibility Note:</b> Methods may be added to this interface 40194246Smarius * in future releases of the platform. 41194246Smarius * 42194246Smarius * @author Joseph D. Darcy 43194246Smarius * @author Scott Seligman 44194246Smarius * @author Peter von der Ahé 45194246Smarius * @see javax.annotation.processing.ProcessingEnvironment#getElementUtils 46194246Smarius * @since 1.6 47194246Smarius */ 48194246Smariuspublic interface Elements { 49194246Smarius 50194246Smarius /** 51194246Smarius * Returns a package given its fully qualified name if the package is unique in the environment. 52194246Smarius * If running with modules, all modules in the modules graph are searched for matching packages. 53194246Smarius * 54194246Smarius * @param name fully qualified package name, or an empty string for an unnamed package 55194246Smarius * @return the named package, or {@code null} if it cannot be uniquely found 56194246Smarius */ 57194246Smarius PackageElement getPackageElement(CharSequence name); 58194246Smarius 59194246Smarius /** 60194904Smarius * Returns a package given its fully qualified name, as seen from the given module. 61194246Smarius * 62194246Smarius * @param name fully qualified package name, or an empty string for an unnamed package 63194246Smarius * @param module module relative to which the lookup should happen 64194246Smarius * @return the named package, or {@code null} if it cannot be found 65194246Smarius * @since 9 66194246Smarius */ 67194246Smarius PackageElement getPackageElement(ModuleElement module, CharSequence name); 68194246Smarius 69194246Smarius /** 70194246Smarius * Returns a type element given its canonical name if the type element is unique in the environment. 71194246Smarius * If running with modules, all modules in the modules graph are searched for matching 72194246Smarius * type elements. 73194246Smarius * 74194246Smarius * @param name the canonical name 75194246Smarius * @return the named type element, or {@code null} if it cannot be uniquely found 76194246Smarius */ 77194246Smarius TypeElement getTypeElement(CharSequence name); 78194246Smarius 79207585Smarius /** 80194246Smarius * Returns a type element given its canonical name, as seen from the given module. 81194246Smarius * 82194246Smarius * @param name the canonical name 83194246Smarius * @param module module relative to which the lookup should happen 84194246Smarius * @return the named type element, or {@code null} if it cannot be found 85194246Smarius * @since 9 86194246Smarius */ 87194246Smarius TypeElement getTypeElement(ModuleElement module, CharSequence name); 88194246Smarius 89194246Smarius /** 90194246Smarius * Returns a module element given its fully qualified name. 91194246Smarius * If the named module cannot be found, null is returned. One situation where a module 92194246Smarius * cannot be found is if the environment does not include modules, such as 93194246Smarius * an annotation processing environment configured for 94194246Smarius * a {@linkplain ProcessingEnvironment#getSourceVersion source version} without modules. * 95194246Smarius * 96194246Smarius * @param name the name 97194246Smarius * @return the named module element, or {@code null} if it cannot be found 98194246Smarius * @since 9 99194246Smarius */ 100194246Smarius ModuleElement getModuleElement(CharSequence name); 101194246Smarius 102194246Smarius /** 103194246Smarius * Returns the values of an annotation's elements, including defaults. 104194246Smarius * 105194246Smarius * @see AnnotationMirror#getElementValues() 106194246Smarius * @param a annotation to examine 107194246Smarius * @return the values of the annotation's elements, including defaults 108194246Smarius */ 109194246Smarius Map<? extends ExecutableElement, ? extends AnnotationValue> 110194246Smarius getElementValuesWithDefaults(AnnotationMirror a); 111194246Smarius 112194246Smarius /** 113194246Smarius * Returns the text of the documentation ("Javadoc") 114194246Smarius * comment of an element. 115194246Smarius * 116194246Smarius * <p> A documentation comment of an element is a comment that 117194246Smarius * begins with "{@code /**}" , ends with a separate 118194246Smarius * "<code>*/</code>", and immediately precedes the element, 119194246Smarius * ignoring white space. Therefore, a documentation comment 120194246Smarius * contains at least three"{@code *}" characters. The text 121194246Smarius * returned for the documentation comment is a processed form of 122194246Smarius * the comment as it appears in source code. The leading "{@code 123194246Smarius * /**}" and trailing "<code>*/</code>" are removed. For lines 124194246Smarius * of the comment starting after the initial "{@code /**}", 125194246Smarius * leading white space characters are discarded as are any 126194246Smarius * consecutive "{@code *}" characters appearing after the white 127194246Smarius * space or starting the line. The processed lines are then 128194246Smarius * concatenated together (including line terminators) and 129194246Smarius * returned. 130194246Smarius * 131194246Smarius * @param e the element being examined 132194246Smarius * @return the documentation comment of the element, or {@code null} 133194246Smarius * if there is none 134194246Smarius * @jls 3.6 White Space 135254842Sandre */ 136194246Smarius String getDocComment(Element e); 137194246Smarius 138194246Smarius /** 139194904Smarius * Returns {@code true} if the element is deprecated, {@code false} otherwise. 140194904Smarius * 141194246Smarius * @param e the element being examined 142194246Smarius * @return {@code true} if the element is deprecated, {@code false} otherwise 143194246Smarius */ 144194246Smarius boolean isDeprecated(Element e); 145194246Smarius 146194246Smarius /** 147194246Smarius * Returns the <em>origin</em> of the given element. 148194246Smarius * 149194246Smarius * <p>Note that if this method returns {@link Origin#EXPLICIT 150194246Smarius * EXPLICIT} and the element was created from a class file, then 151194246Smarius * the element may not, in fact, correspond to an explicitly 152194246Smarius * declared construct in source code. This is due to limitations 153194246Smarius * of the fidelity of the class file format in preserving 154194246Smarius * information from source code. For example, at least some 155194246Smarius * versions of the class file format do not preserve whether a 156194246Smarius * constructor was explicitly declared by the programmer or was 157194246Smarius * implicitly declared as the <em>default constructor</em>. 158194246Smarius * 159194246Smarius * @implSpec The default implementation of this method returns 160194246Smarius * {@link Origin#EXPLICIT EXPLICIT}. 161194246Smarius * 162194246Smarius * @param e the element being examined 163194246Smarius * @return the origin of the given element 164194246Smarius * @since 9 165194246Smarius */ 166194246Smarius default Origin getOrigin(Element e) { 167194246Smarius return Origin.EXPLICIT; 168194904Smarius } 169194246Smarius 170194904Smarius /** 171194246Smarius * Returns the <em>origin</em> of the given annotation mirror. 172194246Smarius * 173194246Smarius * An annotation mirror is {@linkplain Origin#MANDATED mandated} 174194246Smarius * if it is an implicitly declared <em>container annotation</em> 175194246Smarius * used to hold repeated annotations of a repeatable annotation 176194246Smarius * type. 177194246Smarius * 178194246Smarius * <p>Note that if this method returns {@link Origin#EXPLICIT 179210334Sattilio * EXPLICIT} and the annotation mirror was created from a class 180194246Smarius * file, then the element may not, in fact, correspond to an 181194246Smarius * explicitly declared construct in source code. This is due to 182194246Smarius * limitations of the fidelity of the class file format in 183194246Smarius * preserving information from source code. For example, at least 184194246Smarius * some versions of the class file format do not preserve whether 185194246Smarius * an annotation was explicitly declared by the programmer or was 186194246Smarius * implicitly declared as a <em>container annotation</em>. 187194246Smarius * 188194246Smarius * @implSpec The default implementation of this method returns 189194246Smarius * {@link Origin#EXPLICIT EXPLICIT}. 190194246Smarius * 191194246Smarius * @param c the construct the annotation mirror modifies 192194246Smarius * @param a the annotation mirror being examined 193194246Smarius * @return the origin of the given annotation mirror 194194246Smarius * @jls 9.6.3 Repeatable Annotation Types 195194246Smarius * @jls 9.7.5 Multiple Annotations of the Same Type 196194246Smarius * @since 9 197194246Smarius */ 198194246Smarius default Origin getOrigin(AnnotatedConstruct c, 199194246Smarius AnnotationMirror a) { 200194246Smarius return Origin.EXPLICIT; 201194246Smarius } 202194246Smarius 203194246Smarius /** 204194246Smarius * Returns the <em>origin</em> of the given module directive. 205194246Smarius * 206223986Smarius * <p>Note that if this method returns {@link Origin#EXPLICIT 207194904Smarius * EXPLICIT} and the module directive was created from a class 208194904Smarius * file, then the module directive may not, in fact, correspond to 209194904Smarius * an explicitly declared construct in source code. This is due to 210194904Smarius * limitations of the fidelity of the class file format in 211194904Smarius * preserving information from source code. For example, at least 212194904Smarius * some versions of the class file format do not preserve whether 213194904Smarius * a {@code uses} directive was explicitly declared by the 214194904Smarius * programmer or was added as a synthetic construct. 215194904Smarius * 216194904Smarius * <p>Note that an implementation may not be able to reliably 217245923Smarius * determine the origin status of the directive if the directive 218194904Smarius * is created from a class file due to limitations of the fidelity 219245923Smarius * of the class file format in preserving information from source 220245923Smarius * code. 221245923Smarius * 222245923Smarius * @implSpec The default implementation of this method returns 223194246Smarius * {@link Origin#EXPLICIT EXPLICIT}. 224194246Smarius * 225194246Smarius * @param m the module of the directive 226194246Smarius * @param directive the module directive being examined 227194246Smarius * @return the origin of the given directive 228194246Smarius * @since 9 229194246Smarius */ 230194246Smarius default Origin getOrigin(ModuleElement m, 231194246Smarius ModuleElement.Directive directive) { 232194904Smarius return Origin.EXPLICIT; 233194246Smarius } 234194246Smarius 235194246Smarius /** 236194246Smarius * The <em>origin</em> of an element or other language model 237194246Smarius * item. The origin of an element or item models how a construct 238194246Smarius * in a program is declared in the source code, explicitly, 239194246Smarius * implicitly, etc. 240194246Smarius * 241194246Smarius * <p>Note that it is possible additional kinds of origin values 242194246Smarius * will be added in future versions of the platform. 243194246Smarius * 244194246Smarius * @jls 13.1 The Form of a Binary 245194246Smarius * @since 9 246194246Smarius */ 247194246Smarius public enum Origin { 248194246Smarius /** 249194246Smarius * Describes a construct explicitly declared in source code. 250194246Smarius */ 251194246Smarius EXPLICIT, 252194246Smarius 253194246Smarius /** 254194246Smarius * A mandated construct is one that is not explicitly declared 255194246Smarius * in the source code, but whose presence is mandated by the 256194246Smarius * specification. Such a construct is said to be implicitly 257194246Smarius * declared. 258194246Smarius * 259194246Smarius * One example of a mandated element is a <em>default 260194246Smarius * constructor</em> in a class that contains no explicit 261194246Smarius * constructor declarations. 262194246Smarius * 263194246Smarius * Another example of a mandated construct is an implicitly 264194246Smarius * declared <em>container annotation</em> used to hold 265194246Smarius * multiple annotations of a repeatable annotation type. 266194246Smarius * 267194246Smarius * @jls 8.8.9 Default Constructor 268194246Smarius * @jls 9.6.3 Repeatable Annotation Types 269194246Smarius * @jls 9.7.5 Multiple Annotations of the Same Type 270194246Smarius */ 271194246Smarius MANDATED, 272194246Smarius 273194246Smarius /** 274194246Smarius * A synthetic construct is one that is neither implicitly nor 275194246Smarius * explicitly declared in the source code. Such a construct is 276194246Smarius * typically a translation artifact created by a compiler. 277194246Smarius */ 278194246Smarius SYNTHETIC; 279194246Smarius 280194246Smarius /** 281194246Smarius * Returns {@code true} for values corresponding to constructs 282194246Smarius * that are implicitly or explicitly declared, {@code false} 283194246Smarius * otherwise. 284194246Smarius * @return {@code true} for {@link EXPLICIT} and {@link 285194246Smarius * MANDATED}, {@code false} otherwise. 286194246Smarius */ 287194246Smarius public boolean isDeclared() { 288194246Smarius return this != SYNTHETIC; 289194246Smarius } 290194246Smarius } 291194246Smarius 292194246Smarius /** 293194246Smarius * Returns {@code true} if the executable element is a bridge 294194246Smarius * method, {@code false} otherwise. 295194246Smarius * 296194246Smarius * @implSpec The default implementation of this method returns {@code false}. 297194246Smarius * 298194246Smarius * @param e the executable being examined 299194246Smarius * @return {@code true} if the executable element is a bridge 300194246Smarius * method, {@code false} otherwise 301194246Smarius * @since 9 302194246Smarius */ 303194246Smarius default boolean isBridge(ExecutableElement e) { 304194246Smarius return false; 305194246Smarius } 306194246Smarius 307194246Smarius /** 308194246Smarius * Returns the <i>binary name</i> of a type element. 309194246Smarius * 310194246Smarius * @param type the type element being examined 311194246Smarius * @return the binary name 312194246Smarius * 313194246Smarius * @see TypeElement#getQualifiedName 314194246Smarius * @jls 13.1 The Form of a Binary 315194246Smarius */ 316194246Smarius Name getBinaryName(TypeElement type); 317194246Smarius 318194246Smarius 319194246Smarius /** 320194246Smarius * Returns the package of an element. The package of a package is 321194246Smarius * itself. 322194246Smarius * 323194246Smarius * @param type the element being examined 324194246Smarius * @return the package of an element 325194246Smarius */ 326194246Smarius PackageElement getPackageOf(Element type); 327194246Smarius 328194246Smarius /** 329207585Smarius * Returns the module of an element. The module of a module is 330207585Smarius * itself. 331207585Smarius * If there is no module for the element, null is returned. One situation where there is 332207585Smarius * no module for an element is if the environment does not include modules, such as 333207585Smarius * an annotation processing environment configured for 334207585Smarius * a {@linkplain ProcessingEnvironment#getSourceVersion source version} without modules. * 335207585Smarius * 336207585Smarius * @param type the element being examined 337207585Smarius * @return the module of an element 338207585Smarius * @since 9 339207585Smarius */ 340207585Smarius ModuleElement getModuleOf(Element type); 341207585Smarius 342207585Smarius /** 343207585Smarius * Returns all members of a type element, whether inherited or 344207585Smarius * declared directly. For a class the result also includes its 345207585Smarius * constructors, but not local or anonymous classes. 346245923Smarius * 347245923Smarius * <p>Note that elements of certain kinds can be isolated using 348245923Smarius * methods in {@link ElementFilter}. 349207585Smarius * 350207585Smarius * @param type the type being examined 351207585Smarius * @return all members of the type 352245923Smarius * @see Element#getEnclosedElements 353207585Smarius */ 354213893Smarius List<? extends Element> getAllMembers(TypeElement type); 355213893Smarius 356215721Smarius /** 357194246Smarius * Returns all annotations <i>present</i> on an element, whether 358207585Smarius * directly present or present via inheritance. 359207585Smarius * 360207585Smarius * @param e the element being examined 361207585Smarius * @return all annotations of the element 362207585Smarius * @see Element#getAnnotationMirrors 363207585Smarius * @see javax.lang.model.AnnotatedConstruct 364207585Smarius */ 365207585Smarius List<? extends AnnotationMirror> getAllAnnotationMirrors(Element e); 366207585Smarius 367207585Smarius /** 368207585Smarius * Tests whether one type, method, or field hides another. 369245923Smarius * 370207585Smarius * @param hider the first element 371207585Smarius * @param hidden the second element 372207585Smarius * @return {@code true} if and only if the first element hides 373207585Smarius * the second 374245923Smarius */ 375207585Smarius boolean hides(Element hider, Element hidden); 376213893Smarius 377213893Smarius /** 378215721Smarius * Tests whether one method, as a member of a given type, 379194246Smarius * overrides another method. 380207585Smarius * When a non-abstract method overrides an abstract one, the 381207585Smarius * former is also said to <i>implement</i> the latter. 382207585Smarius * 383207585Smarius * <p> In the simplest and most typical usage, the value of the 384194246Smarius * {@code type} parameter will simply be the class or interface 385207585Smarius * directly enclosing {@code overrider} (the possibly-overriding 386207585Smarius * method). For example, suppose {@code m1} represents the method 387207585Smarius * {@code String.hashCode} and {@code m2} represents {@code 388207585Smarius * Object.hashCode}. We can then ask whether {@code m1} overrides 389207585Smarius * {@code m2} within the class {@code String} (it does): 390207585Smarius * 391207585Smarius * <blockquote> 392194246Smarius * {@code assert elements.overrides(m1, m2, 393207585Smarius * elements.getTypeElement("java.lang.String")); } 394207585Smarius * </blockquote> 395207585Smarius * 396207585Smarius * A more interesting case can be illustrated by the following example 397207585Smarius * in which a method in type {@code A} does not override a 398213893Smarius * like-named method in type {@code B}: 399213893Smarius * 400215721Smarius * <blockquote> 401194246Smarius * {@code class A { public void m() {} } }<br> 402194246Smarius * {@code interface B { void m(); } }<br> 403213893Smarius * ...<br> 404194246Smarius * {@code m1 = ...; // A.m }<br> 405194246Smarius * {@code m2 = ...; // B.m }<br> 406194246Smarius * {@code assert ! elements.overrides(m1, m2, 407194246Smarius * elements.getTypeElement("A")); } 408194246Smarius * </blockquote> 409194246Smarius * 410194246Smarius * When viewed as a member of a third type {@code C}, however, 411194246Smarius * the method in {@code A} does override the one in {@code B}: 412194246Smarius * 413194246Smarius * <blockquote> 414194246Smarius * {@code class C extends A implements B {} }<br> 415194246Smarius * ...<br> 416194246Smarius * {@code assert elements.overrides(m1, m2, 417194246Smarius * elements.getTypeElement("C")); } 418194246Smarius * </blockquote> 419194246Smarius * 420194246Smarius * @param overrider the first method, possible overrider 421194246Smarius * @param overridden the second method, possibly being overridden 422194246Smarius * @param type the type of which the first method is a member 423194246Smarius * @return {@code true} if and only if the first method overrides 424194246Smarius * the second 425194246Smarius * @jls 8.4.8 Inheritance, Overriding, and Hiding 426194246Smarius * @jls 9.4.1 Inheritance and Overriding 427194246Smarius */ 428194246Smarius boolean overrides(ExecutableElement overrider, ExecutableElement overridden, 429194246Smarius TypeElement type); 430194246Smarius 431194246Smarius /** 432194246Smarius * Returns the text of a <i>constant expression</i> representing a 433194246Smarius * primitive value or a string. 434194246Smarius * The text returned is in a form suitable for representing the value 435194246Smarius * in source code. 436194246Smarius * 437194246Smarius * @param value a primitive value or string 438194246Smarius * @return the text of a constant expression 439194246Smarius * @throws IllegalArgumentException if the argument is not a primitive 440194246Smarius * value or string 441194246Smarius * 442194246Smarius * @see VariableElement#getConstantValue() 443194246Smarius */ 444194246Smarius String getConstantExpression(Object value); 445194246Smarius 446194246Smarius /** 447194246Smarius * Prints a representation of the elements to the given writer in 448194246Smarius * the specified order. The main purpose of this method is for 449194246Smarius * diagnostics. The exact format of the output is <em>not</em> 450194246Smarius * specified and is subject to change. 451194246Smarius * 452194246Smarius * @param w the writer to print the output to 453194246Smarius * @param elements the elements to print 454194246Smarius */ 455194246Smarius void printElements(java.io.Writer w, Element... elements); 456194246Smarius 457194246Smarius /** 458194246Smarius * Return a name with the same sequence of characters as the 459194246Smarius * argument. 460194246Smarius * 461194246Smarius * @param cs the character sequence to return as a name 462194246Smarius * @return a name with the same sequence of characters as the argument 463194246Smarius */ 464194246Smarius Name getName(CharSequence cs); 465194246Smarius 466194246Smarius /** 467194904Smarius * Returns {@code true} if the type element is a functional interface, {@code false} otherwise. 468194904Smarius * 469194246Smarius * @param type the type element being examined 470194246Smarius * @return {@code true} if the element is a functional interface, {@code false} otherwise 471194246Smarius * @jls 9.8 Functional Interfaces 472194246Smarius * @since 1.8 473194246Smarius */ 474194246Smarius boolean isFunctionalInterface(TypeElement type); 475194246Smarius} 476194246Smarius