Package: org.codehaus.groovy.transform.stc

## [Java] Class TypeCheckingExtension

- org.codehaus.groovy.transform.stc.TypeCheckingExtension

-     public class TypeCheckingExtension
      extends Object

  This interface defines a high-level API for handling type checking errors. As a dynamic language and a platform for developing DSLs, the Groovy language provides a lot of means to supply custom bindings or methods that are not possible to find at compile time. However, it is still possible to help the compiler, for example by telling it what is the type of an unresolved property. For basic DSL type checking, implementing those methods would help the type checker and make it silent where it normally throws errors.

  Since:
    2.1.0

- - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `protected StaticTypeCheckingVisitor` | `typeCheckingVisitor` | Visitor that owns this extension instance.

  - ### Constructor Summary

    Constructors
    Constructor and description
    `TypeCheckingExtension(StaticTypeCheckingVisitor typeCheckingVisitor)` Creates an extension bound to the supplied type-checking visitor.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public void` | `addStaticTypeError(String msg, ASTNode expr)` Adds a type checking error, which will be displayed to the user during compilation.
    `` | `public void` | `afterMethodCall(MethodCall call)` Allows the extension to perform additional tasks after the type checker actually visits a method call.
    `` | `public void` | `afterVisitClass(ClassNode node)` Allows the extension to perform additional tasks after the type checker actually visited a class node.
    `` | `public void` | `afterVisitMethod(MethodNode node)` Allows the extension to perform additional tasks after the type checker actually visited a method node.
    `` | `public boolean` | `beforeMethodCall(MethodCall call)` Allows the extension to perform additional tasks before the type checker actually visits a method call.
    `` | `public boolean` | `beforeVisitClass(ClassNode node)` Allows the extension to perform additional tasks before the type checker actually visits a class node.
    `` | `public boolean` | `beforeVisitMethod(MethodNode node)` Allows the extension to perform additional tasks before the type checker actually visits a method node.
    `` | `public ClassNode` | `buildListType(ClassNode componentType)` Builds a parametrized class node for List, to represent List<X>
    `` | `public ClassNode` | `buildMapType(ClassNode keyType, ClassNode valueType)` Builds a parametrized class node representing the Map<keyType,valueType> type.
    `` | `public ClassNode` | `classNodeFor(Class type)` Creates a ClassNode for the supplied runtime type.
    `` | `public ClassNode` | `classNodeFor(String type)` Creates a ClassNode for the supplied type name.
    `` | `public boolean` | `existsProperty(PropertyExpression pexp, boolean checkForReadOnly)` Checks whether the property exists for the supplied access mode.
    `` | `public boolean` | `existsProperty(PropertyExpression pexp, boolean checkForReadOnly, ClassCodeVisitorSupport visitor)` Checks whether the property exists and optionally visits the resolved member.
    `` | `public ClassNode` | `extractStaticReceiver(MethodCall call)` Given a method call, first checks that it's a static method call, and if it is, returns the class node for the receiver.
    `` | `public void` | `finish()` Subclasses should implement this method if they need to perform additional checks after the type checker has finished its work.
    `` | `public ClassNode[]` | `getArgumentTypes(ArgumentListExpression args)` Returns the inferred argument types for the supplied argument list.
    `` | `public Map<String, Object>` | `getOptions()` Returns the options passed to this extension via the parameterized extension syntax, e.g.
    `` | `public MethodNode` | `getTargetMethod(Expression expression)` Returns the direct target method selected for the expression, if any.
    `` | `public ClassNode` | `getType(ASTNode exp)` Returns the inferred type of an expression.
    `` | `public List<MethodNode>` | `handleAmbiguousMethods(List<MethodNode> nodes, Expression origin)` This method is called by the type checker before throwing an "ambiguous method" error, giving the chance to the extension to select the method properly.
    `` | `public boolean` | `handleIncompatibleAssignment(ClassNode lhsType, ClassNode rhsType, Expression assignmentExpression)` This method is called by the type checker when an assignment is not allowed by the type checker.
    `` | `public boolean` | `handleIncompatibleReturnType(ReturnStatement returnStatement, ClassNode inferredReturnType)` Allows the extension to catch incompatible return types.
    `` | `public List<MethodNode>` | `handleMissingMethod(ClassNode receiver, String name, ArgumentListExpression argumentList, ClassNode[] argumentTypes, MethodCall call)` This method is called by the type checker when a method call cannot be resolved.
    `` | `public boolean` | `handleUnresolvedAttribute(AttributeExpression aexp)` This method is called by the type checker when an attribute expression cannot be resolved (for example, when an attribute doesn't exist).
    `` | `public boolean` | `handleUnresolvedProperty(PropertyExpression pexp)` This method is called by the type checker when a property expression cannot be resolved (for example, when a property doesn't exist).
    `` | `public boolean` | `handleUnresolvedVariableExpression(VariableExpression vexp)` This method is called by the type checker when a variable expression cannot be resolved.
    `` | `public boolean` | `isStaticMethodCallOnClass(MethodCall call, ClassNode receiver)` Given a method call, checks if it's a static method call and if it is, tells if the receiver matches the one supplied as an argument.
    `` | `public ClassNode` | `lookupClassNodeFor(String type)` Lookup a ClassNode by its name from the source unit
    `` | `public void` | `onMethodSelection(Expression expression, MethodNode target)` Allows the extension to listen to method selection events.
    `` | `public ClassNode` | `parameterizedType(ClassNode baseType, ClassNode genericsTypeArguments)` Returns a parameterized view of the supplied base type.
    `` | `public void` | `setOptions(Map<String, Object> options)` Sets the options for this extension.
    `` | `public void` | `setup()` Subclasses should implement this method whenever they need to perform special checks before the type checker starts working.
    `` | `public void` | `storeType(Expression exp, ClassNode cn)` Stores an inferred type for an expression.

  - ### Inherited Methods Summary

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

- - ### Field Detail

    - #### protected final StaticTypeCheckingVisitor typeCheckingVisitor

      Visitor that owns this extension instance.

  - ### Constructor Detail

    - #### public TypeCheckingExtension(StaticTypeCheckingVisitor typeCheckingVisitor)

      Creates an extension bound to the supplied type-checking visitor.

  - ### Method Detail

    - #### public void addStaticTypeError(String msg, ASTNode expr)

      Adds a type checking error, which will be displayed to the user during compilation.

      Parameters:
        `msg` - the message for the error
        `expr` - the expression which is the root cause of the error

    - #### public void afterMethodCall(MethodCall call)

      Allows the extension to perform additional tasks after the type checker actually visits a method call. Compared to a custom visitor, this method ensures that the node being visited is a node which would have been visited by the type checker. This is in particular important for nodes which are marked with TypeCheckingMode.SKIP.

      Parameters:
        `call` - a method call, either a MethodCallExpression, StaticMethodCallExpression, or ConstructorCallExpression

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

      Allows the extension to perform additional tasks after the type checker actually visited a class node. Compared to a custom visitor, this method ensures that the node being visited is a node which would have been visited by the type checker. This is in particular important for nodes which are marked with TypeCheckingMode.SKIP.

      Parameters:
        `node` - a class node

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

      Allows the extension to perform additional tasks after the type checker actually visited a method node. Compared to a custom visitor, this method ensures that the node being visited is a node which would have been visited by the type checker. This is in particular important for nodes which are marked with TypeCheckingMode.SKIP.

      Parameters:
        `node` - a method node

    - #### public boolean beforeMethodCall(MethodCall call)

      Allows the extension to perform additional tasks before the type checker actually visits a method call. Compared to a custom visitor, this method ensures that the node being visited is a node which would have been visited by the type checker. This is in particular important for nodes which are marked with TypeCheckingMode.SKIP.

      Parameters:
        `call` - a method call, either a MethodCallExpression, StaticMethodCallExpression, or ConstructorCallExpression
      Returns:
        false if the type checker should visit the node, or true if this extension replaces what the type checker would do with the method call.

    - #### public boolean beforeVisitClass(ClassNode node)

      Allows the extension to perform additional tasks before the type checker actually visits a class node. Compared to a custom visitor, this method ensures that the node being visited is a node which would have been visited by the type checker. This is in particular important for nodes which are marked with TypeCheckingMode.SKIP.

      Parameters:
        `node` - a class node
      Returns:
        false if the type checker should visit the node, or true if this extension replaces what the type checker would do with the class.

    - #### public boolean beforeVisitMethod(MethodNode node)

      Allows the extension to perform additional tasks before the type checker actually visits a method node. Compared to a custom visitor, this method ensures that the node being visited is a node which would have been visited by the type checker. This is in particular important for nodes which are marked with TypeCheckingMode.SKIP.

      Parameters:
        `node` - a method node
      Returns:
        false if the type checker should visit the node, or true if this extension replaces what the type checker would do with the method.

    - #### public ClassNode buildListType(ClassNode componentType)

      Builds a parametrized class node for List, to represent List<X>

      Parameters:
        `componentType` - the classnode for the component type of the list
      Returns:
        a classnode representing List<componentType>
      Since:
        2.2.0

    - #### public ClassNode buildMapType(ClassNode keyType, ClassNode valueType)

      Builds a parametrized class node representing the Map<keyType,valueType> type.

      Parameters:
        `keyType` - the classnode type of the key
        `valueType` - the classnode type of the value
      Returns:
        a class node for Map<keyType,valueType>
      Since:
        2.2.0

    - #### public ClassNode classNodeFor(Class type)

      Creates a ClassNode for the supplied runtime type.

    - #### public ClassNode classNodeFor(String type)

      Creates a ClassNode for the supplied type name.

    - #### public boolean existsProperty(PropertyExpression pexp, boolean checkForReadOnly)

      Checks whether the property exists for the supplied access mode.

    - #### public boolean existsProperty(PropertyExpression pexp, boolean checkForReadOnly, ClassCodeVisitorSupport visitor)

      Checks whether the property exists and optionally visits the resolved member.

    - #### public ClassNode extractStaticReceiver(MethodCall call)

      Given a method call, first checks that it's a static method call, and if it is, returns the class node for the receiver. For example, with the following code: ``Person.findAll { ... }, it would return the class node for Person. If it's not a static method call, returns null.

      Parameters:
        `call` - a method call
      Returns:
        null if it's not a static method call, or the class node for the receiver instead.

    - #### public void finish()

      Subclasses should implement this method if they need to perform additional checks after the type checker has finished its work. This is particularly useful for situations where you need multiple passes. Some checks in that case may be deferred to the end, using this method.

    - #### public ClassNode[] getArgumentTypes(ArgumentListExpression args)

      Returns the inferred argument types for the supplied argument list.

    - #### public Map<String, Object> getOptions()

      Returns the options passed to this extension via the parameterized extension syntax, e.g. `@TypeChecked(extensions='my.Extension(key: value)')`.

      Returns:
        the options map, never null
      Since:
        6.0.0

    - #### public MethodNode getTargetMethod(Expression expression)

      Returns the direct target method selected for the expression, if any.

    - #### public ClassNode getType(ASTNode exp)

      Returns the inferred type of an expression. Delegates to the type checker implementation.

      Parameters:
        `exp` - the expression for which we want to find the inferred type
      Returns:
        the inferred type of the expression, as found by the type checker

    - #### public List<MethodNode> handleAmbiguousMethods(List<MethodNode> nodes, Expression origin)

      This method is called by the type checker before throwing an "ambiguous method" error, giving the chance to the extension to select the method properly. This means that when this method is called, the "nodes" parameter contains at least two methods. If the returned list still contains at least two methods, then the type checker will throw an ambiguous method call error. If the returned method contains 1 element, then the type checker will not throw any error. It is invalid to return an empty list.

      Parameters:
        `nodes` - the list of ambiguous methods
        `origin` - the expression which originated the method selection process
      Returns:
        a single element list of disambiguated selection, or more elements if still ambiguous. It is not allowed to return an empty list.

    - #### public boolean handleIncompatibleAssignment(ClassNode lhsType, ClassNode rhsType, Expression assignmentExpression)

      This method is called by the type checker when an assignment is not allowed by the type checker. Extensions may override this method to allow such assignments where the type checker normally disallows them.

      Parameters:
        `lhsType` - the type of the left hand side of the assignment, as found by the type checker
        `rhsType` - the type of the right hand side of the assignment, as found by the type checker
        `assignmentExpression` - the assignment expression which triggered this call
      Returns:
        `boolean` false if the extension does not handle this assignment, true otherwise

    - #### public boolean handleIncompatibleReturnType(ReturnStatement returnStatement, ClassNode inferredReturnType)

      Allows the extension to catch incompatible return types. This event is called whenever the type checker finds that an inferred return type is incompatible with the declared return type of a method.

      Parameters:
        `returnStatement` - the statement that triggered the error
        `inferredReturnType` - the inferred return type for this statement
      Returns:
        false if the extension doesn't handle the error, true otherwise

    - #### public List<MethodNode> handleMissingMethod(ClassNode receiver, String name, ArgumentListExpression argumentList, ClassNode[] argumentTypes, MethodCall call)

      This method is called by the type checker when a method call cannot be resolved. Extensions may override this method to handle missing methods and prevent the type checker from throwing an error.

      Parameters:
        `receiver` - the type of the receiver
        `name` - the name of the called method
        `argumentList` - the list of arguments of the call
        `argumentTypes` - the types of the arguments of the call
        `call` - the method call itself, if needed
      Returns:
        an empty list if the extension cannot resolve the method, or a list of potential methods if the extension finds candidates. This method must not return null.

    - #### public boolean handleUnresolvedAttribute(AttributeExpression aexp)

      This method is called by the type checker when an attribute expression cannot be resolved (for example, when an attribute doesn't exist). It gives the extension a chance to resolve it.

      Parameters:
        `aexp` - the unresolved attribute
      Returns:
        `boolean` false if this extension doesn't resolve the attribute, true if it resolves the attribute.

    - #### public boolean handleUnresolvedProperty(PropertyExpression pexp)

      This method is called by the type checker when a property expression cannot be resolved (for example, when a property doesn't exist). It gives the extension a chance to resolve it.

      Parameters:
        `pexp` - the unresolved property
      Returns:
        `boolean` false if this extension doesn't resolve the property, true if it resolves the property.

    - #### public boolean handleUnresolvedVariableExpression(VariableExpression vexp)

      This method is called by the type checker when a variable expression cannot be resolved. It gives the extension a chance to resolve it for the type checker.

      Parameters:
        `vexp` - the unresolved variable extension
      Returns:
        `boolean` false if the extension doesn't handle it, true if the extension handles this variable.

    - #### public boolean isStaticMethodCallOnClass(MethodCall call, ClassNode receiver)

      Given a method call, checks if it's a static method call and if it is, tells if the receiver matches the one supplied as an argument.

      Parameters:
        `call` - a method call
        `receiver` - a class node
      Returns:
        true if the method call is a static method call on the receiver

    - #### public ClassNode lookupClassNodeFor(String type)

      Lookup a ClassNode by its name from the source unit

      Parameters:
        `type` - the name of the class whose ClassNode we want to lookup
      Returns:
        a ClassNode representing the class

    - #### public void onMethodSelection(Expression expression, MethodNode target)

      Allows the extension to listen to method selection events. Given an expression, which may be a method call expression, a static method call expression, a pre/postfix expression, ..., if a corresponding method is found, this method is called.

      Parameters:
        `expression` - the expression for which a corresponding method has been found
        `target` - the method which has been chosen by the type checker

    - #### public ClassNode parameterizedType(ClassNode baseType, ClassNode genericsTypeArguments)

      Returns a parameterized view of the supplied base type.

    - #### public void setOptions(Map<String, Object> options)

      Sets the options for this extension. Called by the framework when loading a parameterized extension.

      Parameters:
        `options` - the options map
      Since:
        6.0.0

    - #### public void setup()

      Subclasses should implement this method whenever they need to perform special checks before the type checker starts working.

    - #### public void storeType(Expression exp, ClassNode cn)

      Stores an inferred type for an expression. Delegates to the type checker.

      Parameters:
        `exp` - the expression for which we want to store an inferred type
        `cn` - the type of the expression