Package org.codehaus.groovy.ast

# Class MethodInvocationTrap

java.lang.Object
org.codehaus.groovy.ast.CodeVisitorSupport
org.codehaus.groovy.ast.MethodInvocationTrap

All Implemented Interfaces:
  `GroovyCodeVisitor`

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
  Modifier and Type
  Field
  Description
  `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 Summary

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

- ## Method Summary

  Modifier and Type
  Method
  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.
  `void`
  `visitMethodCallExpression(MethodCallExpression call)`
  Visits a method call expression, checking if it is a target build invocation.

  ### Methods inherited from class org.codehaus.groovy.ast.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, visitMethodPointerExpression, visitMethodReferenceExpression, visitNotExpression, visitPostfixExpression, visitPrefixExpression, visitPropertyExpression, visitRangeExpression, visitReturnStatement, visitShortTernaryExpression, visitSpreadExpression, visitSpreadMapExpression, visitStaticMethodCallExpression, visitSwitch, visitSynchronizedStatement, visitTernaryExpression, visitThrowStatement, visitTryCatchFinally, visitTupleExpression, visitUnaryMinusExpression, visitUnaryPlusExpression, visitVariableExpression, visitWhileLoop`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface org.codehaus.groovy.ast.GroovyCodeVisitor

  `visit, visit, visitEmptyExpression, visitListOfExpressions`

- ## Field Details

  - ### source

    protected final ReaderSource source
    The source reader for extracting closure source code.

  - ### sourceUnit

    protected final SourceUnit sourceUnit
    The source unit for reporting errors and accessing compilation context.

- ## Constructor Details

  - ### MethodInvocationTrap

    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`.
    Parameters:
      `source` - the `ReaderSource` for extracting source code from closures, cannot be `null`
      `sourceUnit` - the `SourceUnit` for error reporting, cannot be `null`
    Throws:
      `IllegalArgumentException` - if either parameter is `null`

- ## Method Details

  - ### visitMethodCallExpression

    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.
    Specified by:
      `visitMethodCallExpression` in interface `GroovyCodeVisitor`
    Overrides:
      `visitMethodCallExpression` in class `CodeVisitorSupport`
    Parameters:
      `call` - the method call expression that may or may not be an AstBuilder 'from code' invocation

  - ### addError

    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

  - ### convertClosureToSource

    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

  - ### isBuildInvocation

    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

  - ### handleTargetMethodCallExpression

    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