Summary

Add a method to access the module declaration in a module compilation unit.

Problem

The Compiler Tree API models a Compilation Unit, but does not provide an appropriate way to access the Module Declaration in the case of the Compilation Unit being a Modular Compilation Unit.

There's a subsidiary problem (bug) that the module declaration is returned in the list of type declarations returned by CompilationUnitTree.getTypeDecls. But, a module declaration is not a type declaration, and should not be confused as such.

Solution

Add a new method to access the module declaration. Do not return the module declaration in the list of type declarations.

Specification

diff --git a/src/jdk.compiler/share/classes/com/sun/source/tree/CompilationUnitTree.java b/src/jdk.compiler/share/classes/com/sun/source/tree/CompilationUnitTree.java
index 7bbd93d37f7..a9aff465d0c 100644
--- a/src/jdk.compiler/share/classes/com/sun/source/tree/CompilationUnitTree.java
+++ b/src/jdk.compiler/share/classes/com/sun/source/tree/CompilationUnitTree.java
@@ -29,16 +29,29 @@ import java.util.List;
 import javax.tools.JavaFileObject;

 /**
- * Represents the abstract syntax tree for compilation units (source
- * files) and package declarations (package-info.java).
+ * Represents the abstract syntax tree for ordinary compilation units
+ * and modular compilation units.
  *
  * @jls 7.3 Compilation Units
  * @jls 7.4 Package Declarations
+ * @jls 7.7 Module Declarations
  *
  * @author Peter von der Ahé
  * @since 1.6
  */
 public interface CompilationUnitTree extends Tree {
+
+    /**
+     * Returns the module tree associated with this compilation unit,
+     * or {@code null} if there is no module declaration.
+     * @return the module tree
+     * @implSpec This implementation throws {@code UnsupportedOperationException}
+     * @since 17
+     */
+     default ModuleTree getModule() {
+         throw new UnsupportedOperationException();
+     }
+
     /**
      * Returns the annotations listed on any package declaration
      * at the head of this compilation unit, or {@code null} if there
@@ -64,15 +77,18 @@ public interface CompilationUnitTree extends Tree {
     PackageTree getPackage();

     /**
-     * Returns the import declarations appearing in this compilation unit.
+     * Returns the import declarations appearing in this compilation unit,
+     * or an empty list if there are no import declarations.
      * @return the import declarations
      */
     List<? extends ImportTree> getImports();

     /**
-     * Returns the type declarations appearing in this compilation unit.
+     * Returns the type declarations appearing in this compilation unit,
+     * or an empty list if there are no type declarations.
      * The list may also include empty statements resulting from
      * extraneous semicolons.
+     * A modular compilation unit does not contain any type declarations.
      * @return the type declarations
      */
     List<? extends Tree> getTypeDecls();
@@ -84,8 +100,8 @@ public interface CompilationUnitTree extends Tree {
     JavaFileObject getSourceFile();

     /**
-     * Returns the line map for this compilation unit, if available.
-     * Returns {@code null} if the line map is not available.
+     * Returns the line map for this compilation unit, if available,
+     * or {@code null} if the line map is not available.
      * @return the line map for this compilation unit
      */
     LineMap getLineMap();