checkers.types
Class AnnotatedTypeFactory

java.lang.Object
  extended by 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:

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).

See the Checker Framework manual:
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  Map<Tree,AnnotatedTypeMirror> fromTreeCache
           
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 Summary
Constructor and Description
AnnotatedTypeFactory(ProcessingEnvironment env, QualifierHierarchy qualHierarchy, CompilationUnitTree root, Class<? extends SourceChecker> checkerClass)
           
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.
 boolean canHaveAnnotatedTypeParameters()
          For an annotated type parameter or wildcard (e.g.
 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.AnnotatedDeclaredType fromNewClass(NewClassTree tree)
           
 AnnotatedTypeMirror fromTypeTree(Tree tree)
          Determines the annotated type from a type in tree form.
 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


fromTreeCache

protected Map<Tree,AnnotatedTypeMirror> fromTreeCache
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,
                            Class<? extends SourceChecker> checkerClass)
Method Detail

canHaveAnnotatedTypeParameters

public boolean canHaveAnnotatedTypeParameters()
For an annotated type parameter or wildcard (e.g. <@Nullable T>, it returns true if the annotation should target the type parameter itself, otherwise the annotation should target the extends clause, i.e. the declaration should be treated as <T extends @Nullable Object>


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:

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

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:

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)

fromNewClass

public AnnotatedTypeMirror.AnnotatedDeclaredType fromNewClass(NewClassTree tree)

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