src/java.compiler/share/classes/javax/lang/model/util/Elements.java

@@ -27,10 +27,11 @@
 
 
 import java.util.List;
 import java.util.Map;
 
+import javax.lang.model.AnnotatedConstruct;
 import javax.lang.model.element.*;
 
 
 /**
  * Utility methods for operating on program elements.

@@ -134,10 +135,144 @@
      * @return {@code true} if the element is deprecated, {@code false} otherwise
      */
     boolean isDeprecated(Element e);
 
     /**
+     * Returns the <em>naturalness</em> of the given element.
+     *
+     * <p>Note that if an element logically has a naturalness other
+     * than {@link Naturalness#NATURAL NATURAL}, an implementation may
+     * not be able to reliably determine this status if the element 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 Naturalness#NATURAL NATURAL}.
+     *
+     * @param e  the element being examined
+     * @return the naturalness of the given element
+     * @since 9
+     */
+    default Naturalness getNaturalness(Element e) {
+        return Naturalness.NATURAL;
+    }
+
+    /**
+     * Returns the <em>naturalness</em> of the given annotation mirror.
+     *
+     * One example of a mandated construct is the
+     * implicitly declared <em>container annotation</em> used to hold
+     * repeated base annotations of a repeatable annotation type.
+     *
+     * <p>Note that if an annotation mirror logically has a
+     * naturalness other than {@link Naturalness#NATURAL NATURAL}, an
+     * implementation may not be able to reliably determine this
+     * status if the element 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 Naturalness#NATURAL NATURAL}.
+     *
+     * @param c the construct the annotation mirror modifies
+     * @param a  the annotation mirror being examined
+     * @return the naturalness 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 Naturalness getNaturalness(AnnotatedConstruct c,
+                                       AnnotationMirror a) {
+        return Naturalness.NATURAL;
+    }
+
+    /**
+     * Returns the <em>naturalness</em> of the given module directive.
+     *
+     * <p>Note that if a directive mirror logically has a naturalness
+     * other than {@link Naturalness#NATURAL NATURAL}, an
+     * implementation may not be able to reliably determine this
+     * status if the element 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 Naturalness#NATURAL NATURAL}.
+     *
+     * @param m the module of the directive
+     * @param directive  the module directive being examined
+     * @return the naturalness of the given directive
+     * @since 9
+     */
+    default Naturalness getNaturalness(ModuleElement m,
+                                       ModuleElement.Directive directive) {
+        return Naturalness.NATURAL;
+    }
+
+    /**
+     * The <em>naturalness</em> of a construct. The naturalness of a
+     * construct concerns the consistency between how a construct is
+     * declared in source code (explicitly, implicitly, or not at all)
+     * compared to how the construct is represented in this model.
+     *
+     * <p>Note that it is possible additional kinds of naturalness
+     * will be added in future versions of the platform.
+     *
+     * @jls 13.1 The Form of a Binary
+     * @since 9
+     */
+    enum Naturalness {
+        /**
+         * A natural construct is explicitly declared in source code.
+         */
+        NATURAL,
+
+       /**
+         * A mandated construct is one 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 <em>default
+         * constructor</em> in a class that contains no explicit
+         * constructor declarations.
+         *
+         * Another example of a mandated construct is the implicitly
+         * declared <em>container annotation</em> 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. Synthetic
+         * constructs are commonly translation artifacts created by
+         * compiler.
+         */
+        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 <i>binary name</i> of a type element.
      *
      * @param type  the type element being examined
      * @return the binary name
      *