Package: org.codehaus.groovy.ast

## [Java] Class ModuleNode

- org.codehaus.groovy.ast.ModuleNode

-     public class ModuleNode
      extends ASTNode

  Represents a module, which consists typically of a class declaration but could include some imports, some statements and multiple classes intermixed with statements like scripts in Python or Ruby

- - ### Constructor Summary

    Constructors
    Constructor and description
    `ModuleNode(SourceUnit context)` Creates a module node for the specified compilation context.
    `ModuleNode(CompileUnit unit)` Creates a module node for batch compilation.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public void` | `addClass(ClassNode node)` Adds a class definition to this module.
    `` | `public void` | `addImport(String name, ClassNode type)` Registers a regular import (e.g., `import java.util.List`).
    `` | `public void` | `addImport(String name, ClassNode type, List<AnnotationNode> annotations)` Registers a regular import with optional annotations.
    `` | `public void` | `addMethod(MethodNode node)` Adds a module-level method definition.
    `` | `public void` | `addModuleStarImport(String packageName, List<AnnotationNode> annotations)` Adds a module-level star import with optional annotations.
    `` | `public void` | `addStarImport(String packageName)` Registers a wildcard import (e.g., `import java.util.*`).
    `` | `public void` | `addStarImport(String packageName, List<AnnotationNode> annotations)` Registers a wildcard import with optional annotations.
    `` | `public void` | `addStatement(Statement node)` Adds a statement to the module's statement block.
    `` | `public void` | `addStaticImport(ClassNode type, String memberName, String simpleName)` Registers a static import (e.g., `import static java.lang.Math.PI`).
    `` | `public void` | `addStaticImport(ClassNode type, String memberName, String simpleName, List<AnnotationNode> annotations)` Registers a static import with optional annotations.
    `` | `public void` | `addStaticStarImport(String name, ClassNode type)` Registers a static wildcard import (e.g., `import static java.lang.Math.*`).
    `` | `public void` | `addStaticStarImport(String name, ClassNode type, List<AnnotationNode> annotations)` Registers a static wildcard import with optional annotations.
    `` | `protected ClassNode` | `createStatementsClass()` Creates a synthetic class wrapping this module's statement and method definitions.
    `` | `protected String` | `extractClassFromFileDescription()` Extracts the class name from the module's description (typically a file path).
    `` | `public List<ClassNode>` | `getClasses()` Returns the module's class definitions.
    `` | `public SourceUnit` | `getContext()` Returns the source unit for this module (single-file compilation context).
    `` | `public String` | `getDescription()` Returns a description of this module.
    `` | `public ImportNode` | `getImport(String alias)` Looks up an import node by its alias name.
    `` | `public ClassNode` | `getImportType(String alias)` Looks up the class type for a regular import by its alias name.
    `` | `public List<ImportNode>` | `getImports()` Returns a copy of the module's regular import declarations.
    `` | `public String` | `getMainClassName()` Returns the simple name of the main class for this module.
    `` | `public List<MethodNode>` | `getMethods()` Returns the module's top-level method definitions.
    `` | `public List<ImportNode>` | `getModuleStarImports()` Registers a module-level star import (e.g., `import module java.base`).
    `` | `public PackageNode` | `getPackage()` Returns the package node for this module.
    `` | `public String` | `getPackageName()` Returns the module's package name.
    `` | `public ClassNode` | `getScriptClassDummy()` Returns a synthetic class wrapping this module's statements and methods.
    `` | `public List<ImportNode>` | `getStarImports()` Returns wildcard (star) import declarations (e.g., `import java.util.*`).
    `` | `public BlockStatement` | `getStatementBlock()` Returns the block of statements defined at module scope.
    `` | `public Map<String, ImportNode>` | `getStaticImports()` Returns static import declarations (e.g., `import static java.lang.Math.PI`).
    `` | `public Map<String, ImportNode>` | `getStaticStarImports()` Returns static wildcard import declarations (e.g., `import static java.lang.Math.*`).
    `` | `public CompileUnit` | `getUnit()` Returns the compile unit managing this module (batch compilation context).
    `` | `public boolean` | `hasImportsResolved()` Checks whether imports have been resolved for this module.
    `` | `public boolean` | `hasPackage()` Checks whether this module declares a package.
    `` | `public boolean` | `hasPackageName()` Checks whether this module has a named package (not default package).
    `` | `public boolean` | `isEmpty()` Checks whether this module is empty (no classes or statements).
    `` | `public void` | `setDescription(String description)` Sets a description for this module (typically the source file name).
    `` | `public void` | `setImportsResolved(boolean importsResolved)` Marks whether imports have been resolved for this module.
    `` | `public void` | `setPackage(PackageNode packageNode)` Sets the package declaration for this module.
    `` | `public void` | `setPackageName(String packageName)` Sets the package for this module by name.
    `` | `public void` | `sortClasses()` Sorts classes in dependency order based on class hierarchy.
    `` | `public void` | `visit(GroovyCodeVisitor visitor)` Accepts a code visitor for AST traversal and processing.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class ASTNode` | `copyNodeMetaData, getColumnNumber, getLastColumnNumber, getLastLineNumber, getLineNumber, getMetaDataMap, getText, setColumnNumber, setLastColumnNumber, setLastLineNumber, setLineNumber, setMetaDataMap, setSourcePosition, visit`

- - ### Constructor Detail

    - #### public ModuleNode(SourceUnit context)

      Creates a module node for the specified compilation context. Used when compiling a single Groovy file with full source location tracking.

      Parameters:
        `context` - the source unit providing file path, line mapping, and error context

    - #### public ModuleNode(CompileUnit unit)

      Creates a module node for batch compilation. Used when compiling multiple classes in a single compilation batch.

      Parameters:
        `unit` - the compile unit managing this module's classes

  - ### Method Detail

    - #### public void addClass(ClassNode node)

      Adds a class definition to this module. If this is the first class added, its name is recorded as the main class name. The class's containing module is set to this module, and it's registered with the compile unit if present.

      throws:
        SyntaxException if a class with the same name already exists in this module
      Parameters:
        `node` - the ClassNode to add

    - #### public void addImport(String name, ClassNode type)

      Registers a regular import (e.g., `import java.util.List`). The alias name will be used to reference the imported class.

      throws:
        SyntaxException if the name conflicts with an existing declaration
      Parameters:
        `name` - the alias name for this import
        `type` - the ClassNode to import

    - #### public void addImport(String name, ClassNode type, List<AnnotationNode> annotations)

      Registers a regular import with optional annotations. The alias name will be used to reference the imported class.

      throws:
        SyntaxException if the name conflicts with an existing declaration
      Parameters:
        `name` - the alias name for this import
        `type` - the ClassNode to import
        `annotations` - annotations to attach to this import

    - #### public void addMethod(MethodNode node)

      Adds a module-level method definition. Module-level methods are typically found in scripts or in trait interface definitions.

      Parameters:
        `node` - the MethodNode to add

    - #### public void addModuleStarImport(String packageName, List<AnnotationNode> annotations)

      Adds a module-level star import with optional annotations. These are tracked separately from regular wildcard imports for import resolution.

      Parameters:
        `packageName` - the module package name
        `annotations` - annotations to attach to this import
      Since:
        6.0.0

    - #### public void addStarImport(String packageName)

      Registers a wildcard import (e.g., `import java.util.*`). All public classes in the package become available without qualification.

      Parameters:
        `packageName` - the package name (e.g., "java.util")

    - #### public void addStarImport(String packageName, List<AnnotationNode> annotations)

      Registers a wildcard import with optional annotations. All public classes in the package become available without qualification.

      Parameters:
        `packageName` - the package name (e.g., "java.util")
        `annotations` - annotations to attach to this import

    - #### public void addStatement(Statement node)

      Adds a statement to the module's statement block. Module-level statements are collected and later wrapped in a synthetic class during compilation (controlled by createClassForStatements).

      Parameters:
        `node` - the Statement to add

    - #### public void addStaticImport(ClassNode type, String memberName, String simpleName)

      Registers a static import (e.g., `import static java.lang.Math.PI`). A specific static member from a class becomes available without qualification.

      throws:
        SyntaxException if the simpleName conflicts with existing declarations
      Parameters:
        `type` - the ClassNode containing the static member
        `memberName` - the name of the static member (field or method)
        `simpleName` - the alias name by which this member is imported

    - #### public void addStaticImport(ClassNode type, String memberName, String simpleName, List<AnnotationNode> annotations)

      Registers a static import with optional annotations. A specific static member from a class becomes available without qualification.

      throws:
        SyntaxException if the simpleName conflicts with existing declarations
      Parameters:
        `type` - the ClassNode containing the static member
        `memberName` - the name of the static member (field or method)
        `simpleName` - the alias name by which this member is imported
        `annotations` - annotations to attach to this import

    - #### public void addStaticStarImport(String name, ClassNode type)

      Registers a static wildcard import (e.g., `import static java.lang.Math.*`). All static members from a class become available without qualification.

      Parameters:
        `name` - the package/class name for this static star import
        `type` - the ClassNode from which to import static members

    - #### public void addStaticStarImport(String name, ClassNode type, List<AnnotationNode> annotations)

      Registers a static wildcard import with optional annotations. All static members from a class become available without qualification.

      Parameters:
        `name` - the package/class name for this static star import
        `type` - the ClassNode from which to import static members
        `annotations` - annotations to attach to this import

    - #### protected ClassNode createStatementsClass()

      Creates a synthetic class wrapping this module's statement and method definitions. Generates a `main(String[])` method for script execution and a `run()` method for statement execution. Only invoked when the module contains module-level code (scripts or statements).

      Returns:
        a ClassNode representing the synthetic wrapper class with generated methods

    - #### protected String extractClassFromFileDescription()

      Extracts the class name from the module's description (typically a file path). Strips file extensions, path separators, and URI schemes to derive a valid class name. Used when generating synthetic script wrapper classes.

      Returns:
        a valid class name derived from the description

    - #### public List<ClassNode> getClasses()

      Returns the module's class definitions. If `createClassForStatements` is true and there are module-level statements, methods, or this is a package-info script, a synthetic class is created to wrap them. This class is automatically inserted at the beginning of the list. The flag is then reset to prevent future synthesis.

      Returns:
        list of ClassNode definitions (may include synthetic wrapper for statements)

    - #### public SourceUnit getContext()

      Returns the source unit for this module (single-file compilation context). Provides access to source code, line mappings, and error reporting.

      Returns:
        the SourceUnit, or null if compiled as part of a batch

    - #### public String getDescription()

      Returns a description of this module. Typically the source file name if available (via context), otherwise a user-supplied description.

      Returns:
        the module description (usually the file path), or null if not set

    - #### public ImportNode getImport(String alias)

      Looks up an import node by its alias name. Searches regular imports and returns the matching node. Caches import alias mappings as node metadata for performance.

      Parameters:
        `alias` - the imported name to look up
      Returns:
        the ImportNode for that import, or null if not found

    - #### public ClassNode getImportType(String alias)

      Looks up the class type for a regular import by its alias name. Resolves simple names to the actual class they reference.

      Parameters:
        `alias` - the imported name to look up
      Returns:
        the ClassNode for that import, or null if not found

    - #### public List<ImportNode> getImports()

      Returns a copy of the module's regular import declarations. Includes both simple class imports (e.g., `import java.util.List`) and aliased imports. Does not include star imports or static imports.

      Returns:
        a copy of the ImportNode list for regular imports

    - #### public String getMainClassName()

      Returns the simple name of the main class for this module. For scripts, this is the synthetic wrapper class name. For modules with classes, this is typically the first class added.

      Returns:
        the main class name, or null if not set

    - #### public List<MethodNode> getMethods()

      Returns the module's top-level method definitions. These are module-level methods typically found in scripts or trait interfaces.

      Returns:
        list of MethodNode definitions

    - #### public List<ImportNode> getModuleStarImports()

      Registers a module-level star import (e.g., `import module java.base`). Returns module star imports, which are separate from regular wildcard imports for proper JLS 6.4.1 shadowing resolution (type-import-on-demand shadowing).

      Returns:
        star imports from `import module` declarations
      Since:
        6.0.0

    - #### public PackageNode getPackage()

      Returns the package node for this module. Contains the package declaration and associated annotations.

      Returns:
        the PackageNode, or null if none is declared

    - #### public String getPackageName()

      Returns the module's package name. Returns null if no package is declared (uses the default package).

      Returns:
        the fully qualified package name, or null for the default package

    - #### public ClassNode getScriptClassDummy()

      Returns a synthetic class wrapping this module's statements and methods. Used for scripts: module-level code is collected and placed in a generated class with a `main(String[])` method. Configures the base class based on compiler config.

      throws:
        RuntimeException if module description is not set
      Returns:
        a ClassNode for script execution

    - #### public List<ImportNode> getStarImports()

      Returns wildcard (star) import declarations (e.g., `import java.util.*`). These imports make all public classes in a package available without qualification.

      Returns:
        list of ImportNode for wildcard imports

    - #### public BlockStatement getStatementBlock()

      Returns the block of statements defined at module scope. These statements become part of the script's run() method (if module is a script) or remain at module level (if module contains only classes).

      Returns:
        the BlockStatement containing module-level code

    - #### public Map<String, ImportNode> getStaticImports()

      Returns static import declarations (e.g., `import static java.lang.Math.PI`). Maps simple names to ImportNode objects for static member imports.

      Returns:
        map from simple name to ImportNode for static imports

    - #### public Map<String, ImportNode> getStaticStarImports()

      Returns static wildcard import declarations (e.g., `import static java.lang.Math.*`). Maps package names to ImportNode objects for static star imports.

      Returns:
        map from package name to ImportNode for static star imports

    - #### public CompileUnit getUnit()

      Returns the compile unit managing this module (batch compilation context). Null if this module was compiled individually.

      Returns:
        the CompileUnit, or null for single-file compilation

    - #### public boolean hasImportsResolved()

      Checks whether imports have been resolved for this module. Import resolution converts import aliases to fully qualified class names and processes import conflicts. This flag tracks whether that phase is complete.

      Returns:
        true if import resolution has been performed

    - #### public boolean hasPackage()

      Checks whether this module declares a package.

      Returns:
        true if a package is declared, false for the default package

    - #### public boolean hasPackageName()

      Checks whether this module has a named package (not default package).

      Returns:
        true if a non-null package name is declared

    - #### public boolean isEmpty()

      Checks whether this module is empty (no classes or statements). An empty module compiles to no bytecode output.

      Returns:
        true if both class list and statement block are empty

    - #### public void setDescription(String description)

      Sets a description for this module (typically the source file name).

      Parameters:
        `description` - the description to set

    - #### public void setImportsResolved(boolean importsResolved)

      Marks whether imports have been resolved for this module. Set to true after the import resolution phase completes.

      Parameters:
        `importsResolved` - true to mark imports as resolved

    - #### public void setPackage(PackageNode packageNode)

      Sets the package declaration for this module.

      Parameters:
        `packageNode` - the PackageNode for this module

    - #### public void setPackageName(String packageName)

      Sets the package for this module by name. Creates a new PackageNode with the given package name.

      Parameters:
        `packageName` - the fully qualified package name

    - #### public void sortClasses()

      Sorts classes in dependency order based on class hierarchy. Inner classes and dependent classes are ordered after their dependencies. This ensures that base classes are defined before derived classes during compilation. Does nothing if the module is empty or contains only one class.

    - #### public void visit(GroovyCodeVisitor visitor)

      Accepts a code visitor for AST traversal and processing. Implementation is empty; module-level visitation typically proceeds directly to classes and methods contained within.

      Parameters:
        `visitor` - the GroovyCodeVisitor to process this node