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

*** 27,36 ****
--- 27,37 ----
  
  
  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,143 ****
--- 135,254 ----
       * @return {@code true} if the element is deprecated, {@code false} otherwise
       */
      boolean isDeprecated(Element e);
  
      /**
+      * Returns the <em>naturalness</em> of the given element.
+      *
+      * @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.
+      *
+      * @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.
+      *
+      * @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.
+      *
+      * 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 not explicitly declared in the
+          * source code, but its presence is mandated by the
+          * specification to be implicitly declared.
+          *
+          * One example of a mandated construct is a <em>default
+          * constructor</em> in a class that contains no constructor
+          * declarations.
+          *
+          * Another example is the implicitly declared <em>container
+          * annotation</em> used to hold repeated base 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 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
       *