Package: org.codehaus.groovy.ast

## [Java] Class MethodInvocationTrap

- org.codehaus.groovy.ast.MethodInvocationTrap

-     public abstract class MethodInvocationTrap
      extends CodeVisitorSupport

  Abstract base class for AST visitors that trap and intercept specific method invocations. Primarily used to detect AstBuilder "from code" invocations and convert them to the equivalent "from string" approach during compilation.

  Subclasses implement `isBuildInvocation()` to identify target method calls and `handleTargetMethodCallExpression()` to transform them. The base class provides utility methods for error reporting and closure-to-source conversion.

  See Also:
    SourceUnit
    ReaderSource
    MethodCallExpression
    ClosureExpression

- - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `protected ReaderSource` | `source` | The source reader for extracting closure source code.
    `protected SourceUnit` | `sourceUnit` | The source unit for reporting errors and accessing compilation context.

  - ### Constructor Summary

    Constructors
    Constructor and description
    `MethodInvocationTrap(ReaderSource source, SourceUnit sourceUnit)` Creates a method invocation trap with the given source and source unit.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `protected void` | `addError(String msg, ASTNode expr)` Reports an error back to the source unit with line and column information.
    `` | `protected String` | `convertClosureToSource(ClosureExpression expression)` Converts a closure expression into its source code equivalent using the source reader.
    `` | `protected abstract boolean` | `handleTargetMethodCallExpression(MethodCallExpression call)` Handles a target method call expression by transforming or validating it.
    `` | `protected abstract boolean` | `isBuildInvocation(MethodCallExpression call)` Determines whether a method call expression is a target invocation for special handling.
    `` | `public void` | `visitMethodCallExpression(MethodCallExpression call)` Visits a method call expression, checking if it is a target build invocation.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class CodeVisitorSupport` | `afterSwitchCaseStatementsVisited, afterSwitchConditionExpressionVisited, visitArgumentlistExpression, visitArrayExpression, visitAssertStatement, visitAttributeExpression, visitBinaryExpression, visitBitwiseNegationExpression, visitBlockStatement, visitBooleanExpression, visitBreakStatement, visitBytecodeExpression, visitCaseStatement, visitCastExpression, visitCatchStatement, visitClassExpression, visitClosureExpression, visitClosureListExpression, visitConstantExpression, visitConstructorCallExpression, visitContinueStatement, visitDeclarationExpression, visitDoWhileLoop, visitEmptyStatement, visitExpressionStatement, visitFieldExpression, visitForLoop, visitGStringExpression, visitIfElse, visitLambdaExpression, visitListExpression, visitMapEntryExpression, visitMapExpression, visitMethodCallExpression, visitMethodPointerExpression, visitMethodReferenceExpression, visitNotExpression, visitPostfixExpression, visitPrefixExpression, visitPropertyExpression, visitRangeExpression, visitReturnStatement, visitShortTernaryExpression, visitSpreadExpression, visitSpreadMapExpression, visitStaticMethodCallExpression, visitSwitch, visitSynchronizedStatement, visitTernaryExpression, visitThrowStatement, visitTryCatchFinally, visitTupleExpression, visitUnaryMinusExpression, visitUnaryPlusExpression, visitVariableExpression, visitWhileLoop`

- - ### Field Detail

    - #### protected final ReaderSource source

      The source reader for extracting closure source code.

    - #### protected final SourceUnit sourceUnit

      The source unit for reporting errors and accessing compilation context.

  - ### Constructor Detail

    - #### public MethodInvocationTrap(ReaderSource source, SourceUnit sourceUnit)

      Creates a method invocation trap with the given source and source unit. Both arguments are required; `null` values will raise IllegalArgumentException.

      throws:
        IllegalArgumentException if either parameter is `null`
      Parameters:
        `source` - the ReaderSource for extracting source code from closures, cannot be `null`
        `sourceUnit` - the SourceUnit for error reporting, cannot be `null`

  - ### Method Detail

    - #### protected void addError(String msg, ASTNode expr)

      Reports an error back to the source unit with line and column information. The error is collected and processing continues.

      Parameters:
        `msg` - the error message
        `expr` - the expression that caused the error

    - #### protected String convertClosureToSource(ClosureExpression expression)

      Converts a closure expression into its source code equivalent using the source reader. If an error occurs during conversion, adds an error to the source unit and returns `null`.

      Parameters:
        `expression` - the closure expression to convert
      Returns:
        the source code string of the closure, or `null` if conversion fails

    - #### protected abstract boolean handleTargetMethodCallExpression(MethodCallExpression call)

      Handles a target method call expression by transforming or validating it. Subclasses override to implement the transformation logic.

      Parameters:
        `call` - the target method call expression
      Returns:
        `true` to continue tree walking, `false` to stop

    - #### protected abstract boolean isBuildInvocation(MethodCallExpression call)

      Determines whether a method call expression is a target invocation for special handling. Subclasses override to identify invocations matching their specific criteria.

      Parameters:
        `call` - the method call expression to check
      Returns:
        `true` if this call is a target invocation requiring special handling

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

      Visits a method call expression, checking if it is a target build invocation. If identified as a target invocation, calls `handleTargetMethodCallExpression()`. If that method returns `true`, resumes normal tree walking; otherwise stops. For non-target method calls, continues normal tree walking regardless.

      Parameters:
        `call` - the method call expression that may or may not be an AstBuilder 'from code' invocation