1 /*
2 * Copyright (c) 2005, 2024, 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.util;
27
28 import java.util.Collections;
29 import java.util.List;
30 import java.util.Map;
31 import java.util.Optional;
32 import java.util.Set;
33 import java.util.LinkedHashSet;
34 import java.util.Objects;
35
36 import javax.lang.model.AnnotatedConstruct;
37 import javax.lang.model.element.*;
38
39
40 /**
41 * Utility methods for operating on program elements.
42 *
43 * <p><b>Compatibility Note:</b> Methods may be added to this interface
44 * in future releases of the platform.
45 *
46 * @see javax.annotation.processing.ProcessingEnvironment#getElementUtils
47 * @since 1.6
48 */
49 public interface Elements {
50
51 /**
52 * Returns a package given its fully qualified name if the package is uniquely
53 * determinable in the environment.
54 *
55 * If running with modules, packages of the given name are searched in a
56 * two-stage process:
57 * <ul>
58 * <li>find non-empty packages with the given name returned by
59 * {@link #getPackageElement(ModuleElement, CharSequence)},
60 * where the provided ModuleSymbol is any
61 * {@linkplain java.lang.module##root-modules root module},
62 * </li>
63 * <li>if the above yields an empty list, search
64 * {@link #getAllModuleElements() all modules} for observable
65 * packages with the given name
66 * </li>
67 * </ul>
68 *
69 * If this process leads to a list with a single element, the
70 * single element is returned, otherwise {@code null} is returned.
71 *
72 * @param name fully qualified package name,
73 * or an empty string for an unnamed package
74 * @return the specified package,
75 * or {@code null} if no package can be uniquely determined.
76 */
77 PackageElement getPackageElement(CharSequence name);
78
79 /**
80 * Returns a package given its fully qualified name, as seen from the given module.
81 *
82 * @implSpec The default implementation of this method returns
83 * {@code null}.
84 *
85 * @param name fully qualified package name, or an empty string for an unnamed package
86 * @param module module relative to which the lookup should happen
87 * @return the specified package, or {@code null} if it cannot be found
88 * @see #getAllPackageElements
89 * @since 9
90 */
91 default PackageElement getPackageElement(ModuleElement module, CharSequence name) {
92 return null;
93 }
94
95 /**
96 * Returns all package elements with the given canonical name.
97 *
98 * There may be more than one package element with the same canonical
99 * name if the package elements are in different modules.
100 *
101 * @implSpec The default implementation of this method calls
102 * {@link #getAllModuleElements() getAllModuleElements} and stores
103 * the result. If the set of modules is empty, {@link
104 * #getPackageElement(CharSequence) getPackageElement(name)} is
105 * called passing through the name argument. If {@code
106 * getPackageElement(name)} is {@code null}, an empty set of
107 * package elements is returned; otherwise, a single-element set
108 * with the found package element is returned. If the set of
109 * modules is nonempty, the modules are iterated over and any
110 * non-{@code null} results of {@link
111 * #getPackageElement(ModuleElement, CharSequence)
112 * getPackageElement(module, name)} are accumulated into a
113 * set. The set is then returned.
114 *
115 * @param name the canonical name
116 * @return the package elements, or an empty set if no package with the name can be found
117 * @see #getPackageElement(ModuleElement, CharSequence)
118 * @since 9
119 */
120 default Set<? extends PackageElement> getAllPackageElements(CharSequence name) {
121 Set<? extends ModuleElement> modules = getAllModuleElements();
122 if (modules.isEmpty()) {
123 PackageElement packageElt = getPackageElement(name);
124 return (packageElt != null) ?
125 Collections.singleton(packageElt):
126 Collections.emptySet();
127 } else {
128 Set<PackageElement> result = new LinkedHashSet<>(1); // Usually expect at most 1 result
129 for (ModuleElement module: modules) {
130 PackageElement packageElt = getPackageElement(module, name);
131 if (packageElt != null)
132 result.add(packageElt);
133 }
134 return Collections.unmodifiableSet(result);
135 }
136 }
137
138 /**
139 * Returns a type element given its canonical name if the type element is uniquely
140 * determinable in the environment.
141 *
142 * If running with modules, type elements of the given name are
143 * searched in a two-stage process:
144 * <ul>
145 * <li>find type elements with the given name returned by
146 * {@link #getTypeElement(ModuleElement, CharSequence)},
147 * where the provided ModuleSymbol is any
148 * {@linkplain java.lang.module##root-modules root module},
149 * </li>
150 * <li>if the above yields an empty list, search
151 * {@link #getAllModuleElements() all modules} for observable
152 * type elements with the given name
153 * </li>
154 * </ul>
155 *
156 * If this process leads to a list with a single element, the
157 * single element is returned, otherwise {@code null} is returned.
158 *
159 * @param name the canonical name
160 * @return the named type element,
161 * or {@code null} if no type element can be uniquely determined.
162 */
163 TypeElement getTypeElement(CharSequence name);
164
165 /**
166 * Returns a type element given its canonical name, as seen from the given module.
167 *
168 * @implSpec The default implementation of this method returns
169 * {@code null}.
170 *
171 * @param name the canonical name
172 * @param module module relative to which the lookup should happen
173 * @return the named type element, or {@code null} if it cannot be found
174 * @see #getAllTypeElements
175 * @since 9
176 */
177 default TypeElement getTypeElement(ModuleElement module, CharSequence name) {
178 return null;
179 }
180
181 /**
182 * Returns all type elements with the given canonical name.
183 *
184 * There may be more than one type element with the same canonical
185 * name if the type elements are in different modules.
186 *
187 * @implSpec The default implementation of this method calls
188 * {@link #getAllModuleElements() getAllModuleElements} and stores
189 * the result. If the set of modules is empty, {@link
190 * #getTypeElement(CharSequence) getTypeElement(name)} is called
191 * passing through the name argument. If {@code
192 * getTypeElement(name)} is {@code null}, an empty set of type
193 * elements is returned; otherwise, a single-element set with the
194 * found type element is returned. If the set of modules is
195 * nonempty, the modules are iterated over and any non-{@code null}
196 * results of {@link #getTypeElement(ModuleElement,
197 * CharSequence) getTypeElement(module, name)} are accumulated
198 * into a set. The set is then returned.
199 *
200 * @param name the canonical name
201 * @return the type elements, or an empty set if no type with the name can be found
202 * @see #getTypeElement(ModuleElement, CharSequence)
203 * @since 9
204 */
205 default Set<? extends TypeElement> getAllTypeElements(CharSequence name) {
206 Set<? extends ModuleElement> modules = getAllModuleElements();
207 if (modules.isEmpty()) {
208 TypeElement typeElt = getTypeElement(name);
209 return (typeElt != null) ?
210 Collections.singleton(typeElt):
211 Collections.emptySet();
212 } else {
213 Set<TypeElement> result = new LinkedHashSet<>(1); // Usually expect at most 1 result
214 for (ModuleElement module: modules) {
215 TypeElement typeElt = getTypeElement(module, name);
216 if (typeElt != null)
217 result.add(typeElt);
218 }
219 return Collections.unmodifiableSet(result);
220 }
221 }
222
223 /**
224 * Returns a module element given its fully qualified name.
225 *
226 * If the requested module cannot be found, {@code null} is
227 * returned. One situation where a module cannot be found is if
228 * the environment does not include modules, such as an annotation
229 * processing environment configured for a {@linkplain
230 * javax.annotation.processing.ProcessingEnvironment#getSourceVersion
231 * source version} without modules.
232 *
233 * @implSpec The default implementation of this method returns
234 * {@code null}.
235 *
236 * @param name the name, or an empty string for an unnamed module
237 * @return the named module element, or {@code null} if it cannot be found
238 * @see #getAllModuleElements
239 * @since 9
240 */
241 default ModuleElement getModuleElement(CharSequence name) {
242 return null;
243 }
244
245 /**
246 * Returns all module elements in the current environment.
247 *
248 * If no modules are present, an empty set is returned. One
249 * situation where no modules are present occurs when the
250 * environment does not include modules, such as an annotation
251 * processing environment configured for a {@linkplain
252 * javax.annotation.processing.ProcessingEnvironment#getSourceVersion
253 * source version} without modules.
254 *
255 * @implSpec The default implementation of this method returns
256 * an empty set.
257 *
258 * @apiNote
259 * When an environment includes modules, both named modules and
260 * {@linkplain ModuleElement#isUnnamed() unnamed modules} may be
261 * returned.
262 *
263 * @return the known module elements, or an empty set if there are no modules
264 * @see #getModuleElement(CharSequence)
265 * @since 9
266 */
267 default Set<? extends ModuleElement> getAllModuleElements() {
268 return Collections.emptySet();
269 }
270
271 /**
272 * {@return the values of an annotation's elements, including defaults}
273 *
274 * @see AnnotationMirror#getElementValues()
275 * @param a annotation to examine
276 */
277 Map<? extends ExecutableElement, ? extends AnnotationValue>
278 getElementValuesWithDefaults(AnnotationMirror a);
279
280 /**
281 * Returns the text of the documentation ("Javadoc")
282 * comment of an element.
283 *
284 * <p> A documentation comment of an element is a comment that
285 * begins with "{@code /**}", ends with a separate
286 * "<code>*/</code>", and immediately precedes the element,
287 * ignoring white space, annotations, end-of-line-comments ({@code
288 * "//"} comments), and intermediate traditional comments
289 * (<code>"/* ... */"</code> comments) that are not doc comments.
290 * Therefore, a documentation comment
291 * contains at least three "{@code *}" characters. The text
292 * returned for the documentation comment is a processed form of
293 * the comment as it appears in source code:
294 * <ul>
295 * <li>The leading "{@code /**}" is removed, as are any
296 * immediately following space characters on that line. If all the
297 * characters of the line are removed, it makes no contribution to
298 * the returned comment.
299 * <li>For subsequent lines
300 * of the doc comment starting after the initial "{@code /**}",
301 * if the lines start with <em>zero</em> or more whitespace characters followed by
302 * <em>one</em> or more "{@code *}" characters,
303 * those leading whitespace characters are discarded as are any
304 * consecutive "{@code *}" characters appearing after the white
305 * space or starting the line.
306 * Otherwise, if a line does not have a prefix of the described
307 * form, the entire line is retained.
308 * <li> The trailing "<code>*/</code>" is removed. The line
309 * with the trailing" <code>*/</code>" also undergoes leading
310 * space and "{@code *}" character removal as described above. If all the characters
311 * of the line are removed, it makes no contribution to the
312 * returned comment.
313 * </ul>
314 * The processed lines are then
315 * concatenated together (including line terminators) and
316 * returned.
317 *
318 * @param e the element being examined
319 * @return the documentation comment of the element, or {@code null}
320 * if there is none
321 * @jls 3.6 White Space
322 * @jls 3.7 Comments
323 */
324 String getDocComment(Element e);
325
326 /**
327 * {@return {@code true} if the element is deprecated, {@code false} otherwise}
328 *
329 * @param e the element being examined
330 */
331 boolean isDeprecated(Element e);
332
333 /**
334 * {@return the <em>origin</em> of the given element}
335 *
336 * <p>Note that if this method returns {@link Origin#EXPLICIT
337 * EXPLICIT} and the element was created from a class file, then
338 * the element may not, in fact, correspond to an explicitly
339 * declared construct in source code. This is due to limitations
340 * of the fidelity of the class file format in preserving
341 * information from source code. For example, at least some
342 * versions of the class file format do not preserve whether a
343 * constructor was explicitly declared by the programmer or was
344 * implicitly declared as the <em>default constructor</em>.
345 *
346 * @implSpec The default implementation of this method returns
347 * {@link Origin#EXPLICIT EXPLICIT}.
348 *
349 * @param e the element being examined
350 * @since 9
351 */
352 default Origin getOrigin(Element e) {
353 return Origin.EXPLICIT;
354 }
355
356 /**
357 * {@return the <em>origin</em> of the given annotation mirror}
358 *
359 * An annotation mirror is {@linkplain Origin#MANDATED mandated}
360 * if it is an implicitly declared <em>container annotation</em>
361 * used to hold repeated annotations of a repeatable annotation
362 * interface.
363 *
364 * <p>Note that if this method returns {@link Origin#EXPLICIT
365 * EXPLICIT} and the annotation mirror was created from a class
366 * file, then the element may not, in fact, correspond to an
367 * explicitly declared construct in source code. This is due to
368 * limitations of the fidelity of the class file format in
369 * preserving information from source code. For example, at least
370 * some versions of the class file format do not preserve whether
371 * an annotation was explicitly declared by the programmer or was
372 * implicitly declared as a <em>container annotation</em>.
373 *
374 * @implSpec The default implementation of this method returns
375 * {@link Origin#EXPLICIT EXPLICIT}.
376 *
377 * @param c the construct the annotation mirror modifies
378 * @param a the annotation mirror being examined
379 * @jls 9.6.3 Repeatable Annotation Interfaces
380 * @jls 9.7.5 Multiple Annotations of the Same Interface
381 * @since 9
382 */
383 default Origin getOrigin(AnnotatedConstruct c,
384 AnnotationMirror a) {
385 return Origin.EXPLICIT;
386 }
387
388 /**
389 * {@return the <em>origin</em> of the given module directive}
390 *
391 * <p>Note that if this method returns {@link Origin#EXPLICIT
392 * EXPLICIT} and the module directive was created from a class
393 * file, then the module directive may not, in fact, correspond to
394 * an explicitly declared construct in source code. This is due to
395 * limitations of the fidelity of the class file format in
396 * preserving information from source code. For example, at least
397 * some versions of the class file format do not preserve whether
398 * a {@code uses} directive was explicitly declared by the
399 * programmer or was added as a synthetic construct.
400 *
401 * <p>Note that an implementation may not be able to reliably
402 * determine the origin status of the directive if the directive
403 * is created from a class file due to limitations of the fidelity
404 * of the class file format in preserving information from source
405 * code.
406 *
407 * @implSpec The default implementation of this method returns
408 * {@link Origin#EXPLICIT EXPLICIT}.
409 *
410 * @param m the module of the directive
411 * @param directive the module directive being examined
412 * @since 9
413 */
414 default Origin getOrigin(ModuleElement m,
415 ModuleElement.Directive directive) {
416 return Origin.EXPLICIT;
417 }
418
419 /**
420 * The <em>origin</em> of an element or other language model
421 * item. The origin of an element or item models how a construct
422 * in a program is declared in the source code, explicitly,
423 * implicitly, etc.
424 *
425 * <p>Note that it is possible additional kinds of origin values
426 * will be added in future versions of the platform.
427 *
428 * @jls 13.1 The Form of a Binary
429 * @since 9
430 */
431 public enum Origin {
432 /**
433 * Describes a construct explicitly declared in source code.
434 */
435 EXPLICIT,
436
437 /**
438 * A mandated construct is one that is not explicitly declared
439 * in the source code, but whose presence is mandated by the
440 * specification. Such a construct is said to be implicitly
441 * declared.
442 *
443 * One example of a mandated element is a <em>default
444 * constructor</em> in a class that contains no explicit
445 * constructor declarations.
446 *
447 * Another example of a mandated construct is an implicitly
448 * declared <em>container annotation</em> used to hold
449 * multiple annotations of a repeatable annotation interface.
450 *
451 * @jls 8.8.9 Default Constructor
452 * @jls 8.9.3 Enum Members
453 * @jls 8.10.3 Record Members
454 * @jls 9.6.3 Repeatable Annotation Interfaces
455 * @jls 9.7.5 Multiple Annotations of the Same Interface
456 */
457 MANDATED,
458
459 /**
460 * A synthetic construct is one that is neither implicitly nor
461 * explicitly declared in the source code. Such a construct is
462 * typically a translation artifact created by a compiler.
463 */
464 SYNTHETIC;
465
466 /**
467 * Returns {@code true} for values corresponding to constructs
468 * that are implicitly or explicitly declared, {@code false}
469 * otherwise.
470 * @return {@code true} for {@link #EXPLICIT} and {@link #MANDATED},
471 * {@code false} otherwise.
472 */
473 public boolean isDeclared() {
474 return this != SYNTHETIC;
475 }
476 }
477
478 /**
479 * {@return {@code true} if the executable element is a bridge
480 * method, {@code false} otherwise}
481 *
482 * @implSpec The default implementation of this method returns {@code false}.
483 *
484 * @param e the executable being examined
485 * @since 9
486 */
487 default boolean isBridge(ExecutableElement e) {
488 return false;
489 }
490
491 /**
492 * {@return the <i>binary name</i> of a type element}
493 *
494 * @param type the type element being examined
495 *
496 * @see TypeElement#getQualifiedName
497 * @jls 13.1 The Form of a Binary
498 */
499 Name getBinaryName(TypeElement type);
500
501
502 /**
503 * {@return the package of an element} The package of a package is
504 * itself.
505 * The package of a module is {@code null}.
506 *
507 * The package of a top-level class or interface is its {@linkplain
508 * TypeElement#getEnclosingElement enclosing package}. Otherwise,
509 * the package of an element is equal to the package of the
510 * {@linkplain Element#getEnclosingElement enclosing element}.
511 *
512 * @param e the element being examined
513 */
514 PackageElement getPackageOf(Element e);
515
516 /**
517 * {@return the module of an element} The module of a module is
518 * itself.
519 *
520 * If a package has a module as its {@linkplain
521 * PackageElement#getEnclosingElement enclosing element}, that
522 * module is the module of the package. If the enclosing element
523 * of a package is {@code null}, {@code null} is returned for the
524 * package's module.
525 *
526 * (One situation where a package may have a {@code null} module
527 * is if the environment does not include modules, such as an
528 * annotation processing environment configured for a {@linkplain
529 * javax.annotation.processing.ProcessingEnvironment#getSourceVersion
530 * source version} without modules.)
531 *
532 * Otherwise, the module of an element is equal to the module
533 * {@linkplain #getPackageOf(Element) of the package} of the
534 * element.
535 *
536 * @implSpec The default implementation of this method returns
537 * {@code null}.
538 *
539 * @param e the element being examined
540 * @since 9
541 */
542 default ModuleElement getModuleOf(Element e) {
543 return null;
544 }
545
546 /**
547 * Returns all members of a type element, whether inherited or
548 * declared directly. For a class the result also includes its
549 * constructors, but not local or anonymous classes.
550 *
551 * @apiNote Elements of certain kinds can be isolated using
552 * methods in {@link ElementFilter}.
553 *
554 * @param type the type being examined
555 * @return all members of the type
556 * @see Element#getEnclosedElements
557 */
558 List<? extends Element> getAllMembers(TypeElement type);
559
560 /**
561 * {@return the outermost type element an element is contained in
562 * if such a containing element exists; otherwise returns {@code
563 * null}}
564 *
565 * {@linkplain ModuleElement Modules} and {@linkplain
566 * PackageElement packages} do <em>not</em> have a containing type
567 * element and therefore {@code null} is returned for those kinds
568 * of elements.
569 *
570 * A {@linkplain NestingKind#TOP_LEVEL top-level} class or
571 * interface is its own outermost type element.
572 *
573 * @implSpec
574 * The default implementation of this method first checks the kind
575 * of the argument. For elements of kind {@code PACKAGE}, {@code
576 * MODULE}, and {@code OTHER}, {@code null} is returned. For
577 * elements of other kinds, the element is examined to see if it
578 * is a top-level class or interface. If so, that element is
579 * returned; otherwise, the {@linkplain
580 * Element#getEnclosingElement enclosing element} chain is
581 * followed until a top-level class or interface is found. The
582 * element for the eventual top-level class or interface is
583 * returned.
584 *
585 * @param e the element being examined
586 * @see Element#getEnclosingElement
587 * @since 18
588 */
589 default TypeElement getOutermostTypeElement(Element e) {
590 return switch (e.getKind()) {
591 case PACKAGE,
592 MODULE -> null; // Per the general spec above.
593 case OTHER -> null; // Outside of base model of the javax.lang.model API
594
595 // Elements of all remaining kinds should be enclosed in some
596 // sort of class or interface. Check to see if the element is
597 // a top-level type; if so, return it. Otherwise, keep going
598 // up the enclosing element chain until a top-level type is
599 // found.
600 default -> {
601 Element enclosing = e;
602 // This implementation is susceptible to infinite loops
603 // for misbehaving element implementations.
604 while (true) {
605 // Conceptual instanceof TypeElement check. If the
606 // argument is a type element, put it into a
607 // one-element list, otherwise an empty list.
608 List<TypeElement> possibleTypeElement = ElementFilter.typesIn(List.of(enclosing));
609 if (!possibleTypeElement.isEmpty()) {
610 TypeElement typeElement = possibleTypeElement.get(0);
611 if (typeElement.getNestingKind() == NestingKind.TOP_LEVEL) {
612 yield typeElement;
613 }
614 }
615 enclosing = enclosing.getEnclosingElement();
616 }
617 }
618 };
619 }
620
621 /**
622 * Returns all annotations <i>present</i> on an element, whether
623 * directly present or present via inheritance.
624 *
625 * <p>Note that any annotations returned by this method are
626 * declaration annotations.
627 *
628 * @param e the element being examined
629 * @return all annotations of the element
630 * @see Element#getAnnotationMirrors
631 * @see javax.lang.model.AnnotatedConstruct
632 */
633 List<? extends AnnotationMirror> getAllAnnotationMirrors(Element e);
634
635 /**
636 * Tests whether one type, method, or field hides another.
637 *
638 * @param hider the first element
639 * @param hidden the second element
640 * @return {@code true} if and only if the first element hides
641 * the second
642 * @jls 8.4.8 Inheritance, Overriding, and Hiding
643 */
644 boolean hides(Element hider, Element hidden);
645
646 /**
647 * Tests whether one method, as a member of a given class or interface,
648 * overrides another method.
649 * When a non-abstract method overrides an abstract one, the
650 * former is also said to <i>implement</i> the latter.
651 * As implied by JLS {@jls 8.4.8.1}, a method does <em>not</em>
652 * override itself. The overrides relation is <i>irreflexive</i>.
653 *
654 * <p> In the simplest and most typical usage, the value of the
655 * {@code type} parameter will simply be the class or interface
656 * directly enclosing {@code overrider} (the possibly-overriding
657 * method). For example, suppose {@code m1} represents the method
658 * {@code String.hashCode} and {@code m2} represents {@code
659 * Object.hashCode}. We can then ask whether {@code m1} overrides
660 * {@code m2} within the class {@code String} (it does):
661 *
662 * <blockquote>
663 * {@code assert elements.overrides(m1, m2,
664 * elements.getTypeElement("java.lang.String")); }
665 * </blockquote>
666 *
667 * A more interesting case can be illustrated by the following example
668 * in which a method in class {@code A} does not override a
669 * like-named method in interface {@code B}:
670 *
671 * <blockquote>
672 * {@code class A { public void m() {} } }<br>
673 * {@code interface B { void m(); } }<br>
674 * ...<br>
675 * {@code m1 = ...; // A.m }<br>
676 * {@code m2 = ...; // B.m }<br>
677 * {@code assert ! elements.overrides(m1, m2,
678 * elements.getTypeElement("A")); }
679 * </blockquote>
680 *
681 * When viewed as a member of a third class {@code C}, however,
682 * the method in {@code A} does override the one in {@code B}:
683 *
684 * <blockquote>
685 * {@code class C extends A implements B {} }<br>
686 * ...<br>
687 * {@code assert elements.overrides(m1, m2,
688 * elements.getTypeElement("C")); }
689 * </blockquote>
690 *
691 * Consistent with the usage of the {@link Override @Override}
692 * annotation, if an interface declares a method
693 * override-equivalent to a {@code public} method of {@link Object
694 * java.lang.Object}, such a method of the interface is regarded
695 * as overriding the corresponding {@code Object} method; for
696 * example:
697 *
698 * {@snippet lang=java :
699 * interface I {
700 * @Override
701 * String toString();
702 * }
703 * ...
704 * assert elements.overrides(elementForItoString,
705 * elementForObjecttoString,
706 * elements.getTypeElement("I"));
707 * }
708 *
709 * @param overrider the first method, possible overrider
710 * @param overridden the second method, possibly being overridden
711 * @param type the class or interface of which the first method is a member
712 * @return {@code true} if and only if the first method overrides
713 * the second
714 * @jls 8.4.8 Inheritance, Overriding, and Hiding
715 * @jls 9.4.1 Inheritance and Overriding
716 */
717 boolean overrides(ExecutableElement overrider, ExecutableElement overridden,
718 TypeElement type);
719
720 /**
721 * Returns the text of a <i>constant expression</i> representing a
722 * primitive value or a string.
723 * The text returned is in a form suitable for representing the value
724 * in source code.
725 *
726 * @param value a primitive value or string
727 * @return the text of a constant expression
728 * @throws IllegalArgumentException if the argument is not a primitive
729 * value or string
730 *
731 * @see VariableElement#getConstantValue()
732 */
733 String getConstantExpression(Object value);
734
735 /**
736 * Prints a representation of the elements to the given writer in
737 * the specified order. The main purpose of this method is for
738 * diagnostics. The exact format of the output is <em>not</em>
739 * specified and is subject to change.
740 *
741 * @param w the writer to print the output to
742 * @param elements the elements to print
743 */
744 void printElements(java.io.Writer w, Element... elements);
745
746 /**
747 * {@return a name with the same sequence of characters as the
748 * argument}
749 *
750 * @param cs the character sequence to return as a name
751 */
752 Name getName(CharSequence cs);
753
754 /**
755 * {@return {@code true} if the type element is a functional
756 * interface, {@code false} otherwise}
757 *
758 * @param type the type element being examined
759 * @jls 9.8 Functional Interfaces
760 * @since 1.8
761 */
762 boolean isFunctionalInterface(TypeElement type);
763
764 /**
765 * {@return {@code true} if the module element is an automatic
766 * module, {@code false} otherwise}
767 *
768 * @implSpec
769 * The default implementation of this method returns {@code
770 * false}.
771 *
772 * @param module the module element being examined
773 * @jls 7.7.1 Dependences
774 * @since 17
775 */
776 default boolean isAutomaticModule(ModuleElement module) {
777 return false;
778 }
779
780 /**
781 * {@return the class body of an {@code enum} constant if the
782 * argument is an {@code enum} constant declared with an optional
783 * class body, {@code null} otherwise}
784 *
785 * @implSpec
786 * The default implementation of this method throws {@code
787 * UnsupportedOperationException} if the argument is an {@code
788 * enum} constant and throws an {@code IllegalArgumentException}
789 * if it is not.
790 *
791 * @param enumConstant an enum constant
792 * @throws IllegalArgumentException if the argument is not an {@code enum} constant
793 * @jls 8.9.1 Enum Constants
794 * @since 22
795 */
796 default TypeElement getEnumConstantBody(VariableElement enumConstant) {
797 switch(enumConstant.getKind()) {
798 case ENUM_CONSTANT -> throw new UnsupportedOperationException();
799 default -> throw new IllegalArgumentException("Argument not an enum constant");
800 }
801 }
802
803 /**
804 * Returns the record component for the given accessor. Returns
805 * {@code null} if the given method is not a record component
806 * accessor.
807 *
808 * @implSpec The default implementation of this method checks if the element
809 * enclosing the accessor has kind {@link ElementKind#RECORD RECORD} if that is
810 * the case, then all the record components on the accessor's enclosing element
811 * are retrieved by invoking {@link ElementFilter#recordComponentsIn(Iterable)}.
812 * If the accessor of at least one of the record components retrieved happen to
813 * be equal to the accessor passed as a parameter to this method, then that
814 * record component is returned, in any other case {@code null} is returned.
815 *
816 * @param accessor the method for which the record component should be found.
817 * @return the record component, or {@code null} if the given
818 * method is not a record component accessor
819 * @since 16
820 */
821 default RecordComponentElement recordComponentFor(ExecutableElement accessor) {
822 if (accessor.getEnclosingElement().getKind() == ElementKind.RECORD) {
823 for (RecordComponentElement rec : ElementFilter.recordComponentsIn(accessor.getEnclosingElement().getEnclosedElements())) {
824 if (Objects.equals(rec.getAccessor(), accessor)) {
825 return rec;
826 }
827 }
828 }
829 return null;
830 }
831
832 /**
833 * {@return {@code true} if the executable element can be
834 * determined to be a canonical constructor of a record, {@code
835 * false} otherwise}
836 * Note that in some cases there may be insufficient information
837 * to determine if a constructor is a canonical constructor, such
838 * as if the executable element is built backed by a class
839 * file. In such cases, {@code false} is returned.
840 *
841 * @implSpec
842 * The default implementation of this method unconditionally
843 * returns {@code false}.
844 *
845 * @param e the executable being examined
846 * @jls 8.10.4.1 Normal Canonical Constructors
847 * @since 20
848 */
849 default boolean isCanonicalConstructor(ExecutableElement e) {
850 return false;
851 }
852
853 /**
854 * {@return {@code true} if the executable element can be
855 * determined to be a compact constructor of a record, {@code
856 * false} otherwise}
857 * By definition, a compact constructor is also a {@linkplain
858 * #isCanonicalConstructor(ExecutableElement) canonical
859 * constructor}.
860 * Note that in some cases there may be insufficient information
861 * to determine if a constructor is a compact constructor, such as
862 * if the executable element is built backed by a class file. In
863 * such cases, {@code false} is returned.
864 *
865 * @implSpec
866 * The default implementation of this method unconditionally
867 * returns {@code false}.
868 *
869 * @param e the executable being examined
870 * @jls 8.10.4.2 Compact Canonical Constructors
871 * @since 20
872 */
873 default boolean isCompactConstructor(ExecutableElement e) {
874 return false;
875 }
876
877 /**
878 * {@return the file object for this element or {@code null} if
879 * there is no such file object}
880 *
881 * <p>The returned file object is for the {@linkplain
882 * javax.lang.model.element##accurate_model reference
883 * representation} of the information used to construct the
884 * element. For example, if during compilation or annotation
885 * processing, a source file for class {@code Foo} is compiled
886 * into a class file, the file object returned for the element
887 * representing {@code Foo} would be for the source file and
888 * <em>not</em> for the class file.
889 *
890 * <p>An implementation may choose to not support the
891 * functionality of this method, in which case {@link
892 * UnsupportedOperationException} is thrown.
893 *
894 * <p>In the context of annotation processing, a non-{@code null}
895 * value is returned if the element was included as part of the
896 * initial inputs or the containing file was created during the
897 * run of the annotation processing tool. Otherwise, a {@code
898 * null} may be returned. In annotation processing, if a
899 * {@linkplain javax.annotation.processing.Filer#createClassFile
900 * class file is created}, that class file can serve as the
901 * reference representation for elements.
902 *
903 * <p>If it has a file object, the file object for a package will
904 * be a {@code package-info} file. A package may exist and not
905 * have any {@code package-info} file even if the package is
906 * (implicitly) created during an annotation processing run from
907 * the creation of source or class files in that package. An
908 * {@linkplain PackageElement#isUnnamed unnamed package} will have
909 * a {@code null} file since it cannot be declared in a
910 * compilation unit.
911 *
912 * <p>If it has a file object, the file object for a module will
913 * be a {@code module-info} file. An {@linkplain
914 * ModuleElement#isUnnamed unnamed module} will have a {@code
915 * null} file since it cannot be declared in a compilation unit.
916 * An {@linkplain #isAutomaticModule automatic module} will have a
917 * {@code null} file since it is implicitly declared.
918 *
919 * <p>If it has a file object, the file object for a top-level
920 * {@code public} class or interface will be a source or class
921 * file corresponding to that class or interface. In this case,
922 * typically the leading portion of the name of the file will
923 * match the name of the class or interface. A single compilation
924 * unit can define multiple top-level classes and interfaces, such
925 * as a primary {@code public} class or interfaces whose name
926 * corresponds to the file name and one or more <em>auxiliary</em>
927 * classes or interfaces whose names do not correspond to the file
928 * name. If a source file is providing the reference
929 * representation of an auxiliary class or interface, the file for
930 * the primary class is returned. (An auxiliary class or interface
931 * can also be defined in a {@code package-info} source file, in
932 * which case the file for the {@code package-info} file is
933 * returned.) If a class file is providing the reference
934 * representation of an auxiliary class or interface, the separate
935 * class file for the auxiliary class is returned.
936 *
937 * <p>For a nested class or interface, if it has a file object:
938 *
939 * <ul>
940 *
941 * <li>if a source file is providing the reference representation,
942 * the file object will be that of the {@linkplain
943 * #getOutermostTypeElement(Element) outermost enclosing} class or
944 * interface
945 *
946 * <li>if a class file is providing the reference representation,
947 * the file object will be that of the nested class or interface
948 * itself
949 *
950 * </ul>
951 *
952 * <p>For other lexically enclosed elements, such as {@linkplain
953 * VariableElement#getEnclosingElement() variables}, {@linkplain
954 * ExecutableElement#getEnclosingElement() methods, and
955 * constructors}, if they have a file object, the file object will
956 * be the object associated with the {@linkplain
957 * Element#getEnclosingElement() enclosing element} of the
958 * lexically enclosed element.
959 *
960 * @implSpec The default implementation unconditionally throws
961 * {@link UnsupportedOperationException}.
962 *
963 * @throws UnsupportedOperationException if this functionality is
964 * not supported
965 *
966 * @param e the element to find a file object for
967 * @since 18
968 */
969 default javax.tools.JavaFileObject getFileObjectOf(Element e) {
970 throw new UnsupportedOperationException();
971 }
972
973 /**
974 * Returns the code model of provided executable element (if any).
975 * <p>
976 * If the executable element has a code model then it will be an instance of
977 * {@code java.lang.reflect.code.op.CoreOps.FuncOp}.
978 * Note: due to circular dependencies we cannot refer to the type explicitly.
979 *
980 * @implSpec The default implementation unconditionally returns an empty optional.
981 * @param e the executable element.
982 * @return the code model of the provided executable element (if any).
983 * @since 99
984 */
985 default Optional<Object> getBody(ExecutableElement e) {
986 return Optional.empty();
987 }
988 }