Top Description Fields Constructors Methods
org.codehaus.groovy.transform.stc

public Class TypeCheckingExtension

extends Object
Class Inheritance
Known Direct Subclasses
org.codehaus.groovy.transform.stc.AbstractTypeCheckingExtension, org.codehaus.groovy.transform.stc.DefaultTypeCheckingExtension, org.codehaus.groovy.transform.stc.EnumTypeCheckingExtension
Imports
org.codehaus.groovy.GroovyBugError, org.codehaus.groovy.ast.ASTNode, .ClassCodeVisitorSupport, .ClassHelper, .ClassNode, .GenericsType, .MethodNode, org.codehaus.groovy.ast.expr.ArgumentListExpression, .AttributeExpression, .ClassExpression, .Expression, .MethodCall, .MethodCallExpression, .PropertyExpression, .StaticMethodCallExpression, .VariableExpression, org.codehaus.groovy.ast.stmt.ReturnStatement, java.util.Arrays, .Collections, .List

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

Modifier and TypeField and Description
protected final StaticTypeCheckingVisitor

Constructor Summary

AccessConstructor and Description
public

Method Summary

Modifier and TypeMethod and Description
public void
addStaticTypeError(final String
the message for the error
msg
,
final ASTNode
the expression which is the root cause of the error
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
a class node
node
)

Allows the extension to perform additional tasks after the type checker actually visited a class node.

public void
afterVisitMethod(MethodNode
a method node
node
)

Allows the extension to perform additional tasks after the type checker actually visited a method node.

public boolean

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.
beforeMethodCall
(MethodCall call)

Allows the extension to perform additional tasks before the type checker actually visits a method call.

public boolean

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.
beforeVisitClass
(ClassNode
a class node
node
)

Allows the extension to perform additional tasks before the type checker actually visits a class node.

public boolean

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.
beforeVisitMethod
(MethodNode
a method node
node
)

Allows the extension to perform additional tasks before the type checker actually visits a method node.

public ClassNode

Returns:

a classnode representing List<componentType>
buildListType
(ClassNode
the classnode for the component type of the list
componentType
)

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

public ClassNode

Returns:

a class node for Map<keyType,valueType>
buildMapType
(ClassNode
the classnode type of the key
keyType
,
ClassNode
the classnode type of the value
valueType
)

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

public ClassNode
public ClassNode
public boolean
existsProperty(final PropertyExpression pexp, final boolean checkForReadOnly)

public boolean
existsProperty(final PropertyExpression pexp, final boolean checkForReadOnly, final ClassCodeVisitorSupport visitor)

public ClassNode

Returns:

null if it's not a static method call, or the class node for the receiver instead.
extractStaticReceiver
(MethodCall
a method call
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[]
public MethodNode
getTargetMethod(final Expression expression)

public ClassNode

Returns:

the inferred type of the expression, as found by the type checker
getType
(final ASTNode
the expression for which we want to find the inferred type
exp
)

Returns the inferred type of an expression.

public List<MethodNode>

Returns:

a single element list of disambiguated selection, or more elements if still ambiguous. It is not allowed to return an empty list.
handleAmbiguousMethods
(final List<MethodNode>
the list of ambiguous methods
nodes
,
final Expression
the expression which originated the method selection process
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

Returns:

boolean false if the extension does not handle this assignment, true otherwise
handleIncompatibleAssignment
(final ClassNode
the type of the left hand side of the assignment, as found by the type checker
lhsType
,
final ClassNode
the type of the right hand side of the assignment, as found by the type checker
rhsType
,
final Expression
the assignment expression which triggered this call
assignmentExpression
)

This method is called by the type checker when an assignment is not allowed by the type checker.

public boolean

Returns:

false if the extension doesn't handle the error, true otherwise
handleIncompatibleReturnType
(ReturnStatement
the statement that triggered the error
returnStatement
,
ClassNode
the inferred return type for this statement
inferredReturnType
)

Allows the extension to catch incompatible return types.

public List<MethodNode>

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.
handleMissingMethod
(ClassNode
the type of the receiver
receiver
,
String
the name of the called method
name
,
ArgumentListExpression
the list of arguments of the call
argumentList
,
ClassNode[]
the types of the arguments of the call
argumentTypes
,
MethodCall
the method call itself, if needed
call
)

This method is called by the type checker when a method call cannot be resolved.

public boolean

Returns:

boolean false if this extension doesn't resolve the attribute, true if it resolves the attribute.
handleUnresolvedAttribute
(AttributeExpression
the unresolved attribute
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

Returns:

boolean false if this extension doesn't resolve the property, true if it resolves the property.
handleUnresolvedProperty
(PropertyExpression
the unresolved property
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

Returns:

boolean false if the extension doesn't handle it, true if the extension handles this variable.
handleUnresolvedVariableExpression
(VariableExpression
the unresolved variable extension
vexp
)

This method is called by the type checker when a variable expression cannot be resolved.

public boolean

Returns:

true if the method call is a static method call on the receiver
isStaticMethodCallOnClass
(MethodCall
a method call
call
,
ClassNode
a class node
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

Returns:

a ClassNode representing the class
lookupClassNodeFor
(String
the name of the class whose ClassNode we want to lookup
type
)

Lookup a ClassNode by its name from the source unit

public void
onMethodSelection(Expression
the expression for which a corresponding method has been found
expression
,
MethodNode
the method which has been chosen by the type checker
target
)

Allows the extension to listen to method selection events.

public ClassNode
parameterizedType(final ClassNode baseType, final ClassNode... genericsTypeArguments)

public void
setup()

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

public void
storeType(final Expression
the expression for which we want to store an inferred type
exp
,
final ClassNode
the type of the expression
cn
)

Stores an inferred type for an expression.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

typeCheckingVisitorback to summary
protected final StaticTypeCheckingVisitor typeCheckingVisitor

Constructor Detail

TypeCheckingExtensionback to summary
public TypeCheckingExtension(final StaticTypeCheckingVisitor typeCheckingVisitor)

Method Detail

addStaticTypeErrorback to summary
public void addStaticTypeError(final String msg, final ASTNode expr)

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

Parameters
msg:String

the message for the error

expr:ASTNode

the expression which is the root cause of the error

afterMethodCallback to summary
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 groovy.transform.TypeCheckingMode#SKIP.

Parameters
call:MethodCall

a method call, either a org.codehaus.groovy.ast.expr.MethodCallExpression, org.codehaus.groovy.ast.expr.StaticMethodCallExpression, or org.codehaus.groovy.ast.expr.ConstructorCallExpression

afterVisitClassback to summary
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 groovy.transform.TypeCheckingMode#SKIP.

Parameters
node:ClassNode

a class node

afterVisitMethodback to summary
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 groovy.transform.TypeCheckingMode#SKIP.

Parameters
node:MethodNode

a method node

beforeMethodCallback to summary
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 groovy.transform.TypeCheckingMode#SKIP.

Parameters
call:MethodCall

a method call, either a org.codehaus.groovy.ast.expr.MethodCallExpression, org.codehaus.groovy.ast.expr.StaticMethodCallExpression, or org.codehaus.groovy.ast.expr.ConstructorCallExpression

Returns:boolean

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.

beforeVisitClassback to summary
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 groovy.transform.TypeCheckingMode#SKIP.

Parameters
node:ClassNode

a class node

Returns:boolean

false if the type checker should visit the node, or true if this extension replaces what the type checker would do with the class.

beforeVisitMethodback to summary
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 groovy.transform.TypeCheckingMode#SKIP.

Parameters
node:MethodNode

a method node

Returns:boolean

false if the type checker should visit the node, or true if this extension replaces what the type checker would do with the method.

buildListTypeback to summary
public ClassNode buildListType(ClassNode componentType)

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

Parameters
componentType:ClassNode

the classnode for the component type of the list

Returns:ClassNode

a classnode representing List<componentType>

Since
2.2.0
buildMapTypeback to summary
public ClassNode buildMapType(ClassNode keyType, ClassNode valueType)

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

Parameters
keyType:ClassNode

the classnode type of the key

valueType:ClassNode

the classnode type of the value

Returns:ClassNode

a class node for Map<keyType,valueType>

Since
2.2.0
classNodeForback to summary
public ClassNode classNodeFor(Class<T> type)
classNodeForback to summary
public ClassNode classNodeFor(String type)
existsPropertyback to summary
public boolean existsProperty(final PropertyExpression pexp, final boolean checkForReadOnly)
existsPropertyback to summary
public boolean existsProperty(final PropertyExpression pexp, final boolean checkForReadOnly, final ClassCodeVisitorSupport visitor)
extractStaticReceiverback to summary
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:MethodCall

a method call

Returns:ClassNode

null if it's not a static method call, or the class node for the receiver instead.

finishback to summary
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.

getArgumentTypesback to summary
public ClassNode[] getArgumentTypes(final ArgumentListExpression args)
getTargetMethodback to summary
public MethodNode getTargetMethod(final Expression expression)
getTypeback to summary
public ClassNode getType(final ASTNode exp)

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

Parameters
exp:ASTNode

the expression for which we want to find the inferred type

Returns:ClassNode

the inferred type of the expression, as found by the type checker

handleAmbiguousMethodsback to summary
public List<MethodNode> handleAmbiguousMethods(final List<MethodNode> nodes, final 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:List<MethodNode>

the list of ambiguous methods

origin:Expression

the expression which originated the method selection process

Returns:List<MethodNode>

a single element list of disambiguated selection, or more elements if still ambiguous. It is not allowed to return an empty list.

handleIncompatibleAssignmentback to summary
public boolean handleIncompatibleAssignment(final ClassNode lhsType, final ClassNode rhsType, final 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:ClassNode

the type of the left hand side of the assignment, as found by the type checker

rhsType:ClassNode

the type of the right hand side of the assignment, as found by the type checker

assignmentExpression:Expression

the assignment expression which triggered this call

Returns:boolean

boolean false if the extension does not handle this assignment, true otherwise

handleIncompatibleReturnTypeback to summary
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:ReturnStatement

the statement that triggered the error

inferredReturnType:ClassNode

the inferred return type for this statement

Returns:boolean

false if the extension doesn't handle the error, true otherwise

handleMissingMethodback to summary
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:ClassNode

the type of the receiver

name:String

the name of the called method

argumentList:ArgumentListExpression

the list of arguments of the call

argumentTypes:ClassNode[]

the types of the arguments of the call

call:MethodCall

the method call itself, if needed

Returns:List<MethodNode>

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.

handleUnresolvedAttributeback to summary
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:AttributeExpression

the unresolved attribute

Returns:boolean

boolean false if this extension doesn't resolve the attribute, true if it resolves the attribute.

handleUnresolvedPropertyback to summary
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:PropertyExpression

the unresolved property

Returns:boolean

boolean false if this extension doesn't resolve the property, true if it resolves the property.

handleUnresolvedVariableExpressionback to summary
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:VariableExpression

the unresolved variable extension

Returns:boolean

boolean false if the extension doesn't handle it, true if the extension handles this variable.

isStaticMethodCallOnClassback to summary
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:MethodCall

a method call

receiver:ClassNode

a class node

Returns:boolean

true if the method call is a static method call on the receiver

lookupClassNodeForback to summary
public ClassNode lookupClassNodeFor(String type)

Lookup a ClassNode by its name from the source unit

Parameters
type:String

the name of the class whose ClassNode we want to lookup

Returns:ClassNode

a ClassNode representing the class

onMethodSelectionback to summary
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:Expression

the expression for which a corresponding method has been found

target:MethodNode

the method which has been chosen by the type checker

parameterizedTypeback to summary
public ClassNode parameterizedType(final ClassNode baseType, final ClassNode... genericsTypeArguments)
setupback to summary
public void setup()

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

storeTypeback to summary
public void storeType(final Expression exp, final ClassNode cn)

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

Parameters
exp:Expression

the expression for which we want to store an inferred type

cn:ClassNode

the type of the expression