Class BaseTypeVisitor<Factory extends GenericAnnotatedTypeFactory<?,​?,​?,​?>>

    • Field Detail

      • atypeFactory

        protected final Factory extends GenericAnnotatedTypeFactory<?,​?,​?,​?> atypeFactory
        The factory to use for obtaining "parsed" version of annotations.
      • qualHierarchy

        protected final QualifierHierarchy qualHierarchy
        The qualifier hierarchy.
      • typeHierarchy

        protected final TypeHierarchy typeHierarchy
        The Annotated Type Hierarchy.
      • positions

        protected final com.sun.source.util.SourcePositions positions
        For obtaining line numbers in -Ashowchecks debugging output.
      • TARGET

        protected final javax.lang.model.element.AnnotationMirror TARGET
        The @java.lang.annotation.Target annotation.
      • DETERMINISTIC

        protected final javax.lang.model.element.AnnotationMirror DETERMINISTIC
        The @Deterministic annotation.
      • SIDE_EFFECT_FREE

        protected final javax.lang.model.element.AnnotationMirror SIDE_EFFECT_FREE
        The @SideEffectFree annotation.
      • PURE

        protected final javax.lang.model.element.AnnotationMirror PURE
        The @Pure annotation.
      • IMPURE

        protected final javax.lang.model.element.AnnotationMirror IMPURE
        The @Impure annotation.
      • targetValueElement

        protected final javax.lang.model.element.ExecutableElement targetValueElement
        The value element/field of the @java.lang.annotation.Target annotation.
      • unusedWhenElement

        protected final javax.lang.model.element.ExecutableElement unusedWhenElement
        The when element/field of the @Unused annotation.
      • showchecks

        protected final boolean showchecks
        True if "-Ashowchecks" was passed on the command line.
      • ignoreTargetLocations

        protected final boolean ignoreTargetLocations
        True if "-AignoreTargetLocations" was passed on the command line.
      • methodTree

        protected @Nullable com.sun.source.tree.MethodTree methodTree
        The tree of the enclosing method that is currently being visited.
      • qualAllowedLocations

        protected final java.util.Map<@CanonicalName java.lang.String,​java.util.List<TypeUseLocation>> qualAllowedLocations
        Map from String (canonical name of the qualifier) to its type-use locations declared in TargetLocations.
    • Method Detail

      • createTypeFactory

        protected Factory createTypeFactory()
        Constructs an instance of the appropriate type factory for the implemented type system.

        The default implementation uses the checker naming convention to create the appropriate type factory. If no factory is found, it returns BaseAnnotatedTypeFactory. It reflectively invokes the constructor that accepts this checker and compilation unit tree (in that order) as arguments.

        Subclasses have to override this method to create the appropriate visitor if they do not follow the checker naming convention.

        Returns:
        the appropriate type factory
      • getTypeFactory

        public final Factory getTypeFactory()
      • createTypeFactoryPublic

        public Factory createTypeFactoryPublic()
        A public variant of createTypeFactory(). Only use this if you know what you are doing.
        Returns:
        the appropriate type factory
      • setRoot

        public void setRoot​(com.sun.source.tree.CompilationUnitTree root)
        Description copied from class: SourceVisitor
        Set the CompilationUnitTree to be used during any visits. For any later calls of com.sun.source.util.TreePathScanner.scan(TreePath, P), the CompilationUnitTree of the TreePath has to be equal to root.
        Overrides:
        setRoot in class SourceVisitor<java.lang.Void,​java.lang.Void>
      • scan

        public java.lang.Void scan​(@Nullable com.sun.source.tree.Tree tree,
                                   java.lang.Void p)
        Overrides:
        scan in class SourceVisitor<java.lang.Void,​java.lang.Void>
      • testJointJavacJavaParserVisitor

        protected void testJointJavacJavaParserVisitor()
        Test JointJavacJavaParserVisitor if the checker has the "ajavaChecks" option.

        Parse the current source file with JavaParser and check that the AST can be matched with the Tree produced by javac. Crash if not.

        Subclasses may override this method to disable the test if even the option is provided.

      • testAnnotationInsertion

        protected void testAnnotationInsertion()
        Tests InsertAjavaAnnotations if the checker has the "ajavaChecks" option.
        1. Parses the current file with JavaParser.
        2. Removes all annotations.
        3. Reinserts the annotations.
        4. Throws an exception if the ASTs are not the same.

        Subclasses may override this method to disable the test even if the option is provided.

      • visitClass

        public final java.lang.Void visitClass​(com.sun.source.tree.ClassTree classTree,
                                               java.lang.Void p)
        Type-check classTree and skips classes specified by the skipDef option. Subclasses should override processClassTree(ClassTree) instead of this method.
        Specified by:
        visitClass in interface com.sun.source.tree.TreeVisitor<java.lang.Void,​java.lang.Void>
        Overrides:
        visitClass in class SourceVisitor<java.lang.Void,​java.lang.Void>
        Parameters:
        classTree - class to check
        p - null
        Returns:
        null
      • processClassTree

        public void processClassTree​(com.sun.source.tree.ClassTree classTree)
        Type-check classTree. Subclasses should override this method instead of visitClass(ClassTree, Void).
        Parameters:
        classTree - class to check
      • checkForPolymorphicQualifiers

        protected void checkForPolymorphicQualifiers​(com.sun.source.tree.ClassTree classTree)
        Issues an "invalid.polymorphic.qualifier" error for all polymorphic annotations written on the class declaration.
        Parameters:
        classTree - the class to check
      • checkForPolymorphicQualifiers

        protected void checkForPolymorphicQualifiers​(java.util.List<? extends com.sun.source.tree.TypeParameterTree> typeParameterTrees)
        Issues an "invalid.polymorphic.qualifier" error for all polymorphic annotations written on the type parameters declaration.
        Parameters:
        typeParameterTrees - the type parameters to check
      • checkQualifierParameter

        protected void checkQualifierParameter​(com.sun.source.tree.ClassTree classTree)
        Issues an error if classTree has polymorphic fields but is not annotated with @HasQualifierParameter. Always issue a warning if the type of a static field is annotated with a polymorphic qualifier.

        Issues an error if classTree extends or implements a class/interface that has a qualifier parameter, but this class does not.

        Parameters:
        classTree - the ClassTree to check for polymorphic fields
      • checkExtendsAndImplements

        protected void checkExtendsAndImplements​(com.sun.source.tree.ClassTree classTree)
        In @A class X extends @B Y implements @C Z {}, enforce that @A must be a subtype of @B and @C.

        Also validate the types of the extends and implements clauses.

        Parameters:
        classTree - class tree to check
      • checkExtendsOrImplements

        protected void checkExtendsOrImplements​(com.sun.source.tree.Tree boundClause,
                                                AnnotationMirrorSet classBounds,
                                                javax.lang.model.type.TypeMirror classType,
                                                boolean isExtends)
        Helper for checkExtendsAndImplements(com.sun.source.tree.ClassTree) that checks one extends or implements clause.
        Parameters:
        boundClause - an extends or implements clause
        classBounds - the type declarations bounds to check for consistency with boundClause
        classType - the type being declared
        isExtends - true for an extends clause, false for an implements clause
      • checkFieldInvariantDeclarations

        protected void checkFieldInvariantDeclarations​(com.sun.source.tree.ClassTree classTree)
        Check that the field invariant declaration annotations meet the following requirements:
        1. If the superclass of classTree has a field invariant, then the field invariant for classTree must include all the fields in the superclass invariant and those fields' annotations must be a subtype (or equal) to the annotations for those fields in the superclass.
        2. The fields in the invariant must be a.) final and b.) declared in a superclass of classTree.
        3. The qualifier for each field must be a subtype of the annotation on the declaration of that field.
        4. The field invariant has an equal number of fields and qualifiers, or it has one qualifier and at least one field.
        Parameters:
        classTree - class that might have a field invariant
        See the Checker Framework Manual:
        Field invariants
      • checkDefaultConstructor

        protected void checkDefaultConstructor​(com.sun.source.tree.ClassTree tree)
        Check the default constructor.
        Parameters:
        tree - a class declaration
      • visitMethod

        public java.lang.Void visitMethod​(com.sun.source.tree.MethodTree tree,
                                          java.lang.Void p)
        Checks that the method obeys override and subtype rules to all overridden methods. (Uses the pseudo-assignment logic to do so.)

        The override rule specifies that a method, m1, may override a method m2 only if:

        • m1 return type is a subtype of m2
        • m1 receiver type is a supertype of m2
        • m1 parameters are supertypes of corresponding m2 parameters
        Also, it issues a "missing.this" error for static method annotated receivers.
        Specified by:
        visitMethod in interface com.sun.source.tree.TreeVisitor<java.lang.Void,​java.lang.Void>
        Overrides:
        visitMethod in class SourceVisitor<java.lang.Void,​java.lang.Void>
      • reportPurityErrors

        protected void reportPurityErrors​(PurityChecker.PurityResult result,
                                          com.sun.source.tree.MethodTree tree,
                                          java.util.EnumSet<Pure.Kind> expectedKinds)
        Reports errors found during purity checking.
        Parameters:
        result - whether the method is deterministic and/or side-effect-free
        tree - the method
        expectedKinds - the expected purity for the method
      • checkPostcondition

        protected void checkPostcondition​(com.sun.source.tree.MethodTree methodTree,
                                          javax.lang.model.element.AnnotationMirror annotation,
                                          JavaExpression expression)
        Check that the expression's type is annotated with annotation at the regular exit store.
        Parameters:
        methodTree - declaration of the method
        annotation - expression's type must have this annotation
        expression - the expression that must have an annotation
      • checkConditionalPostcondition

        protected void checkConditionalPostcondition​(com.sun.source.tree.MethodTree methodTree,
                                                     javax.lang.model.element.AnnotationMirror annotation,
                                                     JavaExpression expression,
                                                     boolean result)
        Check that the expression's type is annotated with annotation at every regular exit that returns result.
        Parameters:
        methodTree - tree of method with the postcondition
        annotation - expression's type must have this annotation
        expression - the expression that the postcondition concerns
        result - result for which the postcondition is valid
      • visitTypeParameter

        public java.lang.Void visitTypeParameter​(com.sun.source.tree.TypeParameterTree tree,
                                                 java.lang.Void p)
        Specified by:
        visitTypeParameter in interface com.sun.source.tree.TreeVisitor<java.lang.Void,​java.lang.Void>
        Overrides:
        visitTypeParameter in class com.sun.source.util.TreeScanner<java.lang.Void,​java.lang.Void>
      • checkExplicitAnnotationsOnIntersectionBounds

        protected void checkExplicitAnnotationsOnIntersectionBounds​(AnnotatedTypeMirror.AnnotatedIntersectionType intersection,
                                                                    java.util.List<? extends com.sun.source.tree.Tree> boundTrees)
        Issues "explicit.annotation.ignored" warning if any explicit annotation on an intersection bound is not the same as the primary annotation of the given intersection type.
        Parameters:
        intersection - type to use
        boundTrees - trees of intersection bounds
      • visitVariable

        public java.lang.Void visitVariable​(com.sun.source.tree.VariableTree tree,
                                            java.lang.Void p)
        Specified by:
        visitVariable in interface com.sun.source.tree.TreeVisitor<java.lang.Void,​java.lang.Void>
        Overrides:
        visitVariable in class SourceVisitor<java.lang.Void,​java.lang.Void>
      • validateTargetLocation

        protected void validateTargetLocation​(com.sun.source.tree.Tree tree,
                                              AnnotatedTypeMirror type,
                                              TypeUseLocation required)
        Validate if the annotations on the tree are at the right locations, which are specified by the meta-annotation @TargetLocations.
        Parameters:
        tree - annotations on this VariableTree will be validated
        type - the type of the tree
        required - if all of the TypeUseLocations in required are not present in the specification of the annotation (@TargetLocations), issue an error.
      • createQualAllowedLocations

        protected java.util.Map<@CanonicalName java.lang.String,​java.util.List<TypeUseLocation>> createQualAllowedLocations()
        Create a new map, which is used for declared type-use locations lookup.
        Returns:
        a new mapping from strings of qualifier names to their declared type-use locations.
      • warnRedundantAnnotations

        protected void warnRedundantAnnotations​(com.sun.source.tree.Tree tree,
                                                AnnotatedTypeMirror type)
        Issues a "redundant.anno" warning if the annotation written on the type is the same as the default annotation for this type and location.
        Parameters:
        tree - an AST node
        type - get the explicit annotation on this type and compare it with the default one for this type and location.
      • visitAssignment

        public java.lang.Void visitAssignment​(com.sun.source.tree.AssignmentTree tree,
                                              java.lang.Void p)
        Performs two checks: subtyping and assignability checks, using commonAssignmentCheck(Tree, ExpressionTree, String, Object[]).

        If the subtype check fails, it issues an "assignment.type.incompatible" error.

        Specified by:
        visitAssignment in interface com.sun.source.tree.TreeVisitor<java.lang.Void,​java.lang.Void>
        Overrides:
        visitAssignment in class com.sun.source.util.TreeScanner<java.lang.Void,​java.lang.Void>
      • visitEnhancedForLoop

        public java.lang.Void visitEnhancedForLoop​(com.sun.source.tree.EnhancedForLoopTree tree,
                                                   java.lang.Void p)
        Performs a subtype check, to test whether the tree expression iterable type is a subtype of the variable type in the enhanced for loop.

        If the subtype check fails, it issues a "enhancedfor.type.incompatible" error.

        Specified by:
        visitEnhancedForLoop in interface com.sun.source.tree.TreeVisitor<java.lang.Void,​java.lang.Void>
        Overrides:
        visitEnhancedForLoop in class com.sun.source.util.TreeScanner<java.lang.Void,​java.lang.Void>
      • visitMethodInvocation

        public java.lang.Void visitMethodInvocation​(com.sun.source.tree.MethodInvocationTree tree,
                                                    java.lang.Void p)
        Performs a method invocation check.

        An invocation of a method, m, on the receiver, r is valid only if:

        • passed arguments are subtypes of corresponding m parameters
        • r is a subtype of m receiver type
        • if m is generic, passed type arguments are subtypes of m type variables
        Specified by:
        visitMethodInvocation in interface com.sun.source.tree.TreeVisitor<java.lang.Void,​java.lang.Void>
        Overrides:
        visitMethodInvocation in class com.sun.source.util.TreeScanner<java.lang.Void,​java.lang.Void>
      • checkThisConstructorCall

        protected void checkThisConstructorCall​(com.sun.source.tree.MethodInvocationTree thisCall)
        Checks that the following rule is satisfied: The type on a constructor declaration must be a supertype of the return type of "this()" invocation within that constructor.

        Subclasses can override this method to change the behavior for just "this" constructor class. Or override checkThisOrSuperConstructorCall(MethodInvocationTree, String) to change the behavior for "this" and "super" constructor calls.

        Parameters:
        thisCall - the AST node for the constructor call
      • checkSuperConstructorCall

        protected void checkSuperConstructorCall​(com.sun.source.tree.MethodInvocationTree superCall)
        Checks that the following rule is satisfied: The type on a constructor declaration must be a supertype of the return type of "super()" invocation within that constructor.

        Subclasses can override this method to change the behavior for just "super" constructor class. Or override checkThisOrSuperConstructorCall(MethodInvocationTree, String) to change the behavior for "this" and "super" constructor calls.

        Parameters:
        superCall - the AST node for the super constructor call
      • checkThisOrSuperConstructorCall

        protected void checkThisOrSuperConstructorCall​(com.sun.source.tree.MethodInvocationTree call,
                                                       @CompilerMessageKey java.lang.String errorKey)
        Checks that the following rule is satisfied: The type on a constructor declaration must be a supertype of the return type of "this()" or "super()" invocation within that constructor.
        Parameters:
        call - the AST node for the constructor call
        errorKey - the error message key to use if the check fails
      • checkPreconditions

        protected void checkPreconditions​(com.sun.source.tree.MethodInvocationTree tree,
                                          java.util.Set<Contract.Precondition> preconditions)
        Checks that all the given preconditions hold true immediately prior to the method invocation or variable access at tree.
        Parameters:
        tree - the method invocation; immediately prior to it, the preconditions must hold true
        preconditions - the preconditions to be checked
      • checkContract

        protected boolean checkContract​(JavaExpression expr,
                                        javax.lang.model.element.AnnotationMirror necessaryAnnotation,
                                        javax.lang.model.element.AnnotationMirror inferredAnnotation,
                                        CFAbstractStore<?,​?> store)
        Returns true if and only if inferredAnnotation is valid for a given expression to match the necessaryAnnotation.

        By default, inferredAnnotation must be a subtype of necessaryAnnotation, but subclasses might override this behavior.

      • typeCheckVectorCopyIntoArgument

        protected void typeCheckVectorCopyIntoArgument​(com.sun.source.tree.MethodInvocationTree tree,
                                                       java.util.List<? extends AnnotatedTypeMirror> params)
        Type checks the method arguments of Vector.copyInto().

        The Checker Framework special-cases the method invocation, as its type safety cannot be expressed by Java's type system.

        For a Vector v of type Vector<E>, the method invocation v.copyInto(arr) is type-safe iff arr is an array of type T[], where T is a subtype of E.

        In other words, this method checks that the type argument of the receiver method is a subtype of the component type of the passed array argument.

        Parameters:
        tree - a method invocation of Vector.copyInto()
        params - the types of the parameters of Vectory.copyInto()
      • visitNewClass

        public java.lang.Void visitNewClass​(com.sun.source.tree.NewClassTree tree,
                                            java.lang.Void p)
        Performs a new class invocation check.

        An invocation of a constructor, c, is valid only if:

        • passed arguments are subtypes of corresponding c parameters
        • if c is generic, passed type arguments are subtypes of c type variables
        Specified by:
        visitNewClass in interface com.sun.source.tree.TreeVisitor<java.lang.Void,​java.lang.Void>
        Overrides:
        visitNewClass in class com.sun.source.util.TreeScanner<java.lang.Void,​java.lang.Void>
      • visitLambdaExpression

        public java.lang.Void visitLambdaExpression​(com.sun.source.tree.LambdaExpressionTree tree,
                                                    java.lang.Void p)
        Specified by:
        visitLambdaExpression in interface com.sun.source.tree.TreeVisitor<java.lang.Void,​java.lang.Void>
        Overrides:
        visitLambdaExpression in class com.sun.source.util.TreeScanner<java.lang.Void,​java.lang.Void>
      • visitMemberReference

        public java.lang.Void visitMemberReference​(com.sun.source.tree.MemberReferenceTree tree,
                                                   java.lang.Void p)
        Specified by:
        visitMemberReference in interface com.sun.source.tree.TreeVisitor<java.lang.Void,​java.lang.Void>
        Overrides:
        visitMemberReference in class com.sun.source.util.TreeScanner<java.lang.Void,​java.lang.Void>
      • visitReturn

        public java.lang.Void visitReturn​(com.sun.source.tree.ReturnTree tree,
                                          java.lang.Void p)
        Checks that the type of the return expression is a subtype of the enclosing method required return type. If not, it issues a "return.type.incompatible" error.
        Specified by:
        visitReturn in interface com.sun.source.tree.TreeVisitor<java.lang.Void,​java.lang.Void>
        Overrides:
        visitReturn in class com.sun.source.util.TreeScanner<java.lang.Void,​java.lang.Void>
      • visitAnnotation

        public java.lang.Void visitAnnotation​(com.sun.source.tree.AnnotationTree tree,
                                              java.lang.Void p)
        Ensure that the annotation arguments comply to their declarations. This needs some special casing, as annotation arguments form special trees.
        Specified by:
        visitAnnotation in interface com.sun.source.tree.TreeVisitor<java.lang.Void,​java.lang.Void>
        Overrides:
        visitAnnotation in class com.sun.source.util.TreeScanner<java.lang.Void,​java.lang.Void>
      • visitConditionalExpression

        public java.lang.Void visitConditionalExpression​(com.sun.source.tree.ConditionalExpressionTree tree,
                                                         java.lang.Void p)
        If the computation of the type of the ConditionalExpressionTree in org.checkerframework.framework.type.TypeFromTree.TypeFromExpression.visitConditionalExpression(ConditionalExpressionTree, AnnotatedTypeFactory) is correct, the following checks are redundant. However, let's add another failsafe guard and do the checks.
        Specified by:
        visitConditionalExpression in interface com.sun.source.tree.TreeVisitor<java.lang.Void,​java.lang.Void>
        Overrides:
        visitConditionalExpression in class com.sun.source.util.TreeScanner<java.lang.Void,​java.lang.Void>
      • visitSwitchExpression17

        public void visitSwitchExpression17​(com.sun.source.tree.Tree switchExpressionTree)
        This method validates the type of the switch expression. It issues an error if the type of a value that the switch expression can result is not a subtype of the switch type.

        If a subclass overrides this method, it must call super.scan(switchExpressionTree, null) so that the blocks and statements in the cases are checked.

        Parameters:
        switchExpressionTree - a SwitchExpressionTree
      • visitUnary

        public java.lang.Void visitUnary​(com.sun.source.tree.UnaryTree tree,
                                         java.lang.Void p)
        Performs assignability check.
        Specified by:
        visitUnary in interface com.sun.source.tree.TreeVisitor<java.lang.Void,​java.lang.Void>
        Overrides:
        visitUnary in class com.sun.source.util.TreeScanner<java.lang.Void,​java.lang.Void>
      • visitCompoundAssignment

        public java.lang.Void visitCompoundAssignment​(com.sun.source.tree.CompoundAssignmentTree tree,
                                                      java.lang.Void p)
        Performs assignability check.
        Specified by:
        visitCompoundAssignment in interface com.sun.source.tree.TreeVisitor<java.lang.Void,​java.lang.Void>
        Overrides:
        visitCompoundAssignment in class com.sun.source.util.TreeScanner<java.lang.Void,​java.lang.Void>
      • visitNewArray

        public java.lang.Void visitNewArray​(com.sun.source.tree.NewArrayTree tree,
                                            java.lang.Void p)
        Specified by:
        visitNewArray in interface com.sun.source.tree.TreeVisitor<java.lang.Void,​java.lang.Void>
        Overrides:
        visitNewArray in class com.sun.source.util.TreeScanner<java.lang.Void,​java.lang.Void>
      • checkTypecastRedundancy

        protected void checkTypecastRedundancy​(com.sun.source.tree.TypeCastTree typeCastTree)
        If the lint option "cast:redundant" is set, this method issues a warning if the cast is redundant.
      • checkTypecastSafety

        protected void checkTypecastSafety​(com.sun.source.tree.TypeCastTree typeCastTree)
        Issues a warning if the given explicitly-written typecast is unsafe. Does nothing if the lint option "cast:unsafe" is not set. Only primary qualifiers are checked unless the command line option "checkCastElementType" is supplied.
        Parameters:
        typeCastTree - an explicitly-written typecast
      • isTypeCastSafe

        protected boolean isTypeCastSafe​(AnnotatedTypeMirror castType,
                                         AnnotatedTypeMirror exprType)
        Returns true if the cast is safe.

        Only primary qualifiers are checked unless the command line option "checkCastElementType" is supplied.

        Parameters:
        castType - annotated type of the cast
        exprType - annotated type of the casted expression
        Returns:
        true if the type cast is safe, false otherwise
      • visitTypeCast

        public java.lang.Void visitTypeCast​(com.sun.source.tree.TypeCastTree tree,
                                            java.lang.Void p)
        Specified by:
        visitTypeCast in interface com.sun.source.tree.TreeVisitor<java.lang.Void,​java.lang.Void>
        Overrides:
        visitTypeCast in class com.sun.source.util.TreeScanner<java.lang.Void,​java.lang.Void>
      • visitInstanceOf

        public java.lang.Void visitInstanceOf​(com.sun.source.tree.InstanceOfTree tree,
                                              java.lang.Void p)
        Specified by:
        visitInstanceOf in interface com.sun.source.tree.TreeVisitor<java.lang.Void,​java.lang.Void>
        Overrides:
        visitInstanceOf in class com.sun.source.util.TreeScanner<java.lang.Void,​java.lang.Void>
      • visitCatch

        public java.lang.Void visitCatch​(com.sun.source.tree.CatchTree tree,
                                         java.lang.Void p)
        Checks the type of the exception parameter. Subclasses should override checkExceptionParameter(com.sun.source.tree.CatchTree) rather than this method to change the behavior of this check.
        Specified by:
        visitCatch in interface com.sun.source.tree.TreeVisitor<java.lang.Void,​java.lang.Void>
        Overrides:
        visitCatch in class com.sun.source.util.TreeScanner<java.lang.Void,​java.lang.Void>
      • visitThrow

        public java.lang.Void visitThrow​(com.sun.source.tree.ThrowTree tree,
                                         java.lang.Void p)
        Checks the type of a thrown exception. Subclasses should override checkThrownExpression(ThrowTree tree) rather than this method to change the behavior of this check.
        Specified by:
        visitThrow in interface com.sun.source.tree.TreeVisitor<java.lang.Void,​java.lang.Void>
        Overrides:
        visitThrow in class com.sun.source.util.TreeScanner<java.lang.Void,​java.lang.Void>
      • visitAnnotatedType

        public java.lang.Void visitAnnotatedType​(com.sun.source.tree.AnnotatedTypeTree tree,
                                                 java.lang.Void p)
        Rather than overriding this method, clients should often override visitAnnotatedType(List,Tree). That method also handles the case of annotations at the beginning of a variable or method declaration. javac parses all those annotations as being on the variable or method declaration, even though the ones that are type annotations logically belong to the variable type or method return type.
        Specified by:
        visitAnnotatedType in interface com.sun.source.tree.TreeVisitor<java.lang.Void,​java.lang.Void>
        Overrides:
        visitAnnotatedType in class com.sun.source.util.TreeScanner<java.lang.Void,​java.lang.Void>
      • visitAnnotatedType

        public void visitAnnotatedType​(@Nullable java.util.List<? extends com.sun.source.tree.AnnotationTree> annoTrees,
                                       com.sun.source.tree.Tree typeTree)
        Checks an annotated type. Invoked by visitAnnotatedType(AnnotatedTypeTree, Void), visitVariable(com.sun.source.tree.VariableTree, java.lang.Void), and visitMethod(com.sun.source.tree.MethodTree, java.lang.Void). Exists to prevent code duplication among the three. Checking in visitVariable and visitMethod is needed because there isn't an AnnotatedTypeTree within a variable declaration or for a method return type -- all the annotations are attached to the VariableTree or MethodTree, respectively.
        Parameters:
        annoTrees - annotations written before a variable/method declaration, if this type is from one; null otherwise. This might contain type annotations that the Java parser attached to the declaration rather than to the type.
        typeTree - the type that any type annotations in annoTrees apply to
      • warnAboutIrrelevantJavaTypes

        public void warnAboutIrrelevantJavaTypes​(@Nullable java.util.List<? extends com.sun.source.tree.AnnotationTree> annoTrees,
                                                 com.sun.source.tree.Tree typeTree)
        Warns if a type annotation is written on a Java type that is not listed in the @RelevantJavaTypes annotation.
        Parameters:
        annoTrees - annotations written before a variable/method declaration, if this type is from one; null otherwise. This might contain type annotations that the Java parser attached to the declaration rather than to the type.
        typeTree - the type that any type annotations in annoTrees apply to
      • shouldWarnAboutIrrelevantJavaTypes

        protected boolean shouldWarnAboutIrrelevantJavaTypes()
        Returns true if the checker should issue warnings about irrelevant java types.
        Returns:
        true if the checker should issue warnings about irrelevant java types
      • checkExceptionParameter

        protected void checkExceptionParameter​(com.sun.source.tree.CatchTree tree)
        Issue error if the exception parameter is not a supertype of the annotation specified by getExceptionParameterLowerBoundAnnotations(), which is top by default.

        Subclasses may override this method to change the behavior of this check. Subclasses wishing to enforce that exception parameter be annotated with other annotations can just override getExceptionParameterLowerBoundAnnotations().

        Parameters:
        tree - a CatchTree to check
      • getExceptionParameterLowerBoundAnnotations

        protected AnnotationMirrorSet getExceptionParameterLowerBoundAnnotations()
        Returns a set of AnnotationMirrors that is a lower bound for exception parameters.

        This implementation returns top; subclasses can change this behavior.

        Note: by default this method is called by getThrowUpperBoundAnnotations(), so that this annotation is enforced.

        Returns:
        set of annotation mirrors, one per hierarchy, that form a lower bound of annotations that can be written on an exception parameter
      • getThrowUpperBoundAnnotations

        protected AnnotationMirrorSet getThrowUpperBoundAnnotations()
        Returns a set of AnnotationMirrors that is a upper bound for thrown exceptions.

        Note: by default this method is returns by getExceptionParameterLowerBoundAnnotations(), so that this annotation is enforced.

        (Default is top)

        Returns:
        set of annotation mirrors, one per hierarchy, that form an upper bound of thrown expressions
      • commonAssignmentCheck

        protected boolean commonAssignmentCheck​(com.sun.source.tree.Tree varTree,
                                                com.sun.source.tree.ExpressionTree valueExpTree,
                                                @CompilerMessageKey java.lang.String errorKey,
                                                java.lang.Object... extraArgs)
        Checks the validity of an assignment (or pseudo-assignment) from a value to a variable and emits an error message (through the compiler's messaging interface) if it is not valid.
        Parameters:
        varTree - the AST node for the lvalue (usually a variable)
        valueExpTree - the AST node for the rvalue (the new value)
        errorKey - the error message key to use if the check fails
        extraArgs - arguments to the error message key, before "found" and "expected" types
        Returns:
        true if the check succeeds, false if an error message was issued
      • commonAssignmentCheck

        protected boolean commonAssignmentCheck​(AnnotatedTypeMirror varType,
                                                com.sun.source.tree.ExpressionTree valueExpTree,
                                                @CompilerMessageKey java.lang.String errorKey,
                                                java.lang.Object... extraArgs)
        Checks the validity of an assignment (or pseudo-assignment) from a value to a variable and emits an error message (through the compiler's messaging interface) if it is not valid.
        Parameters:
        varType - the annotated type for the lvalue (usually a variable)
        valueExpTree - the AST node for the rvalue (the new value)
        errorKey - the error message key to use if the check fails
        extraArgs - arguments to the error message key, before "found" and "expected" types
        Returns:
        true if the check succeeds, false if an error message was issued
      • commonAssignmentCheck

        protected boolean commonAssignmentCheck​(AnnotatedTypeMirror varType,
                                                AnnotatedTypeMirror valueType,
                                                com.sun.source.tree.Tree valueExpTree,
                                                @CompilerMessageKey java.lang.String errorKey,
                                                java.lang.Object... extraArgs)
        Checks the validity of an assignment (or pseudo-assignment) from a value to a variable and emits an error message (through the compiler's messaging interface) if it is not valid.
        Parameters:
        varType - the annotated type of the variable
        valueType - the annotated type of the value
        valueExpTree - the location to use when reporting the error message
        errorKey - the error message key to use if the check fails
        extraArgs - arguments to the error message key, before "found" and "expected" types
        Returns:
        true if the check succeeds, false if an error message was issued
      • reportCommonAssignmentError

        protected void reportCommonAssignmentError​(AnnotatedTypeMirror varType,
                                                   AnnotatedTypeMirror valueType,
                                                   com.sun.source.tree.Tree valueTree,
                                                   @CompilerMessageKey java.lang.String errorKey,
                                                   java.lang.Object... extraArgs)
        Report a common assignment error. Allows checkers to change how the message is output.
        Parameters:
        varType - the annotated type of the variable
        valueType - the annotated type of the value
        valueTree - the location to use when reporting the error message
        errorKey - the error message key to use if the check fails
        extraArgs - arguments to the error message key, before "found" and "expected" types
      • commonAssignmentCheckStartDiagnostic

        protected final void commonAssignmentCheckStartDiagnostic​(AnnotatedTypeMirror varType,
                                                                  AnnotatedTypeMirror valueType,
                                                                  com.sun.source.tree.Tree valueExpTree)
        Prints a diagnostic about entering commonAssignmentCheck(), if the showchecks option was set.
        Parameters:
        varType - the annotated type of the variable
        valueType - the annotated type of the value
        valueExpTree - the location to use when reporting the error message
      • commonAssignmentCheckEndDiagnostic

        protected final void commonAssignmentCheckEndDiagnostic​(boolean success,
                                                                @Nullable java.lang.String extraMessage,
                                                                AnnotatedTypeMirror varType,
                                                                AnnotatedTypeMirror valueType,
                                                                com.sun.source.tree.Tree valueExpTree)
        Prints a diagnostic about exiting commonAssignmentCheck(), if the showchecks option was set.
        Parameters:
        success - whether the check succeeded or failed
        extraMessage - information about why the result is what it is; may be null
        varType - the annotated type of the variable
        valueType - the annotated type of the value
        valueExpTree - the location to use when reporting the error message
      • commonAssignmentCheckEndDiagnostic

        protected final void commonAssignmentCheckEndDiagnostic​(java.lang.String message,
                                                                AnnotatedTypeMirror varType,
                                                                AnnotatedTypeMirror valueType,
                                                                com.sun.source.tree.Tree valueExpTree)
        Helper method for printing a diagnostic about exiting commonAssignmentCheck(), if the showchecks option was set.

        Most clients should call commonAssignmentCheckEndDiagnostic(boolean, String, AnnotatedTypeMirror, AnnotatedTypeMirror, Tree). The purpose of this method is to permit customizing the message that is printed.

        Parameters:
        message - the result, plus information about why the result is what it is
        varType - the annotated type of the variable
        valueType - the annotated type of the value
        valueExpTree - the location to use when reporting the error message
      • checkArrayInitialization

        protected boolean checkArrayInitialization​(AnnotatedTypeMirror type,
                                                   java.util.List<? extends com.sun.source.tree.ExpressionTree> initializers)
        Checks that the array initializers are consistent with the array type.
        Parameters:
        type - the array elemen type
        initializers - the initializers
        Returns:
        true if the check succeeds, false if an error message was issued
      • checkTypeArguments

        protected void checkTypeArguments​(com.sun.source.tree.Tree toptree,
                                          java.util.List<? extends AnnotatedTypeParameterBounds> paramBounds,
                                          java.util.List<? extends AnnotatedTypeMirror> typeargs,
                                          java.util.List<? extends com.sun.source.tree.Tree> typeargTrees,
                                          java.lang.CharSequence typeOrMethodName,
                                          java.util.List<?> paramNames)
        Checks that the annotations on the type arguments supplied to a type or a method invocation are within the bounds of the type variables as declared, and issues the "type.argument.type.incompatible" error if they are not.
        Parameters:
        toptree - the tree for error reporting, only used for inferred type arguments
        paramBounds - the bounds of the type parameters from a class or method declaration
        typeargs - the type arguments from the type or method invocation
        typeargTrees - the type arguments as trees, used for error reporting
      • skipReceiverSubtypeCheck

        protected boolean skipReceiverSubtypeCheck​(com.sun.source.tree.MethodInvocationTree tree,
                                                   AnnotatedTypeMirror methodDefinitionReceiver,
                                                   AnnotatedTypeMirror methodCallReceiver)
        Indicates whether to skip subtype checks on the receiver when checking method invocability. A visitor may, for example, allow a method to be invoked even if the receivers are siblings in a hierarchy, provided that some other condition (implemented by the visitor) is satisfied.
        Parameters:
        tree - the method invocation tree
        methodDefinitionReceiver - the ATM of the receiver of the method definition
        methodCallReceiver - the ATM of the receiver of the method call
        Returns:
        whether to skip subtype checks on the receiver
      • checkMethodInvocability

        protected void checkMethodInvocability​(AnnotatedTypeMirror.AnnotatedExecutableType method,
                                               com.sun.source.tree.MethodInvocationTree tree)
        Tests whether the method can be invoked using the receiver of the 'tree' method invocation, and issues a "method.invocation.invalid" if the invocation is invalid.

        This implementation tests whether the receiver in the method invocation is a subtype of the method receiver type. This behavior can be specialized by overriding skipReceiverSubtypeCheck.

        Parameters:
        method - the type of the invoked method
        tree - the method invocation tree
      • reportMethodInvocabilityError

        protected void reportMethodInvocabilityError​(com.sun.source.tree.MethodInvocationTree tree,
                                                     AnnotatedTypeMirror found,
                                                     AnnotatedTypeMirror expected)
        Report a method invocability error. Allows checkers to change how the message is output.
        Parameters:
        tree - the AST node at which to report the error
        found - the actual type of the receiver
        expected - the expected type of the receiver
      • checkConstructorInvocation

        protected void checkConstructorInvocation​(AnnotatedTypeMirror.AnnotatedDeclaredType invocation,
                                                  AnnotatedTypeMirror.AnnotatedExecutableType constructor,
                                                  com.sun.source.tree.NewClassTree newClassTree)
        Check that the (explicit) annotations on a new class tree are comparable to the result type of the constructor. Issue an error if not.

        Issue a warning if the annotations on the constructor invocation is a subtype of the constructor result type. This is equivalent to down-casting.

        For type checking of the enclosing expression of inner type instantiations, see checkEnclosingExpr(NewClassTree, AnnotatedExecutableType)

        Parameters:
        invocation - the AnnotatedDeclaredType of the constructor invocation
        constructor - the AnnotatedExecutableType of the constructor declaration
        newClassTree - the NewClassTree
      • checkEnclosingExpr

        protected void checkEnclosingExpr​(com.sun.source.tree.NewClassTree node,
                                          AnnotatedTypeMirror.AnnotatedExecutableType constructorType)
        Helper method to type check the enclosing expression of an inner class instantiation.
        Parameters:
        node - the NewClassTree
        constructorType - the annotatedExecutableType of the constructor declaration
      • checkArguments

        protected void checkArguments​(java.util.List<? extends AnnotatedTypeMirror> requiredArgs,
                                      java.util.List<? extends com.sun.source.tree.ExpressionTree> passedArgs,
                                      java.lang.CharSequence executableName,
                                      java.util.List<?> paramNames)
        A helper method to check that each passed argument is a subtype of the corresponding required argument. Issues an "argument.invalid" error for each passed argument that not a subtype of the required one.

        Note this method requires the lists to have the same length, as it does not handle cases like var args.

        Parameters:
        requiredArgs - the required types. This may differ from the formal parameter types, because it replaces a varargs parameter by multiple parameters with the vararg's element type.
        passedArgs - the expressions passed to the corresponding types
        executableName - the name of the method or constructor being called
        paramNames - the names of the callee's formal parameters
        See Also:
        checkVarargs(AnnotatedTypeMirror.AnnotatedExecutableType, Tree)
      • testTypevarContainment

        protected boolean testTypevarContainment​(AnnotatedTypeMirror inner,
                                                 AnnotatedTypeMirror outer)
        Returns true if both types are type variables and outer contains inner. Outer contains inner implies: inner.upperBound <: outer.upperBound outer.lowerBound <: inner.lowerBound.
        Returns:
        true if both types are type variables and outer contains inner
      • createOverrideChecker

        protected BaseTypeVisitor.OverrideChecker createOverrideChecker​(com.sun.source.tree.Tree overriderTree,
                                                                        AnnotatedTypeMirror.AnnotatedExecutableType overriderMethodType,
                                                                        AnnotatedTypeMirror overriderType,
                                                                        AnnotatedTypeMirror overriderReturnType,
                                                                        AnnotatedTypeMirror.AnnotatedExecutableType overriddenMethodType,
                                                                        AnnotatedTypeMirror.AnnotatedDeclaredType overriddenType,
                                                                        AnnotatedTypeMirror overriddenReturnType)
        Create an OverrideChecker.

        This exists so that subclasses can subclass OverrideChecker and use their subclass instead of using OverrideChecker itself.

        Parameters:
        overriderTree - the AST node of the overriding method or method reference
        overriderMethodType - the type of the overriding method
        overriderType - the type enclosing the overrider method, usually an AnnotatedDeclaredType; for Method References may be something else
        overriderReturnType - the return type of the overriding method
        overriddenMethodType - the type of the overridden method
        overriddenType - the declared type enclosing the overridden method
        overriddenReturnType - the return type of the overridden method
        Returns:
        an OverrideChecker
      • checkMethodReferenceAsOverride

        protected boolean checkMethodReferenceAsOverride​(com.sun.source.tree.MemberReferenceTree memberReferenceTree,
                                                         java.lang.Void p)
        Check that a method reference is allowed. Using the OverrideChecker class.
        Parameters:
        memberReferenceTree - the tree for the method reference
        Returns:
        true if the method reference is allowed
      • enclosingMemberSelect

        protected @Nullable com.sun.source.tree.MemberSelectTree enclosingMemberSelect()
        Call this only when the current path is an identifier.
        Returns:
        the enclosing member select, or null if the identifier is not the field in a member selection
      • enclosingStatement

        protected @Nullable com.sun.source.tree.Tree enclosingStatement​(@FindDistinct
                                                                        com.sun.source.tree.Tree tree)
        Returns the statement that encloses the given one.
        Parameters:
        tree - an AST node that is on the current path
        Returns:
        the statement that encloses the given one
      • visitIdentifier

        public java.lang.Void visitIdentifier​(com.sun.source.tree.IdentifierTree tree,
                                              java.lang.Void p)
        Specified by:
        visitIdentifier in interface com.sun.source.tree.TreeVisitor<java.lang.Void,​java.lang.Void>
        Overrides:
        visitIdentifier in class com.sun.source.util.TreeScanner<java.lang.Void,​java.lang.Void>
      • checkAccess

        protected void checkAccess​(com.sun.source.tree.IdentifierTree identifierTree,
                                   java.lang.Void p)
        Issues an error if access is not allowed, based on an @Unused annotation.
        Parameters:
        identifierTree - the identifier being accessed; the method does nothing if it is not a field
        p - ignored
      • checkAccessAllowed

        protected void checkAccessAllowed​(javax.lang.model.element.Element field,
                                          @Nullable AnnotatedTypeMirror receiverType,
                                          @FindDistinct
                                          com.sun.source.tree.ExpressionTree accessTree)
        Issues an error if access not allowed, based on an @Unused annotation.
        Parameters:
        field - the field to be accessed, whose declaration might be annotated by @Unused. It can also be (for example) this, in which case receiverType is null.
        receiverType - the type of the expression whose field is accessed; null if the field is static
        accessTree - the access expression
      • isValidUse

        public boolean isValidUse​(AnnotatedTypeMirror.AnnotatedPrimitiveType type,
                                  com.sun.source.tree.Tree tree)
        Tests that the qualifiers present on the primitive type are valid.
        Parameters:
        type - the use of the primitive type
        tree - the tree where the type is used
        Returns:
        true if the type is a valid use of the primitive type
      • isValidUse

        public boolean isValidUse​(AnnotatedTypeMirror.AnnotatedArrayType type,
                                  com.sun.source.tree.Tree tree)
        Tests that the qualifiers present on the array type are valid. This method will be invoked for each array level independently, i.e. this method only needs to check the top-level qualifiers of an array.
        Parameters:
        type - the array type use
        tree - the tree where the type is used
        Returns:
        true if the type is a valid array type
      • validateTypeOf

        public boolean validateTypeOf​(com.sun.source.tree.Tree tree)
        Tests whether the tree expressed by the passed type tree is a valid type, and emits an error if that is not the case (e.g. '@Mutable String'). If the tree is a method or constructor, check the return type.
        Parameters:
        tree - the AST type supplied by the user
        Returns:
        true if the tree is a valid type
      • validateType

        protected boolean validateType​(com.sun.source.tree.Tree tree,
                                       AnnotatedTypeMirror type)
        Tests whether the type and corresponding type tree is a valid type, and emits an error if that is not the case (e.g. '@Mutable String'). If the tree is a method or constructor, tests the return type.
        Parameters:
        tree - the type tree supplied by the user
        type - the type corresponding to tree
        Returns:
        true if the type is valid
      • createTypeValidator

        protected TypeValidator createTypeValidator()
      • shouldSkipUses

        protected final boolean shouldSkipUses​(com.sun.source.tree.ExpressionTree exprTree)
        Tests whether the expression should not be checked because of the tree referring to unannotated classes, as specified in the checker.skipUses property.

        It returns true if exprTree is a method invocation or a field access to a class whose qualified name matches the checker.skipUses property.

        Parameters:
        exprTree - any expression tree
        Returns:
        true if checker should not test exprTree
      • visitCompilationUnit

        public java.lang.Void visitCompilationUnit​(com.sun.source.tree.CompilationUnitTree identifierTree,
                                                   java.lang.Void p)
        Override Compilation Unit so we won't visit package names or imports.
        Specified by:
        visitCompilationUnit in interface com.sun.source.tree.TreeVisitor<java.lang.Void,​java.lang.Void>
        Overrides:
        visitCompilationUnit in class com.sun.source.util.TreeScanner<java.lang.Void,​java.lang.Void>