checkers.types
Class AnnotatedTypeFactory

java.lang.Object
  checkers.types.AnnotatedTypeFactory

Direct Known Subclasses:

BasicAnnotatedTypeFactory, JavariAnnotatedTypeFactory, NullnessAnnotatedTypeFactory

public class AnnotatedTypeFactory
extends Object

The methods of this class take an element or AST node, and return the annotated type as an AnnotatedTypeMirror. The methods are:

• getAnnotatedType(ClassTree)
• getAnnotatedType(MethodTree)
• getAnnotatedType(Tree)
• getAnnotatedTypeFromTypeTree(Tree)
• getAnnotatedType(TypeElement)
• getAnnotatedType(ExecutableElement)
• getAnnotatedType(Element)

This implementation only adds qualifiers explicitly specified by the programmer. Type system checker writers may need to subclass this class, to add implicit and default qualifiers according to the type system semantics. Subclasses should especially override annotateImplicit(Element, AnnotatedTypeMirror) and annotateImplicit(Tree, AnnotatedTypeMirror).

checker.framework.manual

#writing-a-checker How to write a checker plug-in

Nested Class Summary

Modifier and Type	Class and Description
protected static class	AnnotatedTypeFactory.InheritedFromClassAnnotator A singleton utility class for pulling annotations down from a class type.

Field Summary

Modifier and Type	Field and Description
protected AnnotationUtils	annotations The factory to use for creating annotations.
protected AnnotatedTypes	atypes Utility class for manipulating annotated types.
protected Elements	elements Utility class for working with Elements.
protected ProcessingEnvironment	env The processing environment to use for accessing compiler internals.
protected QualifierHierarchy	qualHierarchy Represent the annotation relations
protected CompilationUnitTree	root optional! The AST of the source file being operated on
protected Trees	trees The Trees instance to use for tree node path finding.
protected Types	types Utility class for working with TypeMirrors.
protected VisitorState	visitorState the state of the visitor

Constructor and Description

AnnotatedTypeFactory(ProcessingEnvironment env, QualifierHierarchy qualHierarchy, CompilationUnitTree root)

AnnotatedTypeFactory(SourceChecker checker, CompilationUnitTree root)
Constructs a factory from the given ProcessingEnvironment instance and syntax tree root.

Method Summary

Modifier and Type	Method and Description
protected AnnotationMirror	aliasedAnnotation(AnnotationMirror a) Returns the canonical annotation for the passed annotation if it is an alias of a canonical one in the framework.
protected void	annotateImplicit(Element elt, AnnotatedTypeMirror type) Adds implicit annotations to a type obtained from a Element.
protected void	annotateImplicit(Tree tree, AnnotatedTypeMirror type) Adds implicit annotations to a type obtained from a Tree.
protected void	annotateInheritedFromClass(AnnotatedTypeMirror type) Adds annotations to the type based on the annotations from its class type if and only if no annotations are already present on the type.
AnnotatedTypeMirror.AnnotatedExecutableType	constructorFromUse(NewClassTree tree) Determines the AnnotatedTypeMirror.AnnotatedExecutableType of a constructor invocation.
protected static <K,V> Map<K,V>	createLRUCache(int size) A Utility method for creating LRU cache
protected Tree	declarationFromElement(Element elt) Gets the declaration tree for the element, if the source is available.
AnnotatedTypeMirror.AnnotatedDeclaredType	fromClass(ClassTree tree) Determines the annotated type of a class from its declaration.
AnnotatedTypeMirror	fromElement(Element elt) Determines the annotated type of an element.
AnnotatedTypeMirror.AnnotatedExecutableType	fromElement(ExecutableElement elt)
AnnotatedTypeMirror.AnnotatedDeclaredType	fromElement(TypeElement elt)
AnnotatedTypeMirror	fromExpression(ExpressionTree tree) Determines the annotated type of an expression.
AnnotatedTypeMirror	fromMember(Tree tree) Determines the annotated type of a variable or method declaration.
AnnotatedTypeMirror	fromTypeTree(Tree tree) Determines the annotated type from a type in tree form.
AnnotatedTypeMirror	fromTypeTree(Tree tree, checkers.types.ArrayConvention conv)
AnnotatedTypeMirror.AnnotatedDeclaredType	getAnnotatedType(ClassTree tree)
AnnotatedTypeMirror	getAnnotatedType(Element elt) Determines the annotated type of an element using fromElement(Element).
AnnotatedTypeMirror.AnnotatedExecutableType	getAnnotatedType(ExecutableElement elt)
AnnotatedTypeMirror	getAnnotatedType(ExpressionTree tree)
AnnotatedTypeMirror.AnnotatedExecutableType	getAnnotatedType(MethodTree tree)
AnnotatedTypeMirror.AnnotatedArrayType	getAnnotatedType(NewArrayTree tree)
AnnotatedTypeMirror.AnnotatedDeclaredType	getAnnotatedType(NewClassTree tree)
AnnotatedTypeMirror	getAnnotatedType(Tree tree) Determines the annotated type of an AST node.
AnnotatedTypeMirror.AnnotatedDeclaredType	getAnnotatedType(TypeElement elt)
AnnotatedTypeMirror	getAnnotatedType(VariableTree tree)
AnnotatedTypeMirror	getAnnotatedTypeFromTypeTree(Tree tree) Determines the annotated type from a type in tree form.
AnnotatedTypeMirror.AnnotatedDeclaredType	getBoxedType(AnnotatedTypeMirror.AnnotatedPrimitiveType type) returns the annotated boxed type of the given primitive type.
protected AnnotatedTypeMirror.AnnotatedDeclaredType	getCurrentClassType(Tree tree) Returns the current class type being visited by the visitor.
protected AnnotatedTypeMirror.AnnotatedDeclaredType	getCurrentMethodReceiver(Tree tree) Returns the receiver type of the current method being visited, and returns null if the visited tree is not within a method.
AnnotatedTypeMirror.AnnotatedDeclaredType	getEnclosingType(TypeElement element, Tree tree)
protected AnnotatedTypeMirror.AnnotatedDeclaredType	getImplicitReceiverType(Tree tree)
TreePath	getPath(Tree node) Gets the path for the given Tree under the current root by checking from the visitor's current path, and only using Trees.getPath(CompilationUnitTree, Tree) (which is much slower) only if node is not found on the current path.
QualifierHierarchy	getQualifierHierarchy()
AnnotatedTypeMirror	getReceiver(ExpressionTree expression) Returns the receiver type of the expression tree, or null if it does not exist.
AnnotatedTypeMirror.AnnotatedDeclaredType	getSelfType(Tree tree) Returns the type of this in the current location, which can be used if this has a special semantics (e.g.
AnnotatedTypeMirror.AnnotatedPrimitiveType	getUnboxedType(AnnotatedTypeMirror.AnnotatedDeclaredType type) returns the annotated primitive type of the given declared type if it is a boxed declared type.
VisitorState	getVisitorState() Returns the VisitorState instance used by the factory to infer types
protected boolean	isMostEnclosingThisDeref(Tree tree)
protected boolean	isWithinConstructor(Tree tree)
AnnotatedTypeMirror.AnnotatedExecutableType	methodFromUse(MethodInvocationTree tree) Determines the type of the invoked method based on the passed method invocation tree.
protected void	postAsMemberOf(AnnotatedTypeMirror type, AnnotatedTypeMirror owner, Element element) A callback method for the AnnotatedTypeFactory subtypes to customize AnnotatedTypes.asMemberOf().
protected void	postDirectSuperTypes(AnnotatedTypeMirror type, List<? extends AnnotatedTypeMirror> supertypes) A callback method for the AnnotatedTypeFactory subtypes to customize directSuperTypes().
protected Collection<AnnotationMirror>	unify(Collection<AnnotationMirror> c1, Collection<AnnotationMirror> c2) Returns the type qualifiers that are least upper bound for c1 and c2 qualifiers.

Methods inherited from class java.lang.Object

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

Field Detail

trees

protected final Trees trees

The Trees instance to use for tree node path finding.

root

@Nullable
protected final CompilationUnitTree root

optional! The AST of the source file being operated on

env

protected final ProcessingEnvironment env

The processing environment to use for accessing compiler internals.

annotations

protected final AnnotationUtils annotations

The factory to use for creating annotations.

elements

protected final Elements elements

Utility class for working with Elements.

types

protected final Types types

Utility class for working with TypeMirrors.

atypes

protected final AnnotatedTypes atypes

Utility class for manipulating annotated types.

visitorState

protected final VisitorState visitorState

the state of the visitor

qualHierarchy

@Nullable
protected final QualifierHierarchy qualHierarchy

Represent the annotation relations

Constructor Detail

AnnotatedTypeFactory

public AnnotatedTypeFactory(SourceChecker checker,
                            @Nullable
                            CompilationUnitTree root)

Constructs a factory from the given ProcessingEnvironment instance and syntax tree root. (These parameters are required so that the factory may conduct the appropriate annotation-gathering analyses on certain tree types.) Root can be null if the factory does not operate on trees.

Parameters:

checker - the SourceChecker to which this factory belongs

root - the root of the syntax tree that this factory produces annotated types for

Throws:

IllegalArgumentException - if either argument is null

AnnotatedTypeFactory

public AnnotatedTypeFactory(ProcessingEnvironment env,
                            @Nullable
                            QualifierHierarchy qualHierarchy,
                            @Nullable
                            CompilationUnitTree root)

Method Detail

getAnnotatedType

public AnnotatedTypeMirror getAnnotatedType(Element elt)

Determines the annotated type of an element using fromElement(Element).

Parameters:

elt - the element

Returns:

the annotated type of elt

Throws:

IllegalArgumentException - if elt is null

See Also:

fromElement(Element)

getAnnotatedType

public AnnotatedTypeMirror getAnnotatedType(Tree tree)

Determines the annotated type of an AST node.

The type is determined as follows:

• if tree is a class declaration, determine its type via fromClass(com.sun.source.tree.ClassTree)
• if tree is a method or variable declaration, determine its type via fromMember(Tree)
• if tree is an ExpressionTree, determine its type via fromExpression(ExpressionTree)
• otherwise, throw an UnsupportedOperationException

Parameters:

tree - the AST node

Returns:

the annotated type of tree

Throws:

UnsupportedOperationException - if an annotated type cannot be obtained from tree

IllegalArgumentException - if tree is null

See Also:

fromClass(ClassTree), fromMember(Tree), fromExpression(ExpressionTree)

getAnnotatedTypeFromTypeTree

public AnnotatedTypeMirror getAnnotatedTypeFromTypeTree(Tree tree)

Determines the annotated type from a type in tree form.

Parameters:

tree - the type tree

Returns:

the annotated type of the type in the AST

fromElement

public AnnotatedTypeMirror fromElement(Element elt)

Determines the annotated type of an element.

Parameters:

elt - the element

Returns:

the annotated type of the element

fromClass

public AnnotatedTypeMirror.AnnotatedDeclaredType fromClass(ClassTree tree)

Determines the annotated type of a class from its declaration.

Parameters:

tree - the class declaration

Returns:

the annotated type of the class being declared

fromMember

public AnnotatedTypeMirror fromMember(Tree tree)

Determines the annotated type of a variable or method declaration.

Parameters:

tree - the variable or method declaration

Returns:

the annotated type of the variable or method being declared

Throws:

IllegalArgumentException - if tree is not a method or variable declaration

fromExpression

public AnnotatedTypeMirror fromExpression(ExpressionTree tree)

Determines the annotated type of an expression.

Parameters:

tree - an expression

Returns:

the annotated type of the expression

fromTypeTree

public AnnotatedTypeMirror fromTypeTree(Tree tree)

Determines the annotated type from a type in tree form. This method does not add implicit annotations

Parameters:

tree - the type tree

Returns:

the annotated type of the type in the AST

fromTypeTree

public AnnotatedTypeMirror fromTypeTree(Tree tree,
                                        checkers.types.ArrayConvention conv)

annotateImplicit

protected void annotateImplicit(Tree tree,
                                @Mutable
                                AnnotatedTypeMirror type)

Adds implicit annotations to a type obtained from a Tree. By default, this method does nothing. Subclasses should use this method to implement implicit annotations specific to their type systems.

Parameters:

tree - an AST node

type - the type obtained from tree

annotateImplicit

protected void annotateImplicit(Element elt,
                                @Mutable
                                AnnotatedTypeMirror type)

Adds implicit annotations to a type obtained from a Element. By default, this method does nothing. Subclasses should use this method to implement implicit annotations specific to their type systems.

Parameters:

elt - an element

type - the type obtained from elt

postDirectSuperTypes

protected void postDirectSuperTypes(AnnotatedTypeMirror type,
                                    List<? extends AnnotatedTypeMirror> supertypes)

A callback method for the AnnotatedTypeFactory subtypes to customize directSuperTypes(). Overriding methods should merely change the annotations on the supertypes, without adding or removing new types The default provided implementation adds type annotations to supertypes. This allows the type and its supertypes to have the qualifiers, e.g. the supertypes of an Immutable type are also Immutable.

Parameters:

type - the type whose supertypes are desired

supertypes - the supertypes as specified by the base AnnotatedTypeFactory

postAsMemberOf

protected void postAsMemberOf(AnnotatedTypeMirror type,
                              AnnotatedTypeMirror owner,
                              Element element)

A callback method for the AnnotatedTypeFactory subtypes to customize AnnotatedTypes.asMemberOf(). Overriding methods should merely change the annotations on the subtypes, without changing the types.

Parameters:

type - the annotated type of the element

owner - the annotated type of the receiver of the accessing tree

element - the element of the field or method

annotateInheritedFromClass

protected void annotateInheritedFromClass(@Mutable
                                          AnnotatedTypeMirror type)

Adds annotations to the type based on the annotations from its class type if and only if no annotations are already present on the type.

Parameters:

type - the type for which class annotations will be inherited if there are no annotations already present

getImplicitReceiverType

protected AnnotatedTypeMirror.AnnotatedDeclaredType getImplicitReceiverType(Tree tree)

isMostEnclosingThisDeref

protected final boolean isMostEnclosingThisDeref(Tree tree)

getSelfType

public AnnotatedTypeMirror.AnnotatedDeclaredType getSelfType(Tree tree)

Returns the type of this in the current location, which can be used if this has a special semantics (e.g. this is non-null)

getEnclosingType

public AnnotatedTypeMirror.AnnotatedDeclaredType getEnclosingType(TypeElement element,
                                                                  Tree tree)

getReceiver

public final AnnotatedTypeMirror getReceiver(ExpressionTree expression)

Returns the receiver type of the expression tree, or null if it does not exist. The only trees that could potentially have a receiver are:

• Array Access
• Identifiers (whose receivers are usually self type)
• Method Invocation Trees
• Member Select Trees

Parameters:

expression -

Returns:

the type of the receiver of this expression

methodFromUse

public AnnotatedTypeMirror.AnnotatedExecutableType methodFromUse(MethodInvocationTree tree)

Determines the type of the invoked method based on the passed method invocation tree. The returned method type has all type variables resolved, whether based on receiver type, passed type parameters if any, and method invocation parameter. Subclasses may override this method to customize inference of types or qualifiers based on method invocation parameters. As an implementation detail, this method depends on AnnotatedTypes.asMemberOf(AnnotatedTypeMirror, Element), and customization based on receiver type should be in accordance to its specification.

Parameters:

tree - the method invocation tree

Returns:

the method type being invoked with tree

constructorFromUse

public AnnotatedTypeMirror.AnnotatedExecutableType constructorFromUse(NewClassTree tree)

Determines the AnnotatedTypeMirror.AnnotatedExecutableType of a constructor invocation. Note that this is different than calling getAnnotatedType(Tree) or fromExpression(ExpressionTree) on the constructor invocation; those determine the type of the result of invoking the constructor, which is probably an AnnotatedTypeMirror.AnnotatedDeclaredType.

Parameters:

tree - a constructor invocation

Returns:

the annotated type of the invoked constructor (as an executable type)

getBoxedType

public AnnotatedTypeMirror.AnnotatedDeclaredType getBoxedType(AnnotatedTypeMirror.AnnotatedPrimitiveType type)

returns the annotated boxed type of the given primitive type. The returned type would only have the annotations on the given type. Subclasses may override this method safely to override this behavour.

Parameters:

type - the primitivate type

Returns:

the boxed declared type of the passed primitive type

getUnboxedType

public AnnotatedTypeMirror.AnnotatedPrimitiveType getUnboxedType(AnnotatedTypeMirror.AnnotatedDeclaredType type)
                                                          throws IllegalArgumentException

returns the annotated primitive type of the given declared type if it is a boxed declared type. Otherwise, it throws IllegalArgumentException exception. The returned type would have the annotations on the given type and nothing else.

Parameters:

type - the declared type

Returns:

the unboxed primitive type

Throws:

IllegalArgmentExceptionif - the type given has no unbox conversion

IllegalArgumentException

getVisitorState

public VisitorState getVisitorState()

Returns the VisitorState instance used by the factory to infer types

getAnnotatedType

public final AnnotatedTypeMirror.AnnotatedDeclaredType getAnnotatedType(ClassTree tree)

See Also:

getAnnotatedType(Tree)

getAnnotatedType

public final AnnotatedTypeMirror.AnnotatedDeclaredType getAnnotatedType(NewClassTree tree)

See Also:

getAnnotatedType(Tree)

getAnnotatedType

public final AnnotatedTypeMirror.AnnotatedArrayType getAnnotatedType(NewArrayTree tree)

See Also:

getAnnotatedType(Tree)

getAnnotatedType

public final AnnotatedTypeMirror.AnnotatedExecutableType getAnnotatedType(MethodTree tree)

See Also:

getAnnotatedType(Tree)

getAnnotatedType

public final AnnotatedTypeMirror getAnnotatedType(VariableTree tree)

getAnnotatedType

public final AnnotatedTypeMirror getAnnotatedType(ExpressionTree tree)

getAnnotatedType

public final AnnotatedTypeMirror.AnnotatedDeclaredType getAnnotatedType(TypeElement elt)

See Also:

getAnnotatedType(Element)

getAnnotatedType

public final AnnotatedTypeMirror.AnnotatedExecutableType getAnnotatedType(ExecutableElement elt)

See Also:

getAnnotatedType(Element)

fromElement

public final AnnotatedTypeMirror.AnnotatedDeclaredType fromElement(TypeElement elt)

See Also:

getAnnotatedType(Element)

fromElement

public final AnnotatedTypeMirror.AnnotatedExecutableType fromElement(ExecutableElement elt)

See Also:

getAnnotatedType(Element)

aliasedAnnotation

protected AnnotationMirror aliasedAnnotation(AnnotationMirror a)

Returns the canonical annotation for the passed annotation if it is an alias of a canonical one in the framework. If it is not an alias, the method returns null. Returns an aliased type of the current one

unify

protected Collection<AnnotationMirror> unify(Collection<AnnotationMirror> c1,
                                             Collection<AnnotationMirror> c2)

Returns the type qualifiers that are least upper bound for c1 and c2 qualifiers. In most cases, this is simply the intersection of the collections. However, if a type system specifies more than one type qualifier, this needs to return the least restrictive type qualifiers. Examples: For NonNull, unify('Nullable', 'NonNull') ==> Nullable For IGJ, unify('Immutable', 'Mutable') ==> ReadOnly Delegates the call to QualifierHierarchy.leastUpperBound(Collection, Collection).

Parameters:

c1 - type qualifiers for the first type

c2 - tyep qualifiers for the second type

Returns:

the least restrictive qualifiers for both types

getQualifierHierarchy

public QualifierHierarchy getQualifierHierarchy()

declarationFromElement

protected final Tree declarationFromElement(Element elt)

Gets the declaration tree for the element, if the source is available.

Parameters:

elt - an element

Returns:

the tree declaration of the element if found

getCurrentClassType

protected final AnnotatedTypeMirror.AnnotatedDeclaredType getCurrentClassType(Tree tree)

Returns the current class type being visited by the visitor. The method uses the parameter only if the most enclosing class cannot be found directly.

Returns:

type of the most enclosing class being visited

getCurrentMethodReceiver

protected final AnnotatedTypeMirror.AnnotatedDeclaredType getCurrentMethodReceiver(Tree tree)

Returns the receiver type of the current method being visited, and returns null if the visited tree is not within a method. The method uses the parameter only if the most enclosing method cannot be found directly.

Returns:

receiver type of the most enclosing method being visited.

isWithinConstructor

protected final boolean isWithinConstructor(Tree tree)

getPath

public final TreePath getPath(Tree node)

Gets the path for the given Tree under the current root by checking from the visitor's current path, and only using Trees.getPath(CompilationUnitTree, Tree) (which is much slower) only if node is not found on the current path.

Parameters:

node - the Tree to get the path for

Returns:

the path for node under the current root

createLRUCache

protected static <K,V> Map<K,V> createLRUCache(int size)

A Utility method for creating LRU cache

Parameters:

size - size of the cache

Returns:

a new cache with the provided size