1 /*
2 * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.lang.model.util;
27
28 import java.util.ArrayList;
29 import java.util.Collections;
30 import java.util.List;
31 import java.util.Map;
32 import java.util.Set;
33 import java.util.LinkedHashSet;
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 * @author Joseph D. Darcy
46 * @author Scott Seligman
47 * @author Peter von der Ahé
48 * @see javax.annotation.processing.ProcessingEnvironment#getElementUtils
49 * @since 1.6
50 */
51 public interface Elements {
52
53 /**
54 * Returns a package given its fully qualified name if the package is unique in the environment.
55 * If running with modules, all modules in the modules graph are searched for matching packages.
56 *
57 * @param name fully qualified package name, or an empty string for an unnamed package
58 * @return the specified package, or {@code null} if it cannot be uniquely found
59 */
60 PackageElement getPackageElement(CharSequence name);
61
62 /**
63 * Returns a package given its fully qualified name, as seen from the given module.
64 *
65 * @implSpec The default implementation of this method returns
66 * {@code null}.
67 *
68 * @param name fully qualified package name, or an empty string for an unnamed package
69 * @param module module relative to which the lookup should happen
70 * @return the specified package, or {@code null} if it cannot be found
71 * @since 9
72 */
73 default PackageElement getPackageElement(ModuleElement module, CharSequence name) {
74 return null;
75 }
76
77 /**
78 * Returns all package elements with the given canonical name.
79 *
80 * There may be more than one package element with the same canonical
81 * name if the package elements are in different modules.
82 *
83 * @implSpec The default implementation of this method calls
84 * {@link #getAllModuleElements() getAllModuleElements} and stores
85 * the result. If the set of modules is empty, {@link
86 * #getPackageElement(CharSequence) getPackageElement(name)} is
87 * called passing through the name argument. If {@code
88 * getPackageElement(name)} is null, an empty set of package
89 * elements is returned; otherwise, a single-element set with the
90 * found package element is returned. If the set of modules is
91 * nonempty, the modules are iterated over and any non-null result
92 * of {@link #getPackageElement(ModuleElement, CharSequence)
93 * getPackageElement(module, name)} are accumulated into a
94 * set. The set is then returned.
95 *
96 * @param name the canonical name
97 * @return the package elements, or an empty set if no package with the name can be found
98 * @since 9
99 */
100 default Set<? extends PackageElement> getAllPackageElements(CharSequence name) {
101 Set<? extends ModuleElement> modules = getAllModuleElements();
102 if (modules.isEmpty()) {
103 PackageElement packageElt = getPackageElement(name);
104 return (packageElt != null) ?
105 Collections.singleton(packageElt):
106 Collections.emptySet();
107 } else {
108 Set<PackageElement> result = new LinkedHashSet<>(1); // Usually expect at most 1 result
109 for (ModuleElement module: modules) {
110 PackageElement packageElt = getPackageElement(module, name);
111 if (packageElt != null)
112 result.add(packageElt);
113 }
114 return Collections.unmodifiableSet(result);
115 }
116 }
117
118 /**
119 * Returns a type element given its canonical name if the type element is unique in the environment.
120 * If running with modules, all modules in the modules graph are searched for matching
121 * type elements.
122 *
123 * @param name the canonical name
124 * @return the named type element, or {@code null} if it cannot be uniquely found
125 */
126 TypeElement getTypeElement(CharSequence name);
127
128 /**
129 * Returns a type element given its canonical name, as seen from the given module.
130 *
131 * @implSpec The default implementation of this method returns
132 * {@code null}.
133 *
134 * @param name the canonical name
135 * @param module module relative to which the lookup should happen
136 * @return the named type element, or {@code null} if it cannot be found
137 * @since 9
138 */
139 default TypeElement getTypeElement(ModuleElement module, CharSequence name) {
140 return null;
141 }
142
143 /**
144 * Returns all type elements with the given canonical name.
145 *
146 * There may be more than one type element with the same canonical
147 * name if the type elements are in different modules.
148 *
149 * @implSpec The default implementation of this method calls
150 * {@link #getAllModuleElements() getAllModuleElements} and stores
151 * the result. If the set of modules is empty, {@link
152 * #getTypeElement(CharSequence) getTypeElement(name)} is called
153 * passing through the name argument. If {@code
154 * getTypeElement(name)} is null, an empty set of type elements is
155 * returned; otherwise, a single-element set with the found type
156 * element is returned. If the set of modules is nonempty, the
157 * modules are iterated over and any non-null result of {@link
158 * #getTypeElement(ModuleElement, CharSequence)
159 * getTypeElement(module, name)} are accumulated into a set. The
160 * set is then returned.
161 *
162 * @param name the canonical name
163 * @return the type elements, or an empty set if no type with the name can be found
164 * @since 9
165 */
166 default Set<? extends TypeElement> getAllTypeElements(CharSequence name) {
167 Set<? extends ModuleElement> modules = getAllModuleElements();
168 if (modules.isEmpty()) {
169 TypeElement typeElt = getTypeElement(name);
170 return (typeElt != null) ?
171 Collections.singleton(typeElt):
172 Collections.emptySet();
173 } else {
174 Set<TypeElement> result = new LinkedHashSet<>(1); // Usually expect at most 1 result
175 for (ModuleElement module: modules) {
176 TypeElement typeElt = getTypeElement(module, name);
177 if (typeElt != null)
178 result.add(typeElt);
179 }
180 return Collections.unmodifiableSet(result);
181 }
182 }
183
184 /**
185 * Returns a module element given its fully qualified name.
186 * If the named module cannot be found, null is returned. One situation where a module
187 * cannot be found is if the environment does not include modules, such as
188 * an annotation processing environment configured for
189 * a {@linkplain
190 * javax.annotation.processing.ProcessingEnvironment#getSourceVersion
191 * source version} without modules.
192 *
193 * @implSpec The default implementation of this method returns
194 * {@code null}.
195 *
196 * @param name the name
197 * @return the named module element, or {@code null} if it cannot be found
198 * @since 9
199 * @spec JPMS
200 */
201 default ModuleElement getModuleElement(CharSequence name) {
202 return null;
203 }
204
205 /**
206 * Returns all module elements in the current environment.
207 *
208 * If no modules are present, an empty set is returned. One
209 * situation where no modules are present occurs when the
210 * environment does not include modules, such as an annotation
211 * processing environment configured for a {@linkplain
212 * javax.annotation.processing.ProcessingEnvironment#getSourceVersion
213 * source version} without modules.
214 *
215 * @implSpec The default implementation of this method returns
216 * an empty set.
217 *
218 * @return the known module elements, or an empty set if there are no modules
219 * @since 9
220 */
221 default Set<? extends ModuleElement> getAllModuleElements() {
222 return Collections.emptySet();
223 }
224
225 /**
226 * Returns the values of an annotation's elements, including defaults.
227 *
228 * @see AnnotationMirror#getElementValues()
229 * @param a annotation to examine
230 * @return the values of the annotation's elements, including defaults
231 */
232 Map<? extends ExecutableElement, ? extends AnnotationValue>
233 getElementValuesWithDefaults(AnnotationMirror a);
234
235 /**
236 * Returns the text of the documentation ("Javadoc")
237 * comment of an element.
238 *
239 * <p> A documentation comment of an element is a comment that
240 * begins with "{@code /**}" , ends with a separate
241 * "<code>*/</code>", and immediately precedes the element,
242 * ignoring white space. Therefore, a documentation comment
243 * contains at least three"{@code *}" characters. The text
244 * returned for the documentation comment is a processed form of
245 * the comment as it appears in source code. The leading "{@code
246 * /**}" and trailing "<code>*/</code>" are removed. For lines
247 * of the comment starting after the initial "{@code /**}",
248 * leading white space characters are discarded as are any
249 * consecutive "{@code *}" characters appearing after the white
250 * space or starting the line. The processed lines are then
251 * concatenated together (including line terminators) and
252 * returned.
253 *
254 * @param e the element being examined
255 * @return the documentation comment of the element, or {@code null}
256 * if there is none
257 * @jls 3.6 White Space
258 */
259 String getDocComment(Element e);
260
261 /**
262 * Returns {@code true} if the element is deprecated, {@code false} otherwise.
263 *
264 * @param e the element being examined
265 * @return {@code true} if the element is deprecated, {@code false} otherwise
266 */
267 boolean isDeprecated(Element e);
268
269 /**
270 * Returns the <em>origin</em> of the given element.
271 *
272 * <p>Note that if this method returns {@link Origin#EXPLICIT
273 * EXPLICIT} and the element was created from a class file, then
274 * the element may not, in fact, correspond to an explicitly
275 * declared construct in source code. This is due to limitations
276 * of the fidelity of the class file format in preserving
277 * information from source code. For example, at least some
278 * versions of the class file format do not preserve whether a
279 * constructor was explicitly declared by the programmer or was
280 * implicitly declared as the <em>default constructor</em>.
281 *
282 * @implSpec The default implementation of this method returns
283 * {@link Origin#EXPLICIT EXPLICIT}.
284 *
285 * @param e the element being examined
286 * @return the origin of the given element
287 * @since 9
288 */
289 default Origin getOrigin(Element e) {
290 return Origin.EXPLICIT;
291 }
292
293 /**
294 * Returns the <em>origin</em> of the given annotation mirror.
295 *
296 * An annotation mirror is {@linkplain Origin#MANDATED mandated}
297 * if it is an implicitly declared <em>container annotation</em>
298 * used to hold repeated annotations of a repeatable annotation
299 * type.
300 *
301 * <p>Note that if this method returns {@link Origin#EXPLICIT
302 * EXPLICIT} and the annotation mirror was created from a class
303 * file, then the element may not, in fact, correspond to an
304 * explicitly declared construct in source code. This is due to
305 * limitations of the fidelity of the class file format in
306 * preserving information from source code. For example, at least
307 * some versions of the class file format do not preserve whether
308 * an annotation was explicitly declared by the programmer or was
309 * implicitly declared as a <em>container annotation</em>.
310 *
311 * @implSpec The default implementation of this method returns
312 * {@link Origin#EXPLICIT EXPLICIT}.
313 *
314 * @param c the construct the annotation mirror modifies
315 * @param a the annotation mirror being examined
316 * @return the origin of the given annotation mirror
317 * @jls 9.6.3 Repeatable Annotation Types
318 * @jls 9.7.5 Multiple Annotations of the Same Type
319 * @since 9
320 */
321 default Origin getOrigin(AnnotatedConstruct c,
322 AnnotationMirror a) {
323 return Origin.EXPLICIT;
324 }
325
326 /**
327 * Returns the <em>origin</em> of the given module directive.
328 *
329 * <p>Note that if this method returns {@link Origin#EXPLICIT
330 * EXPLICIT} and the module directive was created from a class
331 * file, then the module directive may not, in fact, correspond to
332 * an explicitly declared construct in source code. This is due to
333 * limitations of the fidelity of the class file format in
334 * preserving information from source code. For example, at least
335 * some versions of the class file format do not preserve whether
336 * a {@code uses} directive was explicitly declared by the
337 * programmer or was added as a synthetic construct.
338 *
339 * <p>Note that an implementation may not be able to reliably
340 * determine the origin status of the directive if the directive
341 * is created from a class file due to limitations of the fidelity
342 * of the class file format in preserving information from source
343 * code.
344 *
345 * @implSpec The default implementation of this method returns
346 * {@link Origin#EXPLICIT EXPLICIT}.
347 *
348 * @param m the module of the directive
349 * @param directive the module directive being examined
350 * @return the origin of the given directive
351 * @since 9
352 */
353 default Origin getOrigin(ModuleElement m,
354 ModuleElement.Directive directive) {
355 return Origin.EXPLICIT;
356 }
357
358 /**
359 * The <em>origin</em> of an element or other language model
360 * item. The origin of an element or item models how a construct
361 * in a program is declared in the source code, explicitly,
362 * implicitly, etc.
363 *
364 * <p>Note that it is possible additional kinds of origin values
365 * will be added in future versions of the platform.
366 *
367 * @jls 13.1 The Form of a Binary
368 * @since 9
369 */
370 public enum Origin {
371 /**
372 * Describes a construct explicitly declared in source code.
373 */
374 EXPLICIT,
375
376 /**
377 * A mandated construct is one that is not explicitly declared
378 * in the source code, but whose presence is mandated by the
379 * specification. Such a construct is said to be implicitly
380 * declared.
381 *
382 * One example of a mandated element is a <em>default
383 * constructor</em> in a class that contains no explicit
384 * constructor declarations.
385 *
386 * Another example of a mandated construct is an implicitly
387 * declared <em>container annotation</em> used to hold
388 * multiple annotations of a repeatable annotation type.
389 *
390 * @jls 8.8.9 Default Constructor
391 * @jls 8.9.3 Enum Members
392 * @jls 9.6.3 Repeatable Annotation Types
393 * @jls 9.7.5 Multiple Annotations of the Same Type
394 */
395 MANDATED,
396
397 /**
398 * A synthetic construct is one that is neither implicitly nor
399 * explicitly declared in the source code. Such a construct is
400 * typically a translation artifact created by a compiler.
401 */
402 SYNTHETIC;
403
404 /**
405 * Returns {@code true} for values corresponding to constructs
406 * that are implicitly or explicitly declared, {@code false}
407 * otherwise.
408 * @return {@code true} for {@link EXPLICIT} and {@link
409 * MANDATED}, {@code false} otherwise.
410 */
411 public boolean isDeclared() {
412 return this != SYNTHETIC;
413 }
414 }
415
416 /**
417 * Returns {@code true} if the executable element is a bridge
418 * method, {@code false} otherwise.
419 *
420 * @implSpec The default implementation of this method returns {@code false}.
421 *
422 * @param e the executable being examined
423 * @return {@code true} if the executable element is a bridge
424 * method, {@code false} otherwise
425 * @since 9
426 */
427 default boolean isBridge(ExecutableElement e) {
428 return false;
429 }
430
431 /**
432 * Returns the <i>binary name</i> of a type element.
433 *
434 * @param type the type element being examined
435 * @return the binary name
436 *
437 * @see TypeElement#getQualifiedName
438 * @jls 13.1 The Form of a Binary
439 */
440 Name getBinaryName(TypeElement type);
441
442
443 /**
444 * Returns the package of an element. The package of a package is
445 * itself.
446 *
447 * @param type the element being examined
448 * @return the package of an element
449 */
450 PackageElement getPackageOf(Element type);
451
452 /**
453 * Returns the module of an element. The module of a module is
454 * itself.
455 * If there is no module for the element, null is returned. One situation where there is
456 * no module for an element is if the environment does not include modules, such as
457 * an annotation processing environment configured for
458 * a {@linkplain
459 * javax.annotation.processing.ProcessingEnvironment#getSourceVersion
460 * source version} without modules.
461 *
462 * @implSpec The default implementation of this method returns
463 * {@code null}.
464 *
465 * @param type the element being examined
466 * @return the module of an element
467 * @since 9
468 * @spec JPMS
469 */
470 default ModuleElement getModuleOf(Element type) {
471 return null;
472 }
473
474 /**
475 * Returns all members of a type element, whether inherited or
476 * declared directly. For a class the result also includes its
477 * constructors, but not local or anonymous classes.
478 *
479 * @apiNote Elements of certain kinds can be isolated using
480 * methods in {@link ElementFilter}.
481 *
482 * @param type the type being examined
483 * @return all members of the type
484 * @see Element#getEnclosedElements
485 */
486 List<? extends Element> getAllMembers(TypeElement type);
487
488 /**
489 * Returns all annotations <i>present</i> on an element, whether
490 * directly present or present via inheritance.
491 *
492 * @param e the element being examined
493 * @return all annotations of the element
494 * @see Element#getAnnotationMirrors
495 * @see javax.lang.model.AnnotatedConstruct
496 */
497 List<? extends AnnotationMirror> getAllAnnotationMirrors(Element e);
498
499 /**
500 * Tests whether one type, method, or field hides another.
501 *
502 * @param hider the first element
503 * @param hidden the second element
504 * @return {@code true} if and only if the first element hides
505 * the second
506 */
507 boolean hides(Element hider, Element hidden);
508
509 /**
510 * Tests whether one method, as a member of a given type,
511 * overrides another method.
512 * When a non-abstract method overrides an abstract one, the
513 * former is also said to <i>implement</i> the latter.
514 *
515 * <p> In the simplest and most typical usage, the value of the
516 * {@code type} parameter will simply be the class or interface
517 * directly enclosing {@code overrider} (the possibly-overriding
518 * method). For example, suppose {@code m1} represents the method
519 * {@code String.hashCode} and {@code m2} represents {@code
520 * Object.hashCode}. We can then ask whether {@code m1} overrides
521 * {@code m2} within the class {@code String} (it does):
522 *
523 * <blockquote>
524 * {@code assert elements.overrides(m1, m2,
525 * elements.getTypeElement("java.lang.String")); }
526 * </blockquote>
527 *
528 * A more interesting case can be illustrated by the following example
529 * in which a method in type {@code A} does not override a
530 * like-named method in type {@code B}:
531 *
532 * <blockquote>
533 * {@code class A { public void m() {} } }<br>
534 * {@code interface B { void m(); } }<br>
535 * ...<br>
536 * {@code m1 = ...; // A.m }<br>
537 * {@code m2 = ...; // B.m }<br>
538 * {@code assert ! elements.overrides(m1, m2,
539 * elements.getTypeElement("A")); }
540 * </blockquote>
541 *
542 * When viewed as a member of a third type {@code C}, however,
543 * the method in {@code A} does override the one in {@code B}:
544 *
545 * <blockquote>
546 * {@code class C extends A implements B {} }<br>
547 * ...<br>
548 * {@code assert elements.overrides(m1, m2,
549 * elements.getTypeElement("C")); }
550 * </blockquote>
551 *
552 * @param overrider the first method, possible overrider
553 * @param overridden the second method, possibly being overridden
554 * @param type the type of which the first method is a member
555 * @return {@code true} if and only if the first method overrides
556 * the second
557 * @jls 8.4.8 Inheritance, Overriding, and Hiding
558 * @jls 9.4.1 Inheritance and Overriding
559 */
560 boolean overrides(ExecutableElement overrider, ExecutableElement overridden,
561 TypeElement type);
562
563 /**
564 * Returns the text of a <i>constant expression</i> representing a
565 * primitive value or a string.
566 * The text returned is in a form suitable for representing the value
567 * in source code.
568 *
569 * @param value a primitive value or string
570 * @return the text of a constant expression
571 * @throws IllegalArgumentException if the argument is not a primitive
572 * value or string
573 *
574 * @see VariableElement#getConstantValue()
575 */
576 String getConstantExpression(Object value);
577
578 /**
579 * Prints a representation of the elements to the given writer in
580 * the specified order. The main purpose of this method is for
581 * diagnostics. The exact format of the output is <em>not</em>
582 * specified and is subject to change.
583 *
584 * @param w the writer to print the output to
585 * @param elements the elements to print
586 */
587 void printElements(java.io.Writer w, Element... elements);
588
589 /**
590 * Return a name with the same sequence of characters as the
591 * argument.
592 *
593 * @param cs the character sequence to return as a name
594 * @return a name with the same sequence of characters as the argument
595 */
596 Name getName(CharSequence cs);
597
598 /**
599 * Returns {@code true} if the type element is a functional interface, {@code false} otherwise.
600 *
601 * @param type the type element being examined
602 * @return {@code true} if the element is a functional interface, {@code false} otherwise
603 * @jls 9.8 Functional Interfaces
604 * @since 1.8
605 */
606 boolean isFunctionalInterface(TypeElement type);
607 }