Package: org.codehaus.groovy.ast.decompiled

## [Java] Class AsmReferenceResolver

- org.codehaus.groovy.ast.decompiled.AsmReferenceResolver

-     public class AsmReferenceResolver
      extends Object

  Helper class for resolving class references encountered in bytecode stubs decompiled from compiled classes. Bridges between ASM's internal type descriptors/names and Groovy's ClassNode representation by consulting both classes currently being compiled in the compilation unit and already-loaded classes via the ClassNodeResolver.

  ## Resolution Strategy

  AsmReferenceResolver implements a two-tier lookup strategy:

  1. Compilation-time classes: First checks the compilation unit's AST for classes being compiled in the same batch. This ensures references to companion classes resolve correctly.
  2. Runtime classes: If not found in the compilation unit, delegates to the ClassNodeResolver, which consults already-compiled and third-party classes.

  ## Type Descriptor Handling

  The resolver handles multiple bytecode formats:

  - Primitive types: Resolved via ClassHelper.make (e.g., `"I"` ? `int.class`).
  - Object types: Converted from JVMS internal names (e.g., `"java/lang/String"`) to dot notation and resolved via resolveClass(String).
  - Array types: Handled recursively by resolveType(Type) and marked via ClassNode.makeArray.

  ## Error Handling

  The resolver distinguishes between two resolution modes:

  - resolveClass(String) - Throws NoClassDefFoundError if the class cannot be resolved. Used when a type is required.
  - resolveClassNullable(String) - Returns `null` if the class cannot be resolved. Used for optional type information (e.g., exception types).

  ## Thread Safety

  AsmReferenceResolver instances are typically created once per compilation unit and are thread-safe for concurrent read access. The underlying ClassNodeResolver and CompilationUnit manage their own synchronization.

  See Also:
    DecompiledClassNode
    AsmDecompiler
    ClassNodeResolver
    CompilationUnit

- - ### Constructor Summary

    Constructors
    Constructor and description
    `AsmReferenceResolver(ClassNodeResolver resolver, CompilationUnit unit)` Creates an ASM reference resolver for a compilation unit.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public ClassNode` | `resolveClass(String className)` Resolves a fully qualified class name to a ClassNode.
    `` | `public ClassNode` | `resolveClassNullable(String className)` Attempts to resolve a fully qualified class name to a ClassNode, returning `null` if not found.
    `` | `public Class` | `resolveJvmClass(String name)` Resolves a fully qualified class name to a runtime JVM Class object.
    `` | `public ClassNode` | `resolveType(org.objectweb.asm.Type type)` Resolves an ASM org.objectweb.asm.Type to a ClassNode, handling array types by wrapping element types.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### public AsmReferenceResolver(ClassNodeResolver resolver, CompilationUnit unit)

      Creates an ASM reference resolver for a compilation unit.

      Parameters:
        `resolver` - the ClassNodeResolver used to resolve class names
        `unit` - the CompilationUnit containing classes being compiled and metadata

  - ### Method Detail

    - #### public ClassNode resolveClass(String className)

      Resolves a fully qualified class name to a ClassNode. First checks classes being compiled in this unit, then consults the resolver for already-loaded classes.

      throws:
        NoClassDefFoundError if the class cannot be resolved
      Parameters:
        `className` - the fully qualified class name
      Returns:
        the resolved ClassNode

    - #### public ClassNode resolveClassNullable(String className)

      Attempts to resolve a fully qualified class name to a ClassNode, returning `null` if not found. First checks classes being compiled in this unit, then consults the resolver for already-loaded classes.

      Parameters:
        `className` - the fully qualified class name
      Returns:
        the resolved ClassNode, or `null` if not resolvable

    - #### public Class resolveJvmClass(String name)

      Resolves a fully qualified class name to a runtime JVM Class object. Uses the compilation unit's class loader to load the class.

      throws:
        GroovyBugError if the class cannot be loaded (wrapped ClassNotFoundException)
      Parameters:
        `name` - the fully qualified class name
      Returns:
        the loaded runtime Class

    - #### public ClassNode resolveType(org.objectweb.asm.Type type)

      Resolves an ASM org.objectweb.asm.Type to a ClassNode, handling array types by wrapping element types.

      throws:
        NoClassDefFoundError if an object type cannot be resolved
      Parameters:
        `type` - the ASM type to resolve
      Returns:
        the corresponding ClassNode, with dimensions for array types