aoqi@0: /* aoqi@0: * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved. aoqi@0: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. aoqi@0: * aoqi@0: * This code is free software; you can redistribute it and/or modify it aoqi@0: * under the terms of the GNU General Public License version 2 only, as aoqi@0: * published by the Free Software Foundation. Oracle designates this aoqi@0: * particular file as subject to the "Classpath" exception as provided aoqi@0: * by Oracle in the LICENSE file that accompanied this code. aoqi@0: * aoqi@0: * This code is distributed in the hope that it will be useful, but WITHOUT aoqi@0: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or aoqi@0: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License aoqi@0: * version 2 for more details (a copy is included in the LICENSE file that aoqi@0: * accompanied this code). aoqi@0: * aoqi@0: * You should have received a copy of the GNU General Public License version aoqi@0: * 2 along with this work; if not, write to the Free Software Foundation, aoqi@0: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. aoqi@0: * aoqi@0: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA aoqi@0: * or visit www.oracle.com if you need additional information or have any aoqi@0: * questions. aoqi@0: */ aoqi@0: aoqi@0: package javax.lang.model.util; aoqi@0: aoqi@0: aoqi@0: import java.util.List; aoqi@0: import java.util.Map; aoqi@0: aoqi@0: import javax.lang.model.element.*; aoqi@0: import javax.lang.model.type.*; aoqi@0: aoqi@0: aoqi@0: /** aoqi@0: * Utility methods for operating on program elements. aoqi@0: * aoqi@0: *

Compatibility Note: Methods may be added to this interface aoqi@0: * in future releases of the platform. aoqi@0: * aoqi@0: * @author Joseph D. Darcy aoqi@0: * @author Scott Seligman aoqi@0: * @author Peter von der Ahé aoqi@0: * @see javax.annotation.processing.ProcessingEnvironment#getElementUtils aoqi@0: * @since 1.6 aoqi@0: */ aoqi@0: public interface Elements { aoqi@0: aoqi@0: /** aoqi@0: * Returns a package given its fully qualified name. aoqi@0: * aoqi@0: * @param name fully qualified package name, or "" for an unnamed package aoqi@0: * @return the named package, or {@code null} if it cannot be found aoqi@0: */ aoqi@0: PackageElement getPackageElement(CharSequence name); aoqi@0: aoqi@0: /** aoqi@0: * Returns a type element given its canonical name. aoqi@0: * aoqi@0: * @param name the canonical name aoqi@0: * @return the named type element, or {@code null} if it cannot be found aoqi@0: */ aoqi@0: TypeElement getTypeElement(CharSequence name); aoqi@0: aoqi@0: /** aoqi@0: * Returns the values of an annotation's elements, including defaults. aoqi@0: * aoqi@0: * @see AnnotationMirror#getElementValues() aoqi@0: * @param a annotation to examine aoqi@0: * @return the values of the annotation's elements, including defaults aoqi@0: */ aoqi@0: Map aoqi@0: getElementValuesWithDefaults(AnnotationMirror a); aoqi@0: aoqi@0: /** aoqi@0: * Returns the text of the documentation ("Javadoc") aoqi@0: * comment of an element. aoqi@0: * aoqi@0: *

A documentation comment of an element is a comment that aoqi@0: * begins with "{@code /**}" , ends with a separate aoqi@0: * "*/", and immediately precedes the element, aoqi@0: * ignoring white space. Therefore, a documentation comment aoqi@0: * contains at least three"{@code *}" characters. The text aoqi@0: * returned for the documentation comment is a processed form of aoqi@0: * the comment as it appears in source code. The leading "{@code aoqi@0: * /**}" and trailing "*/" are removed. For lines aoqi@0: * of the comment starting after the initial "{@code /**}", aoqi@0: * leading white space characters are discarded as are any aoqi@0: * consecutive "{@code *}" characters appearing after the white aoqi@0: * space or starting the line. The processed lines are then aoqi@0: * concatenated together (including line terminators) and aoqi@0: * returned. aoqi@0: * aoqi@0: * @param e the element being examined aoqi@0: * @return the documentation comment of the element, or {@code null} aoqi@0: * if there is none aoqi@0: * @jls 3.6 White Space aoqi@0: */ aoqi@0: String getDocComment(Element e); aoqi@0: aoqi@0: /** aoqi@0: * Returns {@code true} if the element is deprecated, {@code false} otherwise. aoqi@0: * aoqi@0: * @param e the element being examined aoqi@0: * @return {@code true} if the element is deprecated, {@code false} otherwise aoqi@0: */ aoqi@0: boolean isDeprecated(Element e); aoqi@0: aoqi@0: /** aoqi@0: * Returns the binary name of a type element. aoqi@0: * aoqi@0: * @param type the type element being examined aoqi@0: * @return the binary name aoqi@0: * aoqi@0: * @see TypeElement#getQualifiedName aoqi@0: * @jls 13.1 The Form of a Binary aoqi@0: */ aoqi@0: Name getBinaryName(TypeElement type); aoqi@0: aoqi@0: aoqi@0: /** aoqi@0: * Returns the package of an element. The package of a package is aoqi@0: * itself. aoqi@0: * aoqi@0: * @param type the element being examined aoqi@0: * @return the package of an element aoqi@0: */ aoqi@0: PackageElement getPackageOf(Element type); aoqi@0: aoqi@0: /** aoqi@0: * Returns all members of a type element, whether inherited or aoqi@0: * declared directly. For a class the result also includes its aoqi@0: * constructors, but not local or anonymous classes. aoqi@0: * aoqi@0: *

Note that elements of certain kinds can be isolated using aoqi@0: * methods in {@link ElementFilter}. aoqi@0: * aoqi@0: * @param type the type being examined aoqi@0: * @return all members of the type aoqi@0: * @see Element#getEnclosedElements aoqi@0: */ aoqi@0: List getAllMembers(TypeElement type); aoqi@0: aoqi@0: /** aoqi@0: * Returns all annotations present on an element, whether aoqi@0: * directly present or present via inheritance. aoqi@0: * aoqi@0: * @param e the element being examined aoqi@0: * @return all annotations of the element aoqi@0: * @see Element#getAnnotationMirrors aoqi@0: * @see javax.lang.model.AnnotatedConstruct aoqi@0: */ aoqi@0: List getAllAnnotationMirrors(Element e); aoqi@0: aoqi@0: /** aoqi@0: * Tests whether one type, method, or field hides another. aoqi@0: * aoqi@0: * @param hider the first element aoqi@0: * @param hidden the second element aoqi@0: * @return {@code true} if and only if the first element hides aoqi@0: * the second aoqi@0: */ aoqi@0: boolean hides(Element hider, Element hidden); aoqi@0: aoqi@0: /** aoqi@0: * Tests whether one method, as a member of a given type, aoqi@0: * overrides another method. aoqi@0: * When a non-abstract method overrides an abstract one, the aoqi@0: * former is also said to implement the latter. aoqi@0: * aoqi@0: *

In the simplest and most typical usage, the value of the aoqi@0: * {@code type} parameter will simply be the class or interface aoqi@0: * directly enclosing {@code overrider} (the possibly-overriding aoqi@0: * method). For example, suppose {@code m1} represents the method aoqi@0: * {@code String.hashCode} and {@code m2} represents {@code aoqi@0: * Object.hashCode}. We can then ask whether {@code m1} overrides aoqi@0: * {@code m2} within the class {@code String} (it does): aoqi@0: * aoqi@0: *

aoqi@0: * {@code assert elements.overrides(m1, m2, aoqi@0: * elements.getTypeElement("java.lang.String")); } aoqi@0: *
aoqi@0: * aoqi@0: * A more interesting case can be illustrated by the following example aoqi@0: * in which a method in type {@code A} does not override a aoqi@0: * like-named method in type {@code B}: aoqi@0: * aoqi@0: *
aoqi@0: * {@code class A { public void m() {} } }
aoqi@0: * {@code interface B { void m(); } }
aoqi@0: * ...
aoqi@0: * {@code m1 = ...; // A.m }
aoqi@0: * {@code m2 = ...; // B.m }
aoqi@0: * {@code assert ! elements.overrides(m1, m2, aoqi@0: * elements.getTypeElement("A")); } aoqi@0: *
aoqi@0: * aoqi@0: * When viewed as a member of a third type {@code C}, however, aoqi@0: * the method in {@code A} does override the one in {@code B}: aoqi@0: * aoqi@0: *
aoqi@0: * {@code class C extends A implements B {} }
aoqi@0: * ...
aoqi@0: * {@code assert elements.overrides(m1, m2, aoqi@0: * elements.getTypeElement("C")); } aoqi@0: *
aoqi@0: * aoqi@0: * @param overrider the first method, possible overrider aoqi@0: * @param overridden the second method, possibly being overridden aoqi@0: * @param type the type of which the first method is a member aoqi@0: * @return {@code true} if and only if the first method overrides aoqi@0: * the second aoqi@0: * @jls 8.4.8 Inheritance, Overriding, and Hiding aoqi@0: * @jls 9.4.1 Inheritance and Overriding aoqi@0: */ aoqi@0: boolean overrides(ExecutableElement overrider, ExecutableElement overridden, aoqi@0: TypeElement type); aoqi@0: aoqi@0: /** aoqi@0: * Returns the text of a constant expression representing a aoqi@0: * primitive value or a string. aoqi@0: * The text returned is in a form suitable for representing the value aoqi@0: * in source code. aoqi@0: * aoqi@0: * @param value a primitive value or string aoqi@0: * @return the text of a constant expression aoqi@0: * @throws IllegalArgumentException if the argument is not a primitive aoqi@0: * value or string aoqi@0: * aoqi@0: * @see VariableElement#getConstantValue() aoqi@0: */ aoqi@0: String getConstantExpression(Object value); aoqi@0: aoqi@0: /** aoqi@0: * Prints a representation of the elements to the given writer in aoqi@0: * the specified order. The main purpose of this method is for aoqi@0: * diagnostics. The exact format of the output is not aoqi@0: * specified and is subject to change. aoqi@0: * aoqi@0: * @param w the writer to print the output to aoqi@0: * @param elements the elements to print aoqi@0: */ aoqi@0: void printElements(java.io.Writer w, Element... elements); aoqi@0: aoqi@0: /** aoqi@0: * Return a name with the same sequence of characters as the aoqi@0: * argument. aoqi@0: * aoqi@0: * @param cs the character sequence to return as a name aoqi@0: * @return a name with the same sequence of characters as the argument aoqi@0: */ aoqi@0: Name getName(CharSequence cs); aoqi@0: aoqi@0: /** aoqi@0: * Returns {@code true} if the type element is a functional interface, {@code false} otherwise. aoqi@0: * aoqi@0: * @param type the type element being examined aoqi@0: * @return {@code true} if the element is a functional interface, {@code false} otherwise aoqi@0: * @jls 9.8 Functional Interfaces aoqi@0: * @since 1.8 aoqi@0: */ aoqi@0: boolean isFunctionalInterface(TypeElement type); aoqi@0: }