Package org.checkerframework.checker.mustcall

Class MustCallAnnotatedTypeFactory

java.lang.Object

org.checkerframework.framework.type.AnnotatedTypeFactory

org.checkerframework.framework.type.GenericAnnotatedTypeFactory<CFValue,CFStore,CFTransfer,CFAnalysis>

org.checkerframework.common.basetype.BaseAnnotatedTypeFactory

org.checkerframework.checker.mustcall.MustCallAnnotatedTypeFactory

All Implemented Interfaces:

CreatesMustCallForElementSupplier, AnnotationProvider

public class MustCallAnnotatedTypeFactory
extends BaseAnnotatedTypeFactory
implements CreatesMustCallForElementSupplier

The annotated type factory for the Must Call Checker. Primarily responsible for the subtyping rules between @MustCall annotations.

Nested Class Summary

Nested classes/interfaces inherited from class org.checkerframework.framework.type.GenericAnnotatedTypeFactory

GenericAnnotatedTypeFactory.ScanState

Nested classes/interfaces inherited from class org.checkerframework.framework.type.AnnotatedTypeFactory

AnnotatedTypeFactory.CapturedTypeVarSubstitutor, AnnotatedTypeFactory.ParameterizedExecutableType

Field Summary

Fields

Modifier and Type	Field	Description
final AnnotationMirror	BOTTOM	The @MustCall() annotation.
final AnnotationMirror	POLY	The @PolyMustCall annotation.
final AnnotationMirror	TOP	The @MustCallUnknown annotation.

Fields inherited from class org.checkerframework.framework.type.GenericAnnotatedTypeFactory

analysis, arraysAreRelevant, cfgVisualizer, contractsUtils, defaults, dependentTypesHelper, emptyStore, exceptionalExitStores, flowByDefault, flowResult, flowResultAnalysisCaches, formalParameterPattern, hasOrIsSubchecker, initializationStaticStore, initializationStore, methodInvocationStores, poly, regularExitStores, relevantJavaTypes, returnStatementStores, scannedClasses, shouldClearSubcheckerSharedCFGs, sideEffectsUnrefineAliases, subcheckerSharedCFG, transfer, treeAnnotator, typeAnnotator

Fields inherited from class org.checkerframework.framework.type.AnnotatedTypeFactory

ajavaTypes, annotatedForValueElement, artificialTreeToEnclosingElementMap, capturedTypeVarSubstitutor, checker, currentFileAjavaTypes, elements, ensuresQualifierExpressionElement, ensuresQualifierIfExpressionElement, ensuresQualifierIfListTM, ensuresQualifierIfListValueElement, ensuresQualifierIfResultElement, ensuresQualifierIfTM, ensuresQualifierListTM, ensuresQualifierListValueElement, ensuresQualifierTM, fieldInvariantFieldElement, fieldInvariantQualifierElement, fromExpressionTreeCache, fromMemberTreeCache, fromTypeTreeCache, hasQualifierParameterValueElement, ignoreRawTypeArguments, loader, methodValClassNameElement, methodValMethodNameElement, methodValParamsElement, noQualifierParameterValueElement, objectGetClass, processingEnv, qualHierarchy, qualifierUpperBounds, reflectionResolver, requiresQualifierExpressionElement, requiresQualifierListTM, requiresQualifierListValueElement, requiresQualifierTM, root, shouldCache, stubTypes, trees, typeArgumentInference, typeFormatter, typeHierarchy, types, typeVarSubstitutor, uid, wpiOutputFormat

Constructor Summary

Constructors

Constructor	Description
MustCallAnnotatedTypeFactory(BaseTypeChecker checker)	Creates a MustCallAnnotatedTypeFactory.

Method Summary

Modifier and Type	Method	Description
protected void	constructorFromUsePreSubstitution(NewClassTree tree, AnnotatedTypeMirror.AnnotatedExecutableType type, boolean resolvePolyQuals)	A callback method for the AnnotatedTypeFactory subtypes to customize the handling of the declared constructor type before type variable substitution.
protected DefaultQualifierForUseTypeAnnotator	createDefaultForUseTypeAnnotator()	Creates an DefaultQualifierForUseTypeAnnotator.
AnnotationMirror	createMustCall(List<String> val)	Creates a MustCall annotation whose values are the given strings.
protected QualifierHierarchy	createQualifierHierarchy()	Returns the QualifierHierarchy to be used by this checker.
protected QualifierPolymorphism	createQualifierPolymorphism()	Creates the QualifierPolymorphism instance which supports the QualifierPolymorphism mechanism.
protected QualifierUpperBounds	createQualifierUpperBounds()	Creates QualifierUpperBounds for this type factory.
protected Set<Class<? extends Annotation>>	createSupportedTypeQualifiers()	Returns a mutable set of annotation classes that are supported by a checker.
protected TreeAnnotator	createTreeAnnotator()	Returns a TreeAnnotator that adds annotations to a type based on the contents of a tree.
protected TypeAnnotator	createTypeAnnotator()	Returns a DefaultForTypeAnnotator that adds annotations to a type based on the content of the type itself.
ExecutableElement	getCreatesMustCallForListValueElement()	Returns the CreatesMustCallFor.List.value field/element.
ExecutableElement	getCreatesMustCallForValueElement()	Returns the CreatesMustCallFor.value field/element.
ExecutableElement	getMustCallValueElement()	Returns the MustCall.value() element.
CFStore	getStoreForBlock(boolean afterFirstStore, Block first, Block succ)	Fetches the store from the results of dataflow for first.
@Nullable LocalVariableNode	getTempVar(Node node)	Return the temporary variable for node, if it exists.
protected boolean	isWpiEnabledForRLC()	Checks if WPI is enabled for the Resource Leak Checker inference.
void	methodFromUsePreSubstitution(ExpressionTree tree, AnnotatedTypeMirror.AnnotatedExecutableType type, boolean resolvePolyQuals)	Treat non-owning method parameters as @MustCallUnknown (top) when the method is called.
void	setRoot(@Nullable CompilationUnitTree root)	Set the CompilationUnitTree that should be used.
boolean	shouldHaveNoMustCallObligation(TypeMirror type)	Returns true if the given type should never have a must-call obligation.
AnnotationMirror	withoutClose(@Nullable AnnotationMirror anno)	Returns a @MustCall annotation that is like the input, but it does not have "close".

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

createFlowAnalysis

Methods inherited from class org.checkerframework.framework.type.GenericAnnotatedTypeFactory

addAnnotationsFromDefaultForType, addCheckedCodeDefaults, addCheckedStandardDefaults, addComputedTypeAnnotations, addComputedTypeAnnotations, addComputedTypeAnnotations, addComputedTypeAnnotationsForWarnRedundant, addDefaultAnnotations, addSharedCFGForTree, addUncheckedStandardDefaults, analyze, annotationsForIrrelevantJavaType, applyInferredAnnotations, applyQualifierParameterDefaults, applyQualifierParameterDefaults, checkAndPerformFlowAnalysis, checkForDefaultQualifierInHierarchy, constructorFromUse, createAndInitQualifierDefaults, createCFGVisualizer, createContractsFromMethod, createDefaultForTypeAnnotator, createDependentTypesHelper, createFlowTransferFunction, createQualifierDefaults, createRequiresOrEnsuresQualifier, getAnnotatedTypeLhs, getAnnotatedTypeLhsNoTypeVarDefault, getAnnotatedTypeRhsUnaryAssign, getAnnotatedTypeVarargsArray, getAnnotationFromJavaExpression, getAnnotationFromJavaExpressionString, getAnnotationMirrorFromJavaExpressionString, getAnnotationsFromJavaExpression, getCFGVisualizer, getContractAnnotations, getContractAnnotations, getContractExpressions, getContractsFromMethod, getDefaultAnnotations, getDefaultAnnotationsForWarnRedundant, getDefaultForTypeAnnotator, getDefaultValueAnnotatedType, getDependentTypesHelper, getEmptyStore, getEnsuresQualifierIfResult, getExceptionalExitStore, getExplicitNewClassAnnos, getExplicitNewClassClassTypeArgs, getExpressionAndOffsetFromJavaExpressionString, getFinalLocalValues, getFirstNodeOfKindForTree, getInferredValueFor, getMethodReturnType, getNodesForTree, getPostconditionAnnotations, getPostconditionAnnotations, getPostconditionAnnotations, getPreconditionAnnotations, getPreconditionAnnotations, getPreconditionAnnotations, getPreOrPostconditionAnnotations, getQualifierPolymorphism, getRegularExitStore, getReturnStatementStores, getSharedCFGForTree, getShouldDefaultTypeVarLocals, getSortedQualifierNames, getStoreAfter, getStoreAfter, getStoreAfter, getStoreBefore, getStoreBefore, getStoreBefore, getSupportedMonotonicTypeQualifiers, getTypeFactoryOfSubchecker, getTypeFactoryOfSubcheckerOrNull, handleCFGViz, irrelevantExtraMessage, isIgnoredExceptionType, isRelevant, isRelevant, isRelevantImpl, isUnreachable, methodFromUse, parseJavaExpressionString, performFlowAnalysis, postAnalyze, postAsMemberOf, postDirectSuperTypes, postInit, preProcessClassTree, typeVariablesFromUse

Methods inherited from class org.checkerframework.framework.type.AnnotatedTypeFactory

adaptGetClassReturnTypeToReceiver, addAliasedDeclAnnotation, addAliasedTypeAnnotation, addAliasedTypeAnnotation, addAliasedTypeAnnotation, addAliasedTypeAnnotation, addAnnotationFromFieldInvariant, addInheritedAnnotation, applyCaptureConversion, applyCaptureConversion, applyUnboxing, areSameByClass, binaryTreeArgTypes, binaryTreeArgTypes, canonicalAnnotation, checkInvalidOptionsInferSignatures, compoundAssignmentTreeArgTypes, constructorFromUse, constructorFromUseWithoutTypeArgInference, containsCapturedTypes, containsSameByClass, createAnnotatedTypeFormatter, createAnnotationClassLoader, createAnnotationFormatter, createTypeArgumentInference, createTypeHierarchy, createTypeVariableSubstitutor, declarationFromElement, doesAnnotatedForApplyToThisChecker, fromElement, fromElement, fromElement, getAnnotatedNullType, getAnnotatedType, getAnnotatedType, getAnnotatedType, getAnnotatedType, getAnnotatedType, getAnnotatedType, getAnnotatedType, getAnnotatedType, getAnnotatedType, getAnnotatedTypeFormatter, getAnnotatedTypeFromTypeTree, getAnnotationByClass, getAnnotationFormatter, getAnnotationMirror, getAnnotationWithMetaAnnotation, getBoxedType, getBundledTypeQualifiers, getCacheSize, getChecker, getCheckerNames, getContractExpressions, getContractListValues, getDeclAnnotation, getDeclAnnotationNoAliases, getDeclAnnotations, getDeclAnnotationWithMetaAnnotation, getDefaultTypeDeclarationBounds, getDummyAssignedTo, getElementUtils, getEnclosingClassOrMethod, getEnclosingElementForArtificialTree, getEnclosingSubType, getEnclosingType, getEnumConstructorQualifiers, getExpressionAndOffset, getFieldInvariantAnnotationTree, getFieldInvariantDeclarationAnnotations, getFieldInvariants, getFnInterfaceFromTree, getFunctionTypeFromTree, getFunctionTypeFromTree, getImplicitReceiverType, getIterableElementType, getIterableElementType, getMethodReturnType, getNarrowedAnnotations, getNarrowedPrimitive, getPath, getProcessingEnv, getQualifierHierarchy, getQualifierParameterHierarchies, getQualifierParameterHierarchies, getQualifierUpperBounds, getReceiverType, getResultingTypeOfConstructorMemberReference, getSelfType, getStringType, getSupportedTypeQualifierNames, getSupportedTypeQualifiers, getTreeUtils, getTypeArgumentInference, getTypeDeclarationBounds, getTypeHierarchy, getTypeOfExtendsImplements, getTypeVarSubstitutor, getUnboxedType, getVisitorTreePath, getWholeProgramInference, getWidenedAnnotations, getWidenedType, getWidenedType, hasExplicitNoQualifierParameterInHierarchy, hasExplicitQualifierParameterInHierarchy, hasQualifierParameterInHierarchy, hasQualifierParameterInHierarchy, initializeAtm, initializeReflectionResolution, isDeterministic, isFromByteCode, isFromStubFile, isImmutable, isSideEffectFree, isSupportedQualifier, isSupportedQualifier, isSupportedQualifier, isTop, isWithinConstructor, logGat, makeConditionConsistentWithOtherMethod, mergeAnnotationFileAnnosIntoType, methodFromUse, methodFromUse, methodFromUse, methodFromUseWithoutTypeArgInference, methodFromUseWithoutTypeArgInference, negateConstant, order, parseAnnotationFiles, postProcessClassTree, replaceAnnotations, replaceAnnotations, setEnclosingElementForArtificialTree, setVisitorTreePath, shouldWarnIfStubRedundantWithBytecode, toAnnotatedType, toString, type, wpiAdjustForUpdateField, wpiAdjustForUpdateNonField, wpiPrepareMethodForWriting, wpiPrepareMethodForWriting, wpiShouldInferTypesForReceivers

Methods inherited from class java.lang.Object

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

Field Details

TOP

public final AnnotationMirror TOP

The @MustCallUnknown annotation.

BOTTOM

public final AnnotationMirror BOTTOM

The @MustCall() annotation. It is the default in unannotated code.

POLY

public final AnnotationMirror POLY

The @PolyMustCall annotation.

Constructor Details

MustCallAnnotatedTypeFactory

public MustCallAnnotatedTypeFactory(BaseTypeChecker checker)

Creates a MustCallAnnotatedTypeFactory.

Parameters:

checker - the checker associated with this type factory

Method Details

setRoot

public void setRoot(@Nullable CompilationUnitTree root)

Description copied from class: AnnotatedTypeFactory

Set the CompilationUnitTree that should be used.

Overrides:

setRoot in class GenericAnnotatedTypeFactory<CFValue,CFStore,CFTransfer,CFAnalysis>

Parameters:

root - the new compilation unit to use

createSupportedTypeQualifiers

protected Set<Class<? extends Annotation>> createSupportedTypeQualifiers()

Description copied from class: AnnotatedTypeFactory

Returns a mutable set of annotation classes that are supported by a checker.

Subclasses may override this method to return a mutable set of their supported type qualifiers through one of the 5 approaches shown below.

Subclasses should not call this method; they should call AnnotatedTypeFactory.getSupportedTypeQualifiers() instead.

By default, a checker supports all annotations located in a subdirectory called qual that's located in the same directory as the checker. Note that only annotations defined with the @Target({ElementType.TYPE_USE}) meta-annotation (and optionally with the additional value of ElementType.TYPE_PARAMETER, but no other ElementType values) are automatically considered as supported annotations.

To support a different set of annotations than those in the qual subdirectory, or that have other ElementType values, see examples below.

In total, there are 5 ways to indicate annotations that are supported by a checker:

1. Only support annotations located in a checker's qual directory:

   This is the default behavior. Simply place those annotations within the qual directory.

2. Support annotations located in a checker's qual directory and a list of other annotations:

   Place those annotations within the qual directory, and override AnnotatedTypeFactory.createSupportedTypeQualifiers() by calling AnnotatedTypeFactory.getBundledTypeQualifiers(Class...) with a varargs parameter list of the other annotations. Code example:

    @Override protected Set<Class<? extends Annotation>> createSupportedTypeQualifiers() {
         return getBundledTypeQualifiers(Regex.class, PartialRegex.class, RegexBottom.class, UnknownRegex.class);
     } 
    

3. Supporting only annotations that are explicitly listed: Override AnnotatedTypeFactory.createSupportedTypeQualifiers() and return a mutable set of the supported annotations. Code example:

    @Override protected Set<Class<? extends Annotation>> createSupportedTypeQualifiers() {
         return new HashSet<Class<? extends Annotation>>(
                 Arrays.asList(A.class, B.class));
     } 
    

   The set of qualifiers returned by AnnotatedTypeFactory.createSupportedTypeQualifiers() must be a fresh, mutable set. The methods AnnotatedTypeFactory.getBundledTypeQualifiers(Class...) must return a fresh, mutable set

Overrides:

createSupportedTypeQualifiers in class AnnotatedTypeFactory

Returns:

the type qualifiers supported this processor, or an empty set if none

createTreeAnnotator

protected TreeAnnotator createTreeAnnotator()

Description copied from class: GenericAnnotatedTypeFactory

Returns a TreeAnnotator that adds annotations to a type based on the contents of a tree.

The default tree annotator is a ListTreeAnnotator of the following:

1. PropagationTreeAnnotator: Propagates annotations from subtrees
2. LiteralTreeAnnotator: Adds annotations based on QualifierForLiterals meta-annotations
3. DependentTypesTreeAnnotator: Adapts dependent annotations based on context

Subclasses may override this method to specify additional tree annotators, for example:

 new ListTreeAnnotator(super.createTreeAnnotator(), new KeyLookupTreeAnnotator(this));
 

Overrides:

createTreeAnnotator in class GenericAnnotatedTypeFactory<CFValue,CFStore,CFTransfer,CFAnalysis>

Returns:

a tree annotator

createTypeAnnotator

protected TypeAnnotator createTypeAnnotator()

Description copied from class: GenericAnnotatedTypeFactory

Returns a DefaultForTypeAnnotator that adds annotations to a type based on the content of the type itself.

Subclass may override this method. The default type annotator is a ListTypeAnnotator of the following:

1. IrrelevantTypeAnnotator: Adds top to types not listed in the @RelevantJavaTypes annotation on the checker.
2. PropagationTypeAnnotator: Propagates annotation onto wildcards.

Overrides:

createTypeAnnotator in class GenericAnnotatedTypeFactory<CFValue,CFStore,CFTransfer,CFAnalysis>

Returns:

a type annotator

withoutClose

public AnnotationMirror withoutClose(@Nullable AnnotationMirror anno)

Returns a @MustCall annotation that is like the input, but it does not have "close". Returns the argument annotation mirror (not a new one) if the argument doesn't have "close" as one of its elements.

If the argument is null, returns bottom.

Parameters:

anno - a MustCall annotation

Returns:

a MustCall annotation that does not have "close" as one of its values, but is otherwise identical to anno

methodFromUsePreSubstitution

public void methodFromUsePreSubstitution(ExpressionTree tree,
 AnnotatedTypeMirror.AnnotatedExecutableType type,
 boolean resolvePolyQuals)

Treat non-owning method parameters as @MustCallUnknown (top) when the method is called.

Overrides:

methodFromUsePreSubstitution in class GenericAnnotatedTypeFactory<CFValue,CFStore,CFTransfer,CFAnalysis>

Parameters:

tree - either a method invocation or a member reference tree

type - declared method type before type variable substitution

resolvePolyQuals - whether to resolve polymorphic qualifiers

constructorFromUsePreSubstitution

protected void constructorFromUsePreSubstitution(NewClassTree tree,
 AnnotatedTypeMirror.AnnotatedExecutableType type,
 boolean resolvePolyQuals)

Description copied from class: AnnotatedTypeFactory

A callback method for the AnnotatedTypeFactory subtypes to customize the handling of the declared constructor type before type variable substitution.

Overrides:

constructorFromUsePreSubstitution in class GenericAnnotatedTypeFactory<CFValue,CFStore,CFTransfer,CFAnalysis>

Parameters:

tree - a NewClassTree from constructorFromUse()

type - declared method type before type variable substitution

resolvePolyQuals - whether to resolve polymorphic qualifiers

createQualifierPolymorphism

protected QualifierPolymorphism createQualifierPolymorphism()

Description copied from class: GenericAnnotatedTypeFactory

Creates the QualifierPolymorphism instance which supports the QualifierPolymorphism mechanism.

Overrides:

createQualifierPolymorphism in class GenericAnnotatedTypeFactory<CFValue,CFStore,CFTransfer,CFAnalysis>

Returns:

the QualifierPolymorphism instance to use

createDefaultForUseTypeAnnotator

protected DefaultQualifierForUseTypeAnnotator createDefaultForUseTypeAnnotator()

Description copied from class: GenericAnnotatedTypeFactory

Creates an DefaultQualifierForUseTypeAnnotator.

Overrides:

createDefaultForUseTypeAnnotator in class GenericAnnotatedTypeFactory<CFValue,CFStore,CFTransfer,CFAnalysis>

Returns:

a new DefaultQualifierForUseTypeAnnotator

getMustCallValueElement

public ExecutableElement getMustCallValueElement()

Returns the MustCall.value() element. For use with AnnotationUtils.getElementValueArray(javax.lang.model.element.AnnotationMirror, java.lang.CharSequence, java.lang.Class<T>, boolean).

Returns:

the MustCall.value() element

createQualifierUpperBounds

protected QualifierUpperBounds createQualifierUpperBounds()

Description copied from class: AnnotatedTypeFactory

Creates QualifierUpperBounds for this type factory.

Overrides:

createQualifierUpperBounds in class AnnotatedTypeFactory

Returns:

a new QualifierUpperBounds for this type factory

createMustCall

public AnnotationMirror createMustCall(List<String> val)

Creates a MustCall annotation whose values are the given strings.

Parameters:

val - the methods that should be called

Returns:

an annotation indicating that the given methods should be called

createQualifierHierarchy

protected QualifierHierarchy createQualifierHierarchy()

Description copied from class: AnnotatedTypeFactory

Returns the QualifierHierarchy to be used by this checker.

The implementation builds the type qualifier hierarchy for the AnnotatedTypeFactory.getSupportedTypeQualifiers() using the meta-annotations found in them. The current implementation returns an instance of NoElementQualifierHierarchy.

Subclasses must override this method if their qualifiers have elements; the method must return an implementation of QualifierHierarchy, such as ElementQualifierHierarchy.

Overrides:

createQualifierHierarchy in class AnnotatedTypeFactory

Returns:

a QualifierHierarchy for this type system

getStoreForBlock

public CFStore getStoreForBlock(boolean afterFirstStore,
 Block first,
 Block succ)

Fetches the store from the results of dataflow for first. If afterFirstStore is true, then the store after first is returned; if afterFirstStore is false, the store before succ is returned.

Parameters:

afterFirstStore - whether to use the store after the first block or the store before its successor, succ

first - a block

succ - first's successor

Returns:

the appropriate CFStore, populated with MustCall annotations, from the results of running dataflow

getCreatesMustCallForValueElement

public ExecutableElement getCreatesMustCallForValueElement()

Returns the CreatesMustCallFor.value field/element.

Specified by:

getCreatesMustCallForValueElement in interface CreatesMustCallForElementSupplier

Returns:

the CreatesMustCallFor.value field/element

getCreatesMustCallForListValueElement

public ExecutableElement getCreatesMustCallForListValueElement()

Returns the CreatesMustCallFor.List.value field/element.

Specified by:

getCreatesMustCallForListValueElement in interface CreatesMustCallForElementSupplier

Returns:

the CreatesMustCallFor.List.value field/element

getTempVar

public @Nullable LocalVariableNode getTempVar(Node node)

Return the temporary variable for node, if it exists. See #tempVars.

Parameters:

node - a CFG node

Returns:

the corresponding temporary variable, or null if there is not one

isWpiEnabledForRLC

protected boolean isWpiEnabledForRLC()

Checks if WPI is enabled for the Resource Leak Checker inference. See ResourceLeakChecker.ENABLE_WPI_FOR_RLC.

Returns:

returns true if WPI is enabled for the Resource Leak Checker

shouldHaveNoMustCallObligation

public boolean shouldHaveNoMustCallObligation(TypeMirror type)

Returns true if the given type should never have a must-call obligation.

Parameters:

type - the type to check

Returns:

true if the given type should never have a must-call obligation