Package org.checkerframework.checker.modifiability

Class ModifiabilityBaseVisitor

java.lang.Object

com.sun.source.util.TreeScanner<Void,Void>

com.sun.source.util.TreePathScanner<Void,Void>

org.checkerframework.framework.source.SourceVisitor<Void,Void>

org.checkerframework.common.basetype.BaseTypeVisitor<ModifiabilityBaseAnnotatedTypeFactory>

org.checkerframework.checker.modifiability.ModifiabilityBaseVisitor

All Implemented Interfaces:

TreeVisitor<Void,Void>

Direct Known Subclasses:

IteratorVisitor

public class ModifiabilityBaseVisitor
extends BaseTypeVisitor<ModifiabilityBaseAnnotatedTypeFactory>

Base visitor for the modifiability sub-checkers (Grow, SeqGrow, Shrink, Replace, and Iterator).

This class contains logic shared across all the sub-checkers:

• Suppressing the "constructor result must be TOP" check, since collection constructors may legitimately produce @Modifiable.
• Suppressing the rule that relates a constructor's result to that of the this() or super() call within it, since a class may declare a different modifiability than its superclass does.
• Requiring all the constructors of a class to declare the same result qualifier, and requiring the body of each method that requires the capability -- either on its own receiver parameter or from a method that it overrides -- to agree with that qualifier about whether the method throws UnsupportedOperationException.
• Requiring a concrete class that claims the capability not to inherit, without overriding, a method whose implementation always throws UnsupportedOperationException.
• Requiring an override to preserve a positive receiver capability of the method it overrides.

Nested Class Summary

Nested classes/interfaces inherited from class org.checkerframework.common.basetype.BaseTypeVisitor

BaseTypeVisitor.FoundRequired, BaseTypeVisitor.OverrideChecker

Field Summary

Fields inherited from class org.checkerframework.common.basetype.BaseTypeVisitor

assumePureGetters, atypeFactory, checker, DETERMINISTIC, IMPURE, methodTree, positions, PURE, qualHierarchy, showchecks, SIDE_EFFECT_FREE, slowTypecheckingSeconds, slowTypecheckingTree, TARGET, targetValueElement, typeHierarchy, typeValidator, unusedWhenElement, warnRedundantAnnotations

Fields inherited from class org.checkerframework.framework.source.SourceVisitor

elements, root, trees, treesWithSuppressWarnings, types

Constructor Summary

Constructors

Constructor	Description
ModifiabilityBaseVisitor(BaseTypeChecker checker)	Create a ModifiabilityBaseVisitor.

Method Summary

Modifier and Type	Method	Description
protected void	checkConstructorResult(AnnotatedTypeMirror.AnnotatedExecutableType constructorType, ExecutableElement constructorElement)	Issue a warning if the result type of the constructor declaration is not top.
protected boolean	checkOverride(MethodTree overriderTree, AnnotatedTypeMirror.AnnotatedExecutableType overriderMethodType, AnnotatedTypeMirror.AnnotatedDeclaredType overriderType, AnnotatedTypeMirror.AnnotatedExecutableType overriddenMethodType, AnnotatedTypeMirror.AnnotatedDeclaredType overriddenType)	Checks the normal override rules, then requires overrides to preserve any positive modifiability receiver capability from the overridden method.
protected void	checkThisOrSuperConstructorCall(MethodInvocationTree call, @CompilerMessageKey String errorKey)	Suppresses the framework's rule that a constructor's result type must be a supertype of the result of the this() or super() call within it.
void	processClassTree(ClassTree tree)	Type-check classTree.
void	processMethodTree(String className, MethodTree tree)	Type-check methodTree.
protected boolean	shouldCheckReceiverOverrideCapabilityPreservation()	Returns true if overrides should preserve positive receiver capabilities from overridden methods.

Methods inherited from class org.checkerframework.common.basetype.BaseTypeVisitor

checkAccess, checkAccessAllowed, checkArguments, checkArrayInitialization, checkConditionalPostcondition, checkConstructorInvocation, checkContract, checkDefaultConstructor, checkExceptionParameter, checkExplicitAnnotationsOnIntersectionBounds, checkExtendsAndImplements, checkExtendsOrImplements, checkFieldInvariantDeclarations, checkLambdaPurity, checkLambdaSideEffectsOnly, checkMethodInvocability, checkMethodReferenceAsOverride, checkOverride, checkPostcondition, checkPreconditions, checkPurityAnnotations, checkQualifierParameter, checkSideEffectsOnlyAnnotation, checkSideEffectsOnlyExpressions, checkSuperConstructorCall, checkThisConstructorCall, checkThrownExpression, checkTypeArguments, checkTypecastRedundancy, checkTypecastSafety, checkVarargs, commonAssignmentCheck, commonAssignmentCheck, commonAssignmentCheck, commonAssignmentCheckEndDiagnostic, commonAssignmentCheckEndDiagnostic, commonAssignmentCheckStartDiagnostic, contractExpressionAndType, createOverrideChecker, createTypeFactory, createTypeFactoryPublic, createTypeValidator, enclosingMemberSelect, enclosingStatement, getExceptionParameterLowerBoundAnnotations, getThrowUpperBoundAnnotations, getTypeFactory, isTypeCastSafe, isValidUse, isValidUse, isValidUse, reportMethodInvocabilityError, reportPurityErrors, scan, setRoot, shouldPerformContractInference, shouldSkipUses, shouldWarnAboutIrrelevantJavaTypes, sideEffectsOnlyParseError, skipReceiverSubtypeCheck, testAnnotationInsertion, testJointJavacJavaParserVisitor, testTypevarContainment, typeCheckVectorCopyIntoArgument, validateType, validateTypeOf, visitAnnotatedType, visitAnnotatedType, visitAnnotation, visitAssignment, visitCatch, visitClass, visitCompilationUnit, visitCompoundAssignment, visitConditionalExpression, visitEnhancedForLoop, visitIdentifier, visitInstanceOf, visitLambdaExpression, visitMemberReference, visitMethod, visitMethodInvocation, visitNewArray, visitNewClass, visitReturn, visitSwitchExpression, visitThrow, visitTypeCast, visitTypeParameter, visitUnary, visitVariable, warnAboutIrrelevantJavaTypes, warnInvalidPolymorphicQualifier, warnInvalidPolymorphicQualifier, warnRedundantAnnotations

Methods inherited from class org.checkerframework.framework.source.SourceVisitor

storeSuppressWarningsAnno, visit

Methods inherited from class com.sun.source.util.TreePathScanner

getCurrentPath, scan

Methods inherited from class com.sun.source.util.TreeScanner

reduce, scan, visitAnyPattern, visitArrayAccess, visitArrayType, visitAssert, visitBinary, visitBindingPattern, visitBlock, visitBreak, visitCase, visitConstantCaseLabel, visitContinue, visitDeconstructionPattern, visitDefaultCaseLabel, visitDoWhileLoop, visitEmptyStatement, visitErroneous, visitExports, visitExpressionStatement, visitForLoop, visitIf, visitImport, visitIntersectionType, visitLabeledStatement, visitLiteral, visitMemberSelect, visitModifiers, visitModule, visitOpens, visitOther, visitPackage, visitParameterizedType, visitParenthesized, visitPatternCaseLabel, visitPrimitiveType, visitProvides, visitRequires, visitStringTemplate, visitSwitch, visitSynchronized, visitTry, visitUnionType, visitUses, visitWhileLoop, visitWildcard, visitYield

Methods inherited from class java.lang.Object

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

Constructor Details

ModifiabilityBaseVisitor

public ModifiabilityBaseVisitor(BaseTypeChecker checker)

Create a ModifiabilityBaseVisitor.

Parameters:

checker - the checker that uses this visitor

Method Details

checkThisOrSuperConstructorCall

protected void checkThisOrSuperConstructorCall(MethodInvocationTree call,
 @CompilerMessageKey String errorKey)

Suppresses the framework's rule that a constructor's result type must be a supertype of the result of the this() or super() call within it.

A collection class may legitimately declare a different modifiability than its superclass does; for example, a class whose constructors are @Ungrowable may extend AbstractList, whose constructor is @Growable, and override every grow method to throw UnsupportedOperationException. The framework's rule would reject every such class, including at the implicit super() call of a constructor that has no explicit one.

What makes the suppression less unsafe is that the declared modifiability of a class is checked against its method bodies; see processClassMembers(com.sun.source.tree.ClassTree). That check is not complete, so the suppression does permit some unsound code: it does nothing unless some constructor of the class declares a qualifier in this hierarchy.

Overrides:

checkThisOrSuperConstructorCall in class BaseTypeVisitor<ModifiabilityBaseAnnotatedTypeFactory>

Parameters:

call - the AST node for the constructor call

errorKey - the error message key to use if the check fails

processClassTree

public void processClassTree(ClassTree tree)

Description copied from class: BaseTypeVisitor

Type-check classTree. Subclasses should override this method instead of BaseTypeVisitor.visitClass(ClassTree, Void).

Overrides:

processClassTree in class BaseTypeVisitor<ModifiabilityBaseAnnotatedTypeFactory>

Parameters:

tree - class to check

processMethodTree

public void processMethodTree(String className,
 MethodTree tree)

Description copied from class: BaseTypeVisitor

Type-check methodTree. Subclasses should override this method instead of BaseTypeVisitor.visitMethod(MethodTree, Void).

Overrides:

processMethodTree in class BaseTypeVisitor<ModifiabilityBaseAnnotatedTypeFactory>

Parameters:

className - the class that contains the method, for diagnostics only

tree - the method to type-check

checkOverride

protected boolean checkOverride(MethodTree overriderTree,
 AnnotatedTypeMirror.AnnotatedExecutableType overriderMethodType,
 AnnotatedTypeMirror.AnnotatedDeclaredType overriderType,
 AnnotatedTypeMirror.AnnotatedExecutableType overriddenMethodType,
 AnnotatedTypeMirror.AnnotatedDeclaredType overriddenType)

Checks the normal override rules, then requires overrides to preserve any positive modifiability receiver capability from the overridden method.

For example, if the overridden method requires a @Growable receiver, then the overriding method must also require a @Growable receiver.

The framework's ordinary receiver override rule allows an overriding method to relax receiver preconditions. For modifiability operations, that would allow a subtype method to drop a required @Growable, @Shrinkable, or @Replaceable receiver capability.

For example:

 abstract class Super {
   abstract void add(@Growable Super this, String s);
 }

 class Sub extends Super {
   @Override
   void add(@MaybeGrowable Sub this, String s) {
     throw new UnsupportedOperationException();
   }
 }
 

Without requiring the override to preserve the @Growable receiver, Sub.add() would be permitted even though the body always throws UnsupportedOperationException.

Overrides:

checkOverride in class BaseTypeVisitor<ModifiabilityBaseAnnotatedTypeFactory>

Parameters:

overriderTree - declaration tree of overriding method

overriderMethodType - type of the overriding method

overriderType - type of overriding class

overriddenMethodType - type of overridden method

overriddenType - type of overridden class

Returns:

true if the override is allowed

See Also:

• BaseTypeVisitor.checkOverride(MethodTree, AnnotatedTypeMirror.AnnotatedDeclaredType, AnnotatedTypeMirror.AnnotatedExecutableType, AnnotatedTypeMirror.AnnotatedDeclaredType)

shouldCheckReceiverOverrideCapabilityPreservation

protected boolean shouldCheckReceiverOverrideCapabilityPreservation()

Returns true if overrides should preserve positive receiver capabilities from overridden methods.

Returns:

true if overrides should preserve positive receiver capabilities

checkConstructorResult

protected void checkConstructorResult(AnnotatedTypeMirror.AnnotatedExecutableType constructorType,
 ExecutableElement constructorElement)

Description copied from class: BaseTypeVisitor

Issue a warning if the result type of the constructor declaration is not top. If it is a supertype of the class, then a conflicting.annos error will also be issued by BaseTypeVisitor.isValidUse(AnnotatedTypeMirror.AnnotatedDeclaredType,AnnotatedTypeMirror.AnnotatedDeclaredType,Tree).

Overrides:

checkConstructorResult in class BaseTypeVisitor<ModifiabilityBaseAnnotatedTypeFactory>

Parameters:

constructorType - the AnnotatedExecutableType for the constructor

constructorElement - the element that declares the constructor