During annotation processing, operating on incomplete or * erroneous programs is necessary; however, there are fewer --- old/src/java.compiler/share/classes/javax/lang/model/util/Elements.java 2016-10-05 17:34:37.943715828 -0700 +++ new/src/java.compiler/share/classes/javax/lang/model/util/Elements.java 2016-10-05 17:34:37.843715823 -0700 @@ -29,6 +29,7 @@ import java.util.List; import java.util.Map; +import javax.lang.model.AnnotatedConstruct; import javax.lang.model.element.*; @@ -136,6 +137,167 @@ boolean isDeprecated(Element e); /** + * Returns the origin of the given element. + * + *
Note that if this method returns {@link Origin#EXPLICIT + * EXPLICIT} and the element was created from a class file, then + * the element may not, in fact, correspond to an explicitly + * declared construct in source code. This is due to limitations + * of the fidelity of the class file format in preserving + * information from source code. For example, at least some + * versions of the class file format do not preserve whether a + * constructor was explicitly declared by the programmer or was + * implicitly declared as the default constructor. + * + * @implSpec The default implementation of this method returns + * {@link Origin#EXPLICIT EXPLICIT}. + * + * @param e the element being examined + * @return the origin of the given element + * @since 9 + */ + default Origin getOrigin(Element e) { + return Origin.EXPLICIT; + } + + /** + * Returns the origin of the given annotation mirror. + * + * An annotation mirror is {@linkplain Origin#MANDATED mandated} + * if it is an implicitly declared container annotation + * used to hold repeated annotations of a repeatable annotation + * type. + * + *
Note that if this method returns {@link Origin#EXPLICIT + * EXPLICIT} and the annotation mirror was created from a class + * file, then the element may not, in fact, correspond to an + * explicitly declared construct in source code. This is due to + * limitations of the fidelity of the class file format in + * preserving information from source code. For example, at least + * some versions of the class file format do not preserve whether + * an annotation was explicitly declared by the programmer or was + * implicitly declared as a container annotation. + * + * @implSpec The default implementation of this method returns + * {@link Origin#EXPLICIT EXPLICIT}. + * + * @param c the construct the annotation mirror modifies + * @param a the annotation mirror being examined + * @return the origin of the given annotation mirror + * @jls 9.6.3 Repeatable Annotation Types + * @jls 9.7.5 Multiple Annotations of the Same Type + * @since 9 + */ + default Origin getOrigin(AnnotatedConstruct c, + AnnotationMirror a) { + return Origin.EXPLICIT; + } + + /** + * Returns the origin of the given module directive. + * + *
Note that if this method returns {@link Origin#EXPLICIT + * EXPLICIT} and the module directive was created from a class + * file, then the module directive may not, in fact, correspond to + * an explicitly declared construct in source code. This is due to + * limitations of the fidelity of the class file format in + * preserving information from source code. For example, at least + * some versions of the class file format do not preserve whether + * a {@code uses} directive was explicitly declared by the + * programmer or was added as a synthetic construct. + * + *
Note that an implementation may not be able to reliably + * determine the origin status of the directive if the directive + * is created from a class file due to limitations of the fidelity + * of the class file format in preserving information from source + * code. + * + * @implSpec The default implementation of this method returns + * {@link Origin#EXPLICIT EXPLICIT}. + * + * @param m the module of the directive + * @param directive the module directive being examined + * @return the origin of the given directive + * @since 9 + */ + default Origin getOrigin(ModuleElement m, + ModuleElement.Directive directive) { + return Origin.EXPLICIT; + } + + /** + * The origin of an element or other language model + * item. The origin of an element or item models how a construct + * in a program is declared in the source code, explicitly, + * implicitly, etc. + * + *
Note that it is possible additional kinds of origin values + * will be added in future versions of the platform. + * + * @jls 13.1 The Form of a Binary + * @since 9 + */ + public enum Origin { + /** + * Describes a construct explicitly declared in source code. + */ + EXPLICIT, + + /** + * A mandated construct is one that is not explicitly declared + * in the source code, but whose presence is mandated by the + * specification. Such a construct is said to be implicitly + * declared. + * + * One example of a mandated element is a default + * constructor in a class that contains no explicit + * constructor declarations. + * + * Another example of a mandated construct is an implicitly + * declared container annotation used to hold + * multiple annotations of a repeatable annotation type. + * + * @jls 8.8.9 Default Constructor + * @jls 9.6.3 Repeatable Annotation Types + * @jls 9.7.5 Multiple Annotations of the Same Type + */ + MANDATED, + + /** + * A synthetic construct is one that is neither implicitly nor + * explicitly declared in the source code. Such a construct is + * typically a translation artifact created by a compiler. + */ + SYNTHETIC; + + /** + * Returns {@code true} for values corresponding to constructs + * that are implicitly or explicitly declared, {@code false} + * otherwise. + * @return {@code true} for {@link EXPLICIT} and {@link + * MANDATED}, {@code false} otherwise. + */ + public boolean isDeclared() { + return this != SYNTHETIC; + } + } + + /** + * Returns {@code true} if the executable element is a bridge + * method, {@code false} otherwise. + * + * @implSpec The default implementation of this method returns {@code false}. + * + * @param e the executable being examined + * @return {@code true} if the executable element is a bridge + * method, {@code false} otherwise + * @since 9 + */ + default boolean isBridge(ExecutableElement e) { + return false; + } + + /** * Returns the binary name of a type element. * * @param type the type element being examined