Package: org.codehaus.groovy.classgen.asm

## [Java] Class InvocationWriter

- org.codehaus.groovy.classgen.asm.InvocationWriter

-     public class InvocationWriter
      extends Object

  Handles method and constructor invocations, generating appropriate bytecode.

- - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `static MethodCaller` | `castToVargsArray` | Method caller for casting an array of arguments to a varargs array.
    `protected WriterController` | `controller` | The controller coordinating all bytecode writers for the current class.
    `protected Expression` | `currentCall` | The expression currently being compiled as a call, used for optimizations.
    `static MethodCaller` | `invokeClosureMethod` | deprecated: Use direct closure invocation instead
    `static MethodCallerMultiAdapter` | `invokeMethod` | Multi-adapter for generic `invokeMethod` call-site variants.
    `static MethodCallerMultiAdapter` | `invokeMethodOnCurrent` | Multi-adapter for `invokeMethodOnCurrent` call-site variants.
    `static MethodCallerMultiAdapter` | `invokeMethodOnSuper` | Multi-adapter for `invokeMethodOnSuper` call-site variants.
    `static MethodCallerMultiAdapter` | `invokeStaticMethod` | Multi-adapter for `invokeStaticMethod` call-site variants.

  - ### Constructor Summary

    Constructors
    Constructor and description
    `InvocationWriter(WriterController controller)` Creates an invocation writer with the given controller.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public void` | `castNonPrimitiveToBool(ClassNode last)` Unboxes a non-primitive value on the operand stack to a primitive `boolean`.
    `` | `public void` | `castToNonPrimitiveIfNecessary(ClassNode sourceType, ClassNode targetType)` Converts sourceType to a non-primitive by using Groovy casting.
    `` | `public void` | `coerce(ClassNode from, ClassNode target)` Emits a Groovy `as` coercion from `from` to `target`.
    `` | `protected void` | `finnishConstructorCall(ConstructorNode cn, String ownerDescriptor, int argsToRemove)` Emits the `INVOKESPECIAL` `<init>` instruction and updates the operand stack after a constructor call set up by prepareConstructorCall.
    `` | `protected String` | `getMethodName(Expression message)` Extracts the constant method name string from a message expression.
    `` | `protected void` | `loadArguments(List<Expression> arguments, Parameter[] parameters)` Evaluates and loads each argument expression, handling varargs packing.
    `` | `public static ArgumentListExpression` | `makeArgumentList(Expression arguments)` Converts an expression to an argument list.
    `` | `protected boolean` | `makeCachedCall(Expression origin, ClassExpression sender, Expression receiver, Expression message, Expression arguments, MethodCallerMultiAdapter adapter, boolean safe, boolean spreadSafe, boolean implicitThis, boolean containsSpreadExpression)` Attempts to emit a call-site-cached invocation (or invokedynamic).
    `` | `public void` | `makeCall(Expression origin, Expression receiver, Expression message, Expression arguments, MethodCallerMultiAdapter adapter, boolean safe, boolean spreadSafe, boolean implicitThis)` Generates bytecode for a method call.
    `` | `protected void` | `makeCall(Expression origin, ClassExpression sender, Expression receiver, Expression message, Expression arguments, MethodCallerMultiAdapter adapter, boolean safe, boolean spreadSafe, boolean implicitThis)` Generates bytecode for a method invocation, choosing among direct call, call-site caching, and uncached (ScriptBytecodeAdapter) strategies.
    `` | `protected boolean` | `makeClassForNameCall(Expression origin, Expression receiver, Expression message, Expression arguments)` if Class.forName(x) is recognized, make a direct method call
    `` | `protected boolean` | `makeDirectCall(Expression origin, Expression receiver, Expression message, Expression arguments, MethodCallerMultiAdapter adapter, boolean implicitThis, boolean containsSpreadExpression)` Attempts to emit a direct (statically resolved) method call.
    `` | `public final void` | `makeSingleArgumentCall(Expression receiver, String message, Expression arguments)` Delegates to makeSingleArgumentCall(Expression, String, Expression, boolean) with `safe = false`.
    `` | `public void` | `makeSingleArgumentCall(Expression receiver, String message, Expression arguments, boolean safe)` Generates a single-argument method call via the call-site writer.
    `` | `protected void` | `makeUncachedCall(Expression origin, ClassExpression sender, Expression receiver, Expression message, Expression arguments, MethodCallerMultiAdapter adapter, boolean safe, boolean spreadSafe, boolean implicitThis, boolean containsSpreadExpression)` Emits an uncached invocation via ScriptBytecodeAdapter.
    `` | `protected String` | `prepareConstructorCall(ConstructorNode cn)` Emits the `NEW` and `DUP` instructions for a constructor call and returns the internal class name of the type being constructed.
    `` | `protected boolean` | `writeAICCall(ConstructorCallExpression call)` Emits a constructor call for an anonymous inner class (AIC).
    `` | `protected boolean` | `writeDirectMethodCall(MethodNode target, boolean implicitThis, Expression receiver, TupleExpression args)` Emits a direct (INVOKE*) bytecode call to `target` when static type information is available.
    `` | `public void` | `writeInvokeConstructor(ConstructorCallExpression call)` Generates bytecode for a constructor call expression, choosing the appropriate strategy (direct, AIC, or normal call-site).
    `` | `public void` | `writeInvokeMethod(MethodCallExpression call)` Generates bytecode for a standard (non-static, non-constructor) method call expression.
    `` | `public void` | `writeInvokeStaticMethod(StaticMethodCallExpression call)` Generates bytecode for a static method call expression.
    `` | `protected void` | `writeNormalConstructorCall(ConstructorCallExpression call)` Emits a normal (non-direct, non-AIC) constructor call via the call-site writer.
    `` | `public void` | `writeSpecialConstructorCall(ConstructorCallExpression call)` Generates bytecode for a `this()` or `super()` constructor call at the start of a constructor body.

  - ### Inherited Methods Summary

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

- - ### Field Detail

    - #### public static final MethodCaller castToVargsArray

      Method caller for casting an array of arguments to a varargs array.

    - #### protected final WriterController controller

      The controller coordinating all bytecode writers for the current class.

    - #### protected Expression currentCall

      The expression currently being compiled as a call, used for optimizations.

    - #### @Deprecated(since = "5.0.0")
      public static final MethodCaller invokeClosureMethod

      deprecated:
        Use direct closure invocation instead

    - #### public static final MethodCallerMultiAdapter invokeMethod

      Multi-adapter for generic `invokeMethod` call-site variants.

    - #### public static final MethodCallerMultiAdapter invokeMethodOnCurrent

      Multi-adapter for `invokeMethodOnCurrent` call-site variants.

    - #### public static final MethodCallerMultiAdapter invokeMethodOnSuper

      Multi-adapter for `invokeMethodOnSuper` call-site variants.

    - #### public static final MethodCallerMultiAdapter invokeStaticMethod

      Multi-adapter for `invokeStaticMethod` call-site variants.

  - ### Constructor Detail

    - #### public InvocationWriter(WriterController controller)

      Creates an invocation writer with the given controller.

      Parameters:
        `controller` - the writer controller

  - ### Method Detail

    - #### public void castNonPrimitiveToBool(ClassNode last)

      Unboxes a non-primitive value on the operand stack to a primitive `boolean`.

      Parameters:
        `last` - the type currently on top of the operand stack

    - #### public void castToNonPrimitiveIfNecessary(ClassNode sourceType, ClassNode targetType)

      Converts sourceType to a non-primitive by using Groovy casting. sourceType might be a primitive This might be done using SBA#castToType

    - #### public void coerce(ClassNode from, ClassNode target)

      Emits a Groovy `as` coercion from `from` to `target`.

      Parameters:
        `from` - the source type currently on the operand stack
        `target` - the target type to coerce to

    - #### protected void finnishConstructorCall(ConstructorNode cn, String ownerDescriptor, int argsToRemove)

      Emits the `INVOKESPECIAL` `<init>` instruction and updates the operand stack after a constructor call set up by prepareConstructorCall.

      Parameters:
        `cn` - the constructor node being invoked
        `ownerDescriptor` - the JVM internal name of the owning class
        `argsToRemove` - the number of argument entries to pop from the tracked stack

    - #### protected String getMethodName(Expression message)

      Extracts the constant method name string from a message expression. Returns `null` if the expression is not a constant string.

      Parameters:
        `message` - the method name expression
      Returns:
        the method name string, or `null` if not determinable

    - #### protected void loadArguments(List<Expression> arguments, Parameter[] parameters)

      Evaluates and loads each argument expression, handling varargs packing.

      Parameters:
        `arguments` - the argument expressions to evaluate
        `parameters` - the declared parameters of the target method

    - #### public static ArgumentListExpression makeArgumentList(Expression arguments)

      Converts an expression to an argument list.

      Returns:
        `arguments` if already an argument list or an argument list of the expression or expressions (in case of a tuple expression).
      Since:
        2.0.0

    - #### protected boolean makeCachedCall(Expression origin, ClassExpression sender, Expression receiver, Expression message, Expression arguments, MethodCallerMultiAdapter adapter, boolean safe, boolean spreadSafe, boolean implicitThis, boolean containsSpreadExpression)

      Attempts to emit a call-site-cached invocation (or invokedynamic). Returns `false` if the call cannot be cached, causing the caller to fall through to the uncached path.

      Parameters:
        `origin` - the original call expression
        `sender` - the class from which the call is dispatched
        `receiver` - the receiver expression
        `message` - the method name expression
        `arguments` - the arguments expression
        `adapter` - the method caller adapter
        `safe` - whether to use safe navigation
        `spreadSafe` - whether to use spread-safe navigation
        `implicitThis` - whether the receiver is implicit `this`
        `containsSpreadExpression` - whether any argument uses spread
      Returns:
        `true` if a cached call was emitted

    - #### public void makeCall(Expression origin, Expression receiver, Expression message, Expression arguments, MethodCallerMultiAdapter adapter, boolean safe, boolean spreadSafe, boolean implicitThis)

      Generates bytecode for a method call.

      Parameters:
        `origin` - the original expression
        `receiver` - the receiver expression
        `message` - the method name expression
        `arguments` - the arguments expression
        `adapter` - the method caller adapter
        `safe` - whether to use safe navigation
        `spreadSafe` - whether to use spread-safe navigation
        `implicitThis` - whether the receiver is implicit 'this'

    - #### protected void makeCall(Expression origin, ClassExpression sender, Expression receiver, Expression message, Expression arguments, MethodCallerMultiAdapter adapter, boolean safe, boolean spreadSafe, boolean implicitThis)

      Generates bytecode for a method invocation, choosing among direct call, call-site caching, and uncached (ScriptBytecodeAdapter) strategies.

      Parameters:
        `origin` - the original expression triggering this call
        `sender` - the class from which the call is dispatched
        `receiver` - the receiver expression
        `message` - the method name expression
        `arguments` - the arguments expression
        `adapter` - the multi-adapter selecting the correct runtime method
        `safe` - whether to use safe navigation (`?.`)
        `spreadSafe` - whether to use spread-safe navigation (`*?.`)
        `implicitThis` - whether the receiver is implicit `this`

    - #### protected boolean makeClassForNameCall(Expression origin, Expression receiver, Expression message, Expression arguments)

      if Class.forName(x) is recognized, make a direct method call

    - #### protected boolean makeDirectCall(Expression origin, Expression receiver, Expression message, Expression arguments, MethodCallerMultiAdapter adapter, boolean implicitThis, boolean containsSpreadExpression)

      Attempts to emit a direct (statically resolved) method call. Returns `false` if no direct call is possible, causing the caller to fall through to the cached or uncached path.

      Parameters:
        `origin` - the original call expression
        `receiver` - the receiver expression
        `message` - the method name expression
        `arguments` - the arguments expression
        `adapter` - the method caller adapter
        `implicitThis` - whether the receiver is implicit `this`
        `containsSpreadExpression` - whether any argument uses spread (`*`)
      Returns:
        `true` if the call was emitted directly

    - #### public final void makeSingleArgumentCall(Expression receiver, String message, Expression arguments)

      Delegates to makeSingleArgumentCall(Expression, String, Expression, boolean) with `safe = false`.

      Parameters:
        `receiver` - the receiver expression
        `message` - the method name
        `arguments` - the single argument expression

    - #### public void makeSingleArgumentCall(Expression receiver, String message, Expression arguments, boolean safe)

      Generates a single-argument method call via the call-site writer.

      Parameters:
        `receiver` - the receiver expression
        `message` - the method name
        `arguments` - the single argument expression
        `safe` - whether to use safe navigation (`?.`)

    - #### protected void makeUncachedCall(Expression origin, ClassExpression sender, Expression receiver, Expression message, Expression arguments, MethodCallerMultiAdapter adapter, boolean safe, boolean spreadSafe, boolean implicitThis, boolean containsSpreadExpression)

      Emits an uncached invocation via ScriptBytecodeAdapter. Used as the fallback when neither direct nor cached dispatch is applicable.

      Parameters:
        `origin` - the original call expression
        `sender` - the class from which the call is dispatched
        `receiver` - the receiver expression
        `message` - the method name expression
        `arguments` - the arguments expression
        `adapter` - the method caller adapter
        `safe` - whether to use safe navigation
        `spreadSafe` - whether to use spread-safe navigation
        `implicitThis` - whether the receiver is implicit `this`
        `containsSpreadExpression` - whether any argument uses spread

    - #### protected String prepareConstructorCall(ConstructorNode cn)

      Emits the `NEW` and `DUP` instructions for a constructor call and returns the internal class name of the type being constructed.

      Parameters:
        `cn` - the constructor node whose declaring class is being instantiated
      Returns:
        the JVM internal name of the class being constructed

    - #### protected boolean writeAICCall(ConstructorCallExpression call)

      Emits a constructor call for an anonymous inner class (AIC). Returns `false` if the call is not for an AIC.

      Parameters:
        `call` - the constructor call expression to compile
      Returns:
        `true` if an AIC call was emitted

    - #### protected boolean writeDirectMethodCall(MethodNode target, boolean implicitThis, Expression receiver, TupleExpression args)

      Emits a direct (INVOKE*) bytecode call to `target` when static type information is available. Returns `false` if a direct call cannot be made.

      Parameters:
        `target` - the resolved method node to call directly
        `implicitThis` - whether the receiver is implicit `this`
        `receiver` - the receiver expression (may be `null`)
        `args` - the argument tuple
      Returns:
        `true` if the call was emitted, `false` otherwise

    - #### public void writeInvokeConstructor(ConstructorCallExpression call)

      Generates bytecode for a constructor call expression, choosing the appropriate strategy (direct, AIC, or normal call-site).

      Parameters:
        `call` - the constructor call expression to compile

    - #### public void writeInvokeMethod(MethodCallExpression call)

      Generates bytecode for a standard (non-static, non-constructor) method call expression.

      Parameters:
        `call` - the method call expression to compile

    - #### public void writeInvokeStaticMethod(StaticMethodCallExpression call)

      Generates bytecode for a static method call expression.

      Parameters:
        `call` - the static method call expression to compile

    - #### protected void writeNormalConstructorCall(ConstructorCallExpression call)

      Emits a normal (non-direct, non-AIC) constructor call via the call-site writer.

      Parameters:
        `call` - the constructor call expression to compile

    - #### public void writeSpecialConstructorCall(ConstructorCallExpression call)

      Generates bytecode for a `this()` or `super()` constructor call at the start of a constructor body.

      Parameters:
        `call` - the constructor call expression representing `this()` or `super()`