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