org.checkerframework.checker.index.upperbound

Class UpperBoundAnnotatedTypeFactory

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.index.upperbound.UpperBoundAnnotatedTypeFactory

All Implemented Interfaces:

AnnotationProvider

public class UpperBoundAnnotatedTypeFactory
extends BaseAnnotatedTypeFactory

Implements the introduction rules for the Upper Bound Checker.

Rules implemented by this class:

• 1. Math.min has unusual semantics that combines annotations for the UBC.
• 2. The return type of Random.nextInt depends on the argument, but is not equal to it, so a polymorhpic qualifier is insufficient.
• 3. Unary negation on a NegativeIndexFor (from the SearchIndex Checker) results in a LTLengthOf for the same arrays.
• 4. Right shifting by a constant between 0 and 30 preserves the type of the left side expression.
• 5. If either argument to a bitwise and expression is non-negative, the and expression retains that argument's upperbound type. If both are non-negative, the result of the expression is the GLB of the two.
• 6. if numerator ≥ 0, then numerator % divisor ≤ numerator
• 7. if divisor ≥ 0, then numerator % divisor < divisor
• 8. If the numerator is an array length access of an array with non-zero length, and the divisor is greater than one, glb the result with an LTL of the array.
• 9. if numeratorTree is a + b and divisor greater than 1, and a and b are less than the length of some sequence, then (a + b) / divisor is less than the length of that sequence.
• 10. Special handling for Math.random: Math.random() * array.length is LTL array.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	UpperBoundAnnotatedTypeFactory.UpperBoundQualifierHierarchy The qualifier hierarchy for the upperbound type system.
protected class	UpperBoundAnnotatedTypeFactory.UpperBoundTreeAnnotator

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

Field Summary

Fields

Modifier and Type	Field and Description
javax.lang.model.element.AnnotationMirror	BOTTOM The @UpperBoundBottom annotation.
javax.lang.model.element.AnnotationMirror	POLY The @PolyUpperBound annotation.
javax.lang.model.element.AnnotationMirror	UNKNOWN The @UpperBoundUnknown annotation.

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

analysis, cfgVisualizer, defaults, dependentTypesHelper, emptyStore, flowByDefault, flowResult, flowResultAnalysisCaches, initializationStaticStore, initializationStore, methodInvocationStores, poly, regularExitStores, returnStatementStores, scannedClasses, transfer, treeAnnotator, typeAnnotator

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

checker, elements, fromExpressionTreeCache, fromMemberTreeCache, fromTypeTreeCache, ignoreUninferredTypeArguments, loader, objectGetClass, processingEnv, qualHierarchy, qualifierUpperBounds, reflectionResolver, root, shouldCache, trees, typeArgumentInference, typeFormatter, typeHierarchy, types, typeVarSubstitutor, uid, visitorState

Constructor Summary

Constructors

Constructor and Description
UpperBoundAnnotatedTypeFactory(BaseTypeChecker checker) Create a new UpperBoundAnnotatedTypeFactory.

Method Summary

Modifier and Type	Method and Description
void	addComputedTypeAnnotations(javax.lang.model.element.Element element, AnnotatedTypeMirror type) To add annotations to the type of method or constructor parameters, add a TypeAnnotator using GenericAnnotatedTypeFactory.createTypeAnnotator() and see the comment in TypeAnnotator#visitExecutable(AnnotatedExecutableType, Void).
void	addComputedTypeAnnotations(com.sun.source.tree.Tree tree, AnnotatedTypeMirror type, boolean iUseFlow) Like GenericAnnotatedTypeFactory.addComputedTypeAnnotations(Tree, AnnotatedTypeMirror).
javax.lang.model.element.AnnotationMirror	convertUBQualifierToAnnotation(UBQualifier qualifier)
protected DependentTypesHelper	createDependentTypesHelper() Creates an DependentTypesHelper and returns it.
QualifierHierarchy	createQualifierHierarchy(MultiGraphQualifierHierarchy.MultiGraphFactory factory) Factory method to easily change what QualifierHierarchy is created.
protected java.util.Set<java.lang.Class<? extends java.lang.annotation.Annotation>>	createSupportedTypeQualifiers() Returns a mutable set of annotation classes that are supported by a checker.
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.
LessThanAnnotatedTypeFactory	getLessThanAnnotatedTypeFactory() Returns the LessThan Checker's annotated type factory.
boolean	hasLowerBoundTypeByClass(Node node, java.lang.Class<? extends java.lang.annotation.Annotation> classOfType) Returns true iff the given node has the passed Lower Bound qualifier according to the LBC.
boolean	isMathMin(com.sun.source.tree.Tree methodTree)
boolean	isRandomNextInt(com.sun.source.tree.Tree methodTree) Returns true if the tree is for Random.nextInt(int).
javax.lang.model.element.AnnotationMirror	sameLenAnnotationFromTree(com.sun.source.tree.Tree tree) Queries the SameLen Checker to return the type that the SameLen Checker associates with the given tree.

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

createFlowAnalysis

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

addAnnotationsFromDefaultQualifierForUse, addCheckedCodeDefaults, addCheckedStandardDefaults, addComputedTypeAnnotations, addDefaultAnnotations, addUncheckedCodeDefaults, addUncheckedStandardDefaults, analyze, applyInferredAnnotations, checkAndPerformFlowAnalysis, checkForDefaultQualifierInHierarchy, constructorFromUse, createAndInitQualifierDefaults, createCFGVisualizer, createDefaultForUseTypeAnnotator, createFlowTransferFunction, createQualifierDefaults, createQualifierPolymorphism, fromNewClass, getAnnotatedTypeLhs, getAnnotatedTypeLhsNoTypeVarDefault, getAnnotatedTypeRhsUnaryAssign, getAnnotatedTypeVarargsArray, getAnnotationFromJavaExpressionString, getAnnotationFromReceiver, getAnnotationMirrorFromJavaExpressionString, getCFGVisualizer, getDependentTypesHelper, getEmptyStore, getFinalLocalValues, getFirstNodeOfKindForTree, getInferredValueFor, getMethodReturnType, getMethodReturnType, getNodesForTree, getQualifierPolymorphism, getReceiverAndOffsetFromJavaExpressionString, getReceiverFromJavaExpressionString, getRegularExitStore, getResultingTypeOfConstructorMemberReference, getReturnStatementStores, getShouldDefaultTypeVarLocals, getSortedQualifierNames, getStoreAfter, getStoreAfter, getStoreAfter, getStoreBefore, getStoreBefore, getStoreBefore, getSupportedMonotonicTypeQualifiers, getTypeFactoryOfSubchecker, handleCFGViz, methodFromUse, performFlowAnalysis, postDirectSuperTypes, postInit, preProcessClassTree, setRoot, typeVariablesFromUse

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

adaptGetClassReturnTypeToReceiver, addAliasedAnnotation, addAliasedAnnotation, addAliasedAnnotation, addAliasedAnnotation, addAliasedDeclAnnotation, addAnnotationFromFieldInvariant, addInheritedAnnotation, canonicalAnnotation, checkInvalidOptionsInferSignatures, createAnnotatedTypeFormatter, createAnnotationClassLoader, createAnnotationFormatter, createQualifierHierarchy, createQualifierHierarchy, createQualifierHierarchyFactory, createQualifierUpperBounds, createTypeArgumentInference, createTypeHierarchy, createTypeVariableSubstitutor, declarationFromElement, fromElement, fromElement, fromElement, getAnnotatedNullType, getAnnotatedType, getAnnotatedType, getAnnotatedType, getAnnotatedType, getAnnotatedType, getAnnotatedType, getAnnotatedType, getAnnotatedType, getAnnotatedTypeFormatter, getAnnotatedTypeFromTypeTree, getAnnotationFormatter, getAnnotationMirror, getAnnotationWithMetaAnnotation, getBoxedType, getBundledTypeQualifiersWithoutPolyAll, getBundledTypeQualifiersWithPolyAll, getCacheSize, getContext, getCurrentClassTree, getCurrentClassType, getCurrentMethodReceiver, getDeclAnnotation, getDeclAnnotationNoAliases, getDeclAnnotations, getDeclAnnotationWithMetaAnnotation, getDefaultTypeDeclarationBounds, getDummyAssignedTo, getElementUtils, getEnclosingElementForArtificialTree, getEnclosingType, getExpressionAndOffset, getFieldInvariantAnnotationTree, getFieldInvariantDeclarationAnnotations, getFieldInvariants, getFnInterfaceFromTree, getFnInterfaceFromTree, getImplicitReceiverType, getNarrowedPrimitive, getPath, getProcessingEnv, getQualifierHierarchy, getReceiverType, getSelfType, getStringType, getSupportedTypeQualifiers, getTreeUtils, getTypeArgumentInference, getTypeDeclarationBounds, getTypeHierarchy, getTypeOfExtendsImplements, getTypeVarSubstitutor, getUnboxedType, getUninferredWildcardType, getVisitorState, getWholeProgramInference, initializeReflectionResolution, isAnyEnclosingThisDeref, isFromByteCode, isFromStubFile, isMostEnclosingThisDeref, isSupportedQualifier, isWithinConstructor, methodFromUse, negateConstant, parseStubFiles, postAsMemberOf, postProcessClassTree, postTypeVarSubstitution, setEnclosingElementForArtificialTree, shouldWarnIfStubRedundantWithBytecode, toAnnotatedType, toString, type, widenToUpperBound

Methods inherited from class java.lang.Object

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

Field Detail

UNKNOWN

public final javax.lang.model.element.AnnotationMirror UNKNOWN

The @UpperBoundUnknown annotation.

BOTTOM

public final javax.lang.model.element.AnnotationMirror BOTTOM

The @UpperBoundBottom annotation.

POLY

public final javax.lang.model.element.AnnotationMirror POLY

The @PolyUpperBound annotation.

Constructor Detail

UpperBoundAnnotatedTypeFactory

public UpperBoundAnnotatedTypeFactory(BaseTypeChecker checker)

Create a new UpperBoundAnnotatedTypeFactory.

Method Detail

createSupportedTypeQualifiers

protected java.util.Set<java.lang.Class<? extends java.lang.annotation.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 PolyAll, and 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 not support PolyAll, see examples below.

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, and PolyAll:

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

2. Support annotations located in a checker's qual directory, but without PolyAll:

   Place those annotations within the qual directory, and override AnnotatedTypeFactory.createSupportedTypeQualifiers() by calling AnnotatedTypeFactory.getBundledTypeQualifiersWithPolyAll(Class...) with no parameters passed in. Code example:

     @Override protected Set<Class<? extends Annotation>> createSupportedTypeQualifiers() {
         return getBundledTypeQualifiersWithoutPolyAll();
     } 
    

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

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

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

4. Support annotations located in a checker's qual directory and a list of other annotations, but without supporting PolyAll:

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

     @Override protected Set<Class<? extends Annotation>> createSupportedTypeQualifiers() {
         return getBundledTypeQualifiersWithoutPolyAll(UnknownFormat.class, FormatBottom.class);
     } 
    

5. 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.getBundledTypeQualifiersWithoutPolyAll(Class...) and AnnotatedTypeFactory.getBundledTypeQualifiersWithPolyAll(Class...) each must return a fresh, mutable set

Overrides:

createSupportedTypeQualifiers in class AnnotatedTypeFactory

Returns:

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

getLessThanAnnotatedTypeFactory

public LessThanAnnotatedTypeFactory getLessThanAnnotatedTypeFactory()

Returns the LessThan Checker's annotated type factory.

addComputedTypeAnnotations

public void addComputedTypeAnnotations(javax.lang.model.element.Element element,
                                       AnnotatedTypeMirror type)

Description copied from class: GenericAnnotatedTypeFactory

To add annotations to the type of method or constructor parameters, add a TypeAnnotator using GenericAnnotatedTypeFactory.createTypeAnnotator() and see the comment in TypeAnnotator#visitExecutable(AnnotatedExecutableType, Void).

Overrides:

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

Parameters:

element - an element

type - the type obtained from elt

addComputedTypeAnnotations

public void addComputedTypeAnnotations(com.sun.source.tree.Tree tree,
                                       AnnotatedTypeMirror type,
                                       boolean iUseFlow)

Description copied from class: GenericAnnotatedTypeFactory

Like GenericAnnotatedTypeFactory.addComputedTypeAnnotations(Tree, AnnotatedTypeMirror). Overriding implementations typically simply pass the boolean to calls to super.

Overrides:

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

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.
3. DefaultForTypeAnnotator: Adds annotations based on DefaultFor meta-annotations.

Overrides:

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

Returns:

a type annotator

createDependentTypesHelper

protected DependentTypesHelper createDependentTypesHelper()

Description copied from class: GenericAnnotatedTypeFactory

Creates an DependentTypesHelper and returns it.

Overrides:

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

Returns:

a new DependentTypesHelper

sameLenAnnotationFromTree

public javax.lang.model.element.AnnotationMirror sameLenAnnotationFromTree(com.sun.source.tree.Tree tree)

Queries the SameLen Checker to return the type that the SameLen Checker associates with the given tree.

isMathMin

public boolean isMathMin(com.sun.source.tree.Tree methodTree)

isRandomNextInt

public boolean isRandomNextInt(com.sun.source.tree.Tree methodTree)

Returns true if the tree is for Random.nextInt(int).

Parameters:

methodTree - a tree to check

Returns:

true iff the tree is for Random.nextInt(int)

hasLowerBoundTypeByClass

public boolean hasLowerBoundTypeByClass(Node node,
                                        java.lang.Class<? extends java.lang.annotation.Annotation> classOfType)

Returns true iff the given node has the passed Lower Bound qualifier according to the LBC. The last argument should be Positive.class, NonNegative.class, or GTENegativeOne.class.

createQualifierHierarchy

public QualifierHierarchy createQualifierHierarchy(MultiGraphQualifierHierarchy.MultiGraphFactory factory)

Description copied from class: AnnotatedTypeFactory

Factory method to easily change what QualifierHierarchy is created. Needs to be public only because the GraphFactory must be able to call this method. No external use of this method is necessary.

Overrides:

createQualifierHierarchy in class AnnotatedTypeFactory

createTreeAnnotator

public 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

convertUBQualifierToAnnotation

public javax.lang.model.element.AnnotationMirror convertUBQualifierToAnnotation(UBQualifier qualifier)