Class AnnotatedTypeFactory
- All Implemented Interfaces:
AnnotationProvider
- Direct Known Subclasses:
GenericAnnotatedTypeFactory
,TypeOutputtingChecker.GeneralAnnotatedTypeFactory
AnnotatedTypeMirror
. The methods are:
getAnnotatedType(ClassTree)
getAnnotatedType(MethodTree)
getAnnotatedType(Tree)
getAnnotatedTypeFromTypeTree(Tree)
getAnnotatedType(TypeElement)
getAnnotatedType(ExecutableElement)
getAnnotatedType(Element)
addComputedTypeAnnotations(com.sun.source.tree.Tree, org.checkerframework.framework.type.AnnotatedTypeMirror)
to add defaults, flow-sensitive refinement, and
type-system-specific rules.
Unless otherwise indicated, each public method in this class returns a "fully annotated" type, which is one that has an annotation in all positions.
Type system checker writers may need to subclass this class, to add default qualifiers
according to the type system semantics. Subclasses should especially override addComputedTypeAnnotations(Element, AnnotatedTypeMirror)
and addComputedTypeAnnotations(Tree, AnnotatedTypeMirror)
to handle default annotations. (Also,
addDefaultAnnotations(AnnotatedTypeMirror)
adds annotations, but that method is a
workaround for Issue
979.)
- See the Checker Framework Manual:
- How to write a checker plug-in
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
Substitutes references to captured types intype
usingcapturedTypeVarToAnnotatedTypeVar
.static class
The type for an instantiated generic method or constructor. -
Field Summary
Modifier and TypeFieldDescriptionParses ajava files and stores annotations on public elements from ajava files.protected final ExecutableElement
The AnnotatedFor.value argument/element.Mapping from CFG-generated trees to their enclosing elements.Substitutes references to captured type variables.protected final BaseTypeChecker
The checker to use for option handling and resource management.protected @Nullable AnnotationFileElementTypes
If type checking a Java file, stores annotations read from an ajava file for that class if one exists.protected final Elements
Utility class for working withElement
s.protected final ExecutableElement
The EnsuresQualifier.expression field/element.protected final ExecutableElement
The EnsuresQualifierIf.expression field/element.protected final TypeMirror
The EnsuresQualifierIf.List type.protected final ExecutableElement
The EnsuresQualifierIf.List.value field/element.protected final ExecutableElement
The EnsuresQualifierIf.result argument/element.protected final TypeMirror
The EnsuresQualifierIf type.protected final TypeMirror
The EnsuresQualifier.List type.protected final ExecutableElement
The EnsuresQualifier.List.value field/element.protected final TypeMirror
The EnsuresQualifier type.protected final ExecutableElement
The FieldInvariant.field argument/element.protected final ExecutableElement
The FieldInvariant.qualifier argument/element.protected final Map<Tree,
AnnotatedTypeMirror> Mapping from an expression tree to its annotated type; before defaults are applied, just what the programmer wrote.protected final Map<Tree,
AnnotatedTypeMirror> Mapping from a member tree to its annotated type; before defaults are applied, just what the programmer wrote.protected final Map<Tree,
AnnotatedTypeMirror> Mapping from a type tree to its annotated type; before defaults are applied, just what the programmer wrote.protected final ExecutableElement
The HasQualifierParameter.value field/element.final boolean
Whether to ignore type arguments from raw types.protected AnnotationClassLoader
This loads type annotation classes via reflective lookup.final ExecutableElement
The MethodVal.className argument/element.final ExecutableElement
The MethodVal.methodName argument/element.final ExecutableElement
The MethodVal.params argument/element.protected final ExecutableElement
The NoQualifierParameter.value field/element.protected final ExecutableElement
The Object.getClass method.protected final ProcessingEnvironment
The processing environment to use for accessing compiler internals.protected QualifierHierarchy
Represent the annotation relations.protected QualifierUpperBounds
Holds the qualifier upper bounds for type uses.protected ReflectionResolver
Object that is used to resolve reflective method calls, if reflection resolution is turned on.protected final ExecutableElement
The RequiresQualifier.expression field/element.protected final TypeMirror
The RequiresQualifier.List type.protected final ExecutableElement
The RequiresQualifier.List.value field/element.protected final TypeMirror
The RequiresQualifier type.protected @Nullable CompilationUnitTree
Optional! The AST of the source file being operated on.boolean
Should results be cached? This means that ATM.deepCopy() will be called.Parses stub files and stores annotations on public elements from stub files.protected final Trees
TheTrees
instance to use for tree node path finding.protected TypeArgumentInference
Provides utility method to infer type arguments.protected final AnnotatedTypeFormatter
This formatter is used for converting AnnotatedTypeMirrors to Strings.protected TypeHierarchy
Represent the type relations.final Types
Utility class for working withTypeMirror
s.protected TypeVariableSubstitutor
Provides utility method to substitute arguments for their type variables.final int
Unique ID of the current object; for debugging purposes.Which whole-program inference output format to use, if doing whole-program inference. -
Constructor Summary
ConstructorDescriptionAnnotatedTypeFactory
(BaseTypeChecker checker) Constructs a factory from the given checker. -
Method Summary
Modifier and TypeMethodDescriptionprotected void
adaptGetClassReturnTypeToReceiver
(AnnotatedTypeMirror.AnnotatedExecutableType getClassType, AnnotatedTypeMirror receiverType, ExpressionTree tree) Java special-cases the return type ofgetClass()
.protected void
addAliasedDeclAnnotation
(Class<? extends Annotation> alias, Class<? extends Annotation> annotation, AnnotationMirror annotationToUse) Add the annotationalias
as an alias for the declaration annotationannotation
, where the annotation mirrorannotationToUse
will be used instead.protected void
addAliasedTypeAnnotation
(@FullyQualifiedName String aliasName, Class<?> canonicalAnno, boolean copyElements, String... ignorableElements) Adds the annotation, whose fully-qualified name is given byaliasName
, as an alias for the canonical annotationcanonicalAnno
that will be used by the Checker Framework in the alias's place.protected void
addAliasedTypeAnnotation
(@FullyQualifiedName String aliasName, AnnotationMirror canonicalAnno) Adds the annotation, whose fully-qualified name is given byaliasName
, as an alias for the canonical annotationcanonicalAnno
that will be used by the Checker Framework in the alias's place.protected void
addAliasedTypeAnnotation
(Class<?> aliasClass, Class<?> canonicalClass, boolean copyElements, String... ignorableElements) Adds the annotationaliasClass
as an alias for the canonical annotationcanonicalClass
that will be used by the Checker Framework in the alias's place.protected void
addAliasedTypeAnnotation
(Class<?> aliasClass, AnnotationMirror canonicalAnno) Adds the annotationaliasClass
as an alias for the canonical annotationcanonicalAnno
that will be used by the Checker Framework in the alias's place.protected void
addAnnotationFromFieldInvariant
(AnnotatedTypeMirror type, AnnotatedTypeMirror accessedVia, VariableElement field) Adds the qualifier specified by a field invariant forfield
totype
.protected void
addComputedTypeAnnotations
(Tree tree, AnnotatedTypeMirror type) Changes annotations on a type obtained from aTree
.protected void
addComputedTypeAnnotations
(Element elt, AnnotatedTypeMirror type) Changes annotations on a type obtained from anElement
.void
Adds default annotations totype
.protected void
addInheritedAnnotation
(AnnotationMirror annotation) Adds the annotationannotation
in the set of declaration annotations that should be inherited.applyCaptureConversion
(AnnotatedTypeMirror typeToCapture) Apply capture conversion totypeToCapture
.applyCaptureConversion
(AnnotatedTypeMirror type, TypeMirror typeMirror) Apply capture conversion totype
.Return a primitive type: either the argument, or the result of unboxing it (which might affect its annotations).boolean
areSameByClass
(AnnotationMirror am, Class<? extends Annotation> annoClass) Checks that the annotationam
has the name ofannoClass
.org.plumelib.util.IPair<AnnotatedTypeMirror,
AnnotatedTypeMirror> binaryTreeArgTypes
(BinaryTree tree) Returns the types of the two arguments to the BinaryTree, accounting for widening and unboxing if applicable.org.plumelib.util.IPair<AnnotatedTypeMirror,
AnnotatedTypeMirror> binaryTreeArgTypes
(AnnotatedTypeMirror left, AnnotatedTypeMirror right) Returns the types of the two arguments to a binary operation, accounting for widening and unboxing if applicable.Returns the canonical annotation for the passed annotation.protected void
This method is called only when-Ainfer
is passed as an option.org.plumelib.util.IPair<AnnotatedTypeMirror,
AnnotatedTypeMirror> Returns the types of the two arguments to the CompoundAssignmentTree, accounting for widening and unboxing if applicable.Determines the type of the invoked constructor based on the passed new class tree.constructorFromUse
(NewClassTree tree, boolean inferTypeArgs) The implementation ofconstructorFromUse(NewClassTree)
andconstructorFromUseWithoutTypeArgInference(NewClassTree)
.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.The same asconstructorFromUse(NewClassTree)
, but no type arguments are inferred.boolean
Returns true iftype
contains any captured type variables.boolean
containsSameByClass
(Collection<? extends AnnotationMirror> c, Class<? extends Annotation> anno) Checks that the collection contains the annotation.protected AnnotatedTypeFormatter
Creates the AnnotatedTypeFormatter used by this type factory and all AnnotatedTypeMirrors it creates.protected AnnotationClassLoader
Factory method to easily change whatAnnotationClassLoader
is created to load type annotation classes.protected AnnotationFormatter
protected QualifierHierarchy
Returns theQualifierHierarchy
to be used by this checker.protected QualifierUpperBounds
CreatesQualifierUpperBounds
for this type factory.protected Set<Class<? extends Annotation>>
Returns a mutable set of annotation classes that are supported by a checker.protected TypeArgumentInference
Creates the object that infers type arguments.protected TypeHierarchy
Creates the type hierarchy to be used by this factory.protected TypeVariableSubstitutor
TypeVariableSubstitutor provides a method to replace type parameters with their arguments.Gets the declaration tree for the element, if the source is available.boolean
doesAnnotatedForApplyToThisChecker
(AnnotationMirror annotatedForAnno) Doesanno
, which is anAnnotatedFor
annotation, apply to this checker?fromElement
(Element elt) Creates an AnnotatedTypeMirror forelt
that includes: annotations explicitly written on the element and annotations from stub files.SeefromElement(Element)
.fromElement
(TypeElement elt) SeefromElement(Element)
.getAnnotatedNullType
(Set<? extends AnnotationMirror> annotations) Creates and returns an AnnotatedNullType qualified withannotations
.getAnnotatedType
(ClassTree tree) getAnnotatedType
(MethodTree tree) getAnnotatedType
(NewArrayTree tree) getAnnotatedType
(NewClassTree tree) getAnnotatedType
(Tree tree) Returns an AnnotatedTypeMirror representing the annotated type oftree
.getAnnotatedType
(Class<?> clazz) Returns an AnnotatedTypeMirror representing the annotated type ofclazz
.getAnnotatedType
(Element elt) Returns an AnnotatedTypeMirror representing the annotated type ofelt
.Determines the annotated type from a type in tree form.getAnnotationByClass
(Collection<? extends AnnotationMirror> c, Class<? extends Annotation> anno) Returns the AnnotationMirror inc
that has the same class asanno
.getAnnotationMirror
(Tree tree, Class<? extends Annotation> target) Return the annotation ontree
that is in the hierarchy that contains the qualifiertarget
.List<org.plumelib.util.IPair<AnnotationMirror,
AnnotationMirror>> getAnnotationWithMetaAnnotation
(Element element, Class<? extends Annotation> metaAnnotationClass) Returns a list of all annotations used to annotate this element, which have a meta-annotation (i.e., an annotation on that annotation) with classmetaAnnotationClass
.Returns the annotated boxed type of the given primitive type.protected final Set<Class<? extends Annotation>>
getBundledTypeQualifiers
(Class<? extends Annotation>... explicitlyListedAnnotations) Loads all annotations contained in the qual directory of a checker via reflection; if a polymorphic type qualifier exists, and an explicit array of annotations to the set of annotation classes.protected int
Returns the size for LRU caches.Returns the checker associated with this factory.Returns the names of the annotation processors that are being run.getContractExpressions
(AnnotationMirror contractAnno) Get theexpression
field/element of the given contract annotation.getContractListValues
(AnnotationMirror contractListAnno) Get thevalue
field/element of the given contract list annotation.final AnnotationMirror
getDeclAnnotation
(Element elt, Class<? extends Annotation> anno) Returns all of the declaration annotations whose name equals the passed annotation class (or is an alias for it) including annotations: on the element written in stubfiles inherited from overridden methods, (seeInheritedAnnotation
) inherited from superclasses or super interfaces (seeInherited
)final @Nullable AnnotationMirror
getDeclAnnotationNoAliases
(Element elt, Class<? extends Annotation> anno) Returns the annotation mirror used to annotate this element, whose name equals the passed annotation class.Returns all of the declaration annotations on this element including annotations: on the element written in stubfiles inherited from overridden methods, (seeInheritedAnnotation
) inherited from superclasses or super interfaces (seeInherited
)List<org.plumelib.util.IPair<AnnotationMirror,
AnnotationMirror>> getDeclAnnotationWithMetaAnnotation
(Element element, Class<? extends Annotation> metaAnnotationClass) Returns a list of all declaration annotations used to annotate the element, which have a meta-annotation (i.e., an annotation on that annotation) with classmetaAnnotationClass
.protected AnnotationMirrorSet
Returns the set of qualifiers that are the upper bound for a type use if no other bound is specified for the type.getDummyAssignedTo
(ExpressionTree expressionTree) Returnsnull
or an annotated type mirror that type argument inference should assumeexpressionTree
is assigned to.final Elements
Returns the utility class for working withElement
s.Returns the innermost enclosing method or class tree oftree
.Gets theElement
representing the declaration of the method enclosing a tree AST node.getEnclosingSubType
(TypeElement typeElement, Tree tree) Returns theAnnotatedTypeMirror
of the enclosing type at the location oftree
that is a subtype oftypeElement
.getEnclosingType
(TypeElement typeElement, Tree tree) Returns theAnnotatedTypeMirror
of the enclosing type at the location oftree
that is the same type astypeElement
.protected Set<AnnotationMirror>
Returns the annotations that should be applied to enum constructors.getExplicitNewClassAnnos
(NewClassTree newClassTree) Returns the annotations explicitly written on a NewClassTree.protected List<AnnotatedTypeMirror>
getExplicitNewClassClassTypeArgs
(NewClassTree newClass) Returns the partially-annotated explicit class type arguments of the new class tree.getExpressionAndOffset
(String expression) Given an expression, split it into a subexpression and a constant offset.getFieldInvariantAnnotationTree
(@Nullable List<? extends AnnotationTree> annoTrees) Returns the element ofannoTrees
that is a use of one of the field invariant annotations (as specified viagetFieldInvariantDeclarationAnnotations()
.protected Set<Class<? extends Annotation>>
Returns the set of classes of field invariant annotations.getFieldInvariants
(TypeElement element) Returns the field invariants for the given class, as expressed by the user in@FieldInvariant
method annotations.org.plumelib.util.IPair<AnnotatedTypeMirror,
AnnotatedTypeMirror.AnnotatedExecutableType> getFnInterfaceFromTree
(Tree tree) Returns the functional interface and the function type that this lambda or member references targets.Returns the function type that this lambda targets.Returns the function type that this member reference targets.Return the implicit receiver type of an expression tree.getIterableElementType
(ExpressionTree expression) Return the element type ofexpression
.protected AnnotatedTypeMirror
getIterableElementType
(ExpressionTree expression, AnnotatedTypeMirror iterableType) Return the element type ofiterableType
.Returns the return type of the methodm
.Returns the return type of the methodm
at the return statementr
.getNarrowedAnnotations
(AnnotationMirrorSet annos, TypeKind typeKind, TypeKind narrowedTypeKind) Returns annotations applicable to typenarrowedTypeKind
, that are copied or adapted fromannos
.getNarrowedPrimitive
(AnnotatedTypeMirror.AnnotatedPrimitiveType type, TypeMirror narrowedTypeMirror) Returns AnnotatedPrimitiveType with underlying typenarrowedTypeMirror
and with annotations copied or adapted fromtype
.Gets the path for the givenTree
under the current root by checking from the visitor's current path, and usingTrees.getPath(CompilationUnitTree, Tree)
(which is much slower) only iftree
is not found on the current path.Accessor for the processing environment.final QualifierHierarchy
Returns the type qualifier hierarchy graph to be used by this processor.getQualifierParameterHierarchies
(Element element) Returns the set of top annotations representing all the hierarchies for which this element has a qualifier parameter.getQualifierParameterHierarchies
(AnnotatedTypeMirror annotatedType) Returns the set of top annotations representing all the hierarchies for which this type has a qualifier parameter.ReturnQualifierUpperBounds
for this type factory.final @Nullable AnnotatedTypeMirror
getReceiverType
(ExpressionTree expression) Returns the receiver type of the expression tree, which might be the type of an implicitthis
.getResultingTypeOfConstructorMemberReference
(MemberReferenceTree memberReferenceTree, AnnotatedTypeMirror.AnnotatedExecutableType constructorType) Gets the type of the resulting constructor call of a MemberReferenceTree.getSelfType
(Tree tree) Returns the type ofthis
at the location oftree
.Returns AnnotatedDeclaredType with underlying type String and annotations copied from type.final Set<@CanonicalName String>
Returns an immutable set of the fully qualified names of the type qualifiers supported by this checker.final Set<Class<? extends Annotation>>
Returns an immutable set of the classes corresponding to the type qualifiers supported by this checker.Accessor for the tree utilities.Returns the set of qualifiers that are the upper bounds for a use of the type.final TypeHierarchy
getTypeOfExtendsImplements
(Tree clause) Returns the type of the extends or implements clause.Returns the annotated primitive type of the given declared type if it is a boxed declared type.Returns the path to the tree that an external "visitor" is visiting.Returns the WholeProgramInference instance (may be null).getWidenedAnnotations
(AnnotationMirrorSet annos, TypeKind typeKind, TypeKind widenedTypeKind) Returns annotations applicable to typewidenedTypeKind
, that are copied or adapted fromannos
.final AnnotatedTypeMirror
getWidenedType
(AnnotatedTypeMirror exprType, AnnotatedTypeMirror widenedType) Returns a widened type if applicable, otherwise returns its first argument.final AnnotatedTypeMirror
getWidenedType
(AnnotationMirrorSet exprAnnos, TypeMirror exprTypeMirror, AnnotatedTypeMirror widenedType) Applies widening if applicable, otherwise returns its first argument.boolean
Returns whether theNoQualifierParameter
annotation was explicitly written onelement
for the hierarchy given bytop
.boolean
hasExplicitQualifierParameterInHierarchy
(Element element, AnnotationMirror top) Returns whether theHasQualifierParameter
annotation was explicitly written onelement
for the hierarchy given bytop
.boolean
hasQualifierParameterInHierarchy
(@Nullable Element element, AnnotationMirror top) Whether or not theelement
has a qualifier parameter.boolean
hasQualifierParameterInHierarchy
(AnnotatedTypeMirror annotatedTypeMirror, AnnotationMirror top) Whether or not theannotatedTypeMirror
has a qualifier parameter.void
Initializes all fields oftype
.protected void
Initialize reflection resolution.boolean
isDeterministic
(ExecutableElement methodElement) Returns true if the given method is deterministic according to this AnnotationProvider — that is, if multiple calls to the given method (with the same arguments) return the same value.boolean
isFromByteCode
(Element element) Returns true if the element is from bytecode and the if the element did not appear in a stub file.boolean
isFromStubFile
(Element element) Returns true if the element appears in a stub file (Currently only works for methods, constructors, and fields).boolean
isImmutable
(TypeMirror type) Returns true if the type is immutable.boolean
isSideEffectFree
(ExecutableElement methodElement) Returns true if the given method is side-effect-free according to this AnnotationProvider — that is, if a call to the given method does not undo flow-sensitive type refinement.boolean
Returns true if the given annotation is a part of the type system under which this type factory operates.boolean
isSupportedQualifier
(Class<? extends Annotation> clazz) Returns true if the given class is a part of the type system under which this type factory operates.boolean
isSupportedQualifier
(String className) Returns true if the given class name is a part of the type system under which this type factory operates.final boolean
isTop
(AnnotationMirror qualifier) Returns true if the given qualifer is one of the top annotations for the qualifer hierarchy.protected final boolean
isWithinConstructor
(Tree tree) Returns true iftree
is within a constructor.void
Output a message aboutgetAnnotatedType(javax.lang.model.element.Element)
, if logging is on.protected void
makeConditionConsistentWithOtherMethod
(Map<String, org.plumelib.util.IPair<AnnotatedTypeMirror, AnnotatedTypeMirror>> conditionMap, WholeProgramInferenceJavaParserStorage.CallableDeclarationAnnos otherDeclAnnos, boolean isPrecondition, boolean otherIsSupertype) Performs side effects to makeconditionMap
obey behavioral subtyping constraints withotherDeclAnnos
, that is, postconditions must be at least as strong as the postcondition on the superclass, and preconditions must be at most as strong as the condition on the superclass.protected AnnotatedTypeMirror
mergeAnnotationFileAnnosIntoType
(@Nullable AnnotatedTypeMirror type, Element elt, AnnotationFileElementTypes source) Merges types from annotation files forelt
intotype
by taking the greatest lower bound of the annotations in both.methodFromUse
(ExpressionTree tree, ExecutableElement methodElt, AnnotatedTypeMirror receiverType) Determines the type of the invoked method based on the passed expression tree, executable element, and receiver type.methodFromUse
(ExpressionTree tree, ExecutableElement methodElt, AnnotatedTypeMirror receiverType, boolean inferTypeArgs) Determines the type of the invoked method based on the passed method invocation tree.methodFromUse
(MethodInvocationTree tree, boolean inferTypeArgs) The implementation ofmethodFromUse(MethodInvocationTree)
andmethodFromUseWithoutTypeArgInference(MethodInvocationTree)
.protected void
methodFromUsePreSubstitution
(ExpressionTree tree, AnnotatedTypeMirror.AnnotatedExecutableType type, boolean resolvePolyQuals) A callback method for the AnnotatedTypeFactory subtypes to customize the handling of the declared method type before type variable substitution.methodFromUseWithoutTypeArgInference
(ExpressionTree tree, ExecutableElement methodElt, AnnotatedTypeMirror receiverType) Returns the same asmethodFromUse(ExpressionTree, ExecutableElement, AnnotatedTypeMirror)
, but without inferred type arguments.Returns the same asmethodFromUse(MethodInvocationTree)
, but without inferred type arguments.static String
negateConstant
(String constantExpression) Given an expression string, returns its negation.order
(Collection<AnnotatedTypeMirror.AnnotatedTypeVariable> collection) Returns the list of type variables such that a type variable in the list only references type variables at a lower index than itself.protected void
Parses all annotation files in the following order: jdk.astub in the same directory as the checker, if it exists and ignorejdkastub option is not supplied jdkN.astub (where N is the Java version or any higher value) in the same directory as the checker, if it exists and ignorejdkastub option is not supplied Stub files listed in @StubFiles annotation on the checker; must be in same directory as the checker Stub files provided via-Astubs
compiler option Ajava files provided via-Aajava
compiler optionvoid
postAsMemberOf
(AnnotatedTypeMirror type, AnnotatedTypeMirror owner, Element element) A callback method for the AnnotatedTypeFactory subtypes to customize AnnotatedTypes.asMemberOf().protected void
postDirectSuperTypes
(AnnotatedTypeMirror type, List<? extends AnnotatedTypeMirror> supertypes) A callback method for the AnnotatedTypeFactory subtypes to customize directSupertypes().protected void
postInit()
Actions that logically belong in the constructor, but need to run after the subclass constructor has completed.void
Called byBaseTypeVisitor.visitClass(ClassTree, Void)
after the ClassTree has been type checked.void
preProcessClassTree
(ClassTree classTree) Called byBaseTypeVisitor.visitClass(ClassTree, Void)
before the classTree is type checked.void
Replaces or adds all annotations fromfrom
toto
.void
replaceAnnotations
(AnnotatedTypeMirror from, AnnotatedTypeMirror to, AnnotationMirror top) Replaces or adds annotations intop
's hierarchy fromfrom
toto
.final void
setEnclosingElementForArtificialTree
(Tree tree, Element enclosing) Adds the given mapping from a synthetic (generated) tree to its enclosing element.void
Set the CompilationUnitTree that should be used.void
setVisitorTreePath
(@Nullable TreePath visitorTreePath) Sets the path to the tree that an external "visitor" is visiting.boolean
Returns true if redundancy between a stub file and bytecode should be reported.protected final AnnotatedTypeMirror
toAnnotatedType
(TypeMirror t, boolean declaration) A convenience method that converts aTypeMirror
to an emptyAnnotatedTypeMirror
usingAnnotatedTypeMirror.createType(javax.lang.model.type.TypeMirror, org.checkerframework.framework.type.AnnotatedTypeFactory, boolean)
.toString()
protected final AnnotatedTypeMirror
Determines an empty annotated type of the given tree.Adapt the upper bounds of the type variables of a class relative to the type instantiation.void
wpiAdjustForUpdateField
(Tree lhsTree, Element element, String fieldName, AnnotatedTypeMirror rhsATM) Changes the type ofrhsATM
when being assigned to a field, for use by whole-program inference.void
Changes the type ofrhsATM
when being assigned to anything other than a field, for use by whole-program inference.void
wpiPrepareMethodForWriting
(org.checkerframework.afu.scenelib.el.AMethod methodAnnos) Side-effects the method or constructor annotations to make any desired changes before writing to an annotation file.void
wpiPrepareMethodForWriting
(WholeProgramInferenceJavaParserStorage.CallableDeclarationAnnos methodAnnos, Collection<WholeProgramInferenceJavaParserStorage.CallableDeclarationAnnos> inSupertypes, Collection<WholeProgramInferenceJavaParserStorage.CallableDeclarationAnnos> inSubtypes) Side-effects the method or constructor annotations to make any desired changes before writing to an ajava file.boolean
Returns whether whole-program inference should infer types for receiver expressions.
-
Field Details
-
trees
TheTrees
instance to use for tree node path finding. -
root
Optional! The AST of the source file being operated on. -
processingEnv
The processing environment to use for accessing compiler internals. -
elements
Utility class for working withElement
s. -
types
Utility class for working withTypeMirror
s. -
annotatedForValueElement
The AnnotatedFor.value argument/element. -
ensuresQualifierExpressionElement
The EnsuresQualifier.expression field/element. -
ensuresQualifierListValueElement
The EnsuresQualifier.List.value field/element. -
ensuresQualifierIfExpressionElement
The EnsuresQualifierIf.expression field/element. -
ensuresQualifierIfResultElement
The EnsuresQualifierIf.result argument/element. -
ensuresQualifierIfListValueElement
The EnsuresQualifierIf.List.value field/element. -
fieldInvariantFieldElement
The FieldInvariant.field argument/element. -
fieldInvariantQualifierElement
The FieldInvariant.qualifier argument/element. -
hasQualifierParameterValueElement
The HasQualifierParameter.value field/element. -
methodValClassNameElement
The MethodVal.className argument/element. -
methodValMethodNameElement
The MethodVal.methodName argument/element. -
methodValParamsElement
The MethodVal.params argument/element. -
noQualifierParameterValueElement
The NoQualifierParameter.value field/element. -
requiresQualifierExpressionElement
The RequiresQualifier.expression field/element. -
requiresQualifierListValueElement
The RequiresQualifier.List.value field/element. -
requiresQualifierTM
The RequiresQualifier type. -
requiresQualifierListTM
The RequiresQualifier.List type. -
ensuresQualifierTM
The EnsuresQualifier type. -
ensuresQualifierListTM
The EnsuresQualifier.List type. -
ensuresQualifierIfTM
The EnsuresQualifierIf type. -
ensuresQualifierIfListTM
The EnsuresQualifierIf.List type. -
qualHierarchy
Represent the annotation relations. -
typeHierarchy
Represent the type relations. -
typeFormatter
This formatter is used for converting AnnotatedTypeMirrors to Strings. This formatter will be used by all AnnotatedTypeMirrors created by this factory in their toString methods. -
qualifierUpperBounds
Holds the qualifier upper bounds for type uses. -
typeVarSubstitutor
Provides utility method to substitute arguments for their type variables. Field should be final, but can only be set in postInit, because subtypes might need other state to be initialized first. -
typeArgumentInference
Provides utility method to infer type arguments. -
stubTypes
Parses stub files and stores annotations on public elements from stub files. -
ajavaTypes
Parses ajava files and stores annotations on public elements from ajava files. -
currentFileAjavaTypes
If type checking a Java file, stores annotations read from an ajava file for that class if one exists. UnlikeajavaTypes
, which only stores annotations on public elements, this stores annotations on all element locations such as in anonymous class bodies. -
checker
The checker to use for option handling and resource management. -
uid
public final int uidUnique ID of the current object; for debugging purposes. -
reflectionResolver
Object that is used to resolve reflective method calls, if reflection resolution is turned on. -
loader
This loads type annotation classes via reflective lookup. -
wpiOutputFormat
Which whole-program inference output format to use, if doing whole-program inference. This variable would be final, but it is not set unless WPI is enabled. -
shouldCache
public boolean shouldCacheShould results be cached? This means that ATM.deepCopy() will be called. ATM.deepCopy() used to (and perhaps still does) side effect the ATM being copied. So setting this to false is not equivalent to setting shouldReadCache to false. -
fromExpressionTreeCache
Mapping from an expression tree to its annotated type; before defaults are applied, just what the programmer wrote. -
fromMemberTreeCache
Mapping from a member tree to its annotated type; before defaults are applied, just what the programmer wrote. -
fromTypeTreeCache
Mapping from a type tree to its annotated type; before defaults are applied, just what the programmer wrote. -
artificialTreeToEnclosingElementMap
Mapping from CFG-generated trees to their enclosing elements. -
ignoreRawTypeArguments
public final boolean ignoreRawTypeArgumentsWhether to ignore type arguments from raw types. -
objectGetClass
The Object.getClass method. -
capturedTypeVarSubstitutor
Substitutes references to captured type variables.Unlike
typeVarSubstitutor
, this class does not copy the type. Callsubstitute
to use.
-
-
Constructor Details
-
AnnotatedTypeFactory
Constructs a factory from the given checker.A subclass must call postInit at the end of its constructor. postInit must be the last call in the constructor or else types from stub files may not be created as expected.
- Parameters:
checker
- theSourceChecker
to which this factory belongs
-
-
Method Details
-
initializeAtm
Initializes all fields oftype
.- Parameters:
type
- annotated type mirror
-
checkInvalidOptionsInferSignatures
protected void checkInvalidOptionsInferSignatures()This method is called only when-Ainfer
is passed as an option. It checks if another option that should not occur simultaneously with the whole-program inference is also passed as argument, and aborts the process if that is the case. For example, the whole-program inference process was not designed to work with conservative defaults.Subclasses may override this method to add more options.
-
postInit
Actions that logically belong in the constructor, but need to run after the subclass constructor has completed. In particular,AnnotationFileElementTypes.parseStubFiles()
may try to do type resolution with this AnnotatedTypeFactory. -
getChecker
Returns the checker associated with this factory.- Returns:
- the checker associated with this factory
-
getCheckerNames
Returns the names of the annotation processors that are being run.- Returns:
- the names of the annotation processors that are being run
-
createQualifierUpperBounds
CreatesQualifierUpperBounds
for this type factory.- Returns:
- a new
QualifierUpperBounds
for this type factory
-
getQualifierUpperBounds
ReturnQualifierUpperBounds
for this type factory.- Returns:
QualifierUpperBounds
for this type factory
-
getWholeProgramInference
Returns the WholeProgramInference instance (may be null).- Returns:
- the WholeProgramInference instance, or null
-
initializeReflectionResolution
protected void initializeReflectionResolution()Initialize reflection resolution. -
setRoot
Set the CompilationUnitTree that should be used.- Parameters:
root
- the new compilation unit to use
-
toString
-
createQualifierHierarchy
Returns theQualifierHierarchy
to be used by this checker.The implementation builds the type qualifier hierarchy for the
getSupportedTypeQualifiers()
using the meta-annotations found in them. The current implementation returns an instance ofNoElementQualifierHierarchy
.Subclasses must override this method if their qualifiers have elements; the method must return an implementation of
QualifierHierarchy
, such asElementQualifierHierarchy
.- Returns:
- a QualifierHierarchy for this type system
-
getQualifierHierarchy
Returns the type qualifier hierarchy graph to be used by this processor.- Returns:
- the
QualifierHierarchy
for this checker - See Also:
-
isTop
Returns true if the given qualifer is one of the top annotations for the qualifer hierarchy.- Parameters:
qualifier
- a type qualifier- Returns:
- true if the given qualifer is one of the top annotations for the qualifer hierarchy
-
createTypeHierarchy
Creates the type hierarchy to be used by this factory.Subclasses may override this method to specify new type-checking rules beyond the typical Java subtyping rules.
- Returns:
- the type relations class to check type subtyping
-
getTypeHierarchy
-
createTypeVariableSubstitutor
TypeVariableSubstitutor provides a method to replace type parameters with their arguments. -
getTypeVarSubstitutor
-
createTypeArgumentInference
Creates the object that infers type arguments.- Returns:
- the object that infers type arguments
-
getTypeArgumentInference
-
createAnnotationClassLoader
Factory method to easily change whatAnnotationClassLoader
is created to load type annotation classes. Subclasses can override this method and return a custom AnnotationClassLoader subclass to customize loading logic. -
createSupportedTypeQualifiers
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
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 ofElementType.TYPE_PARAMETER
, but no otherElementType
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:
- Only support annotations located in a checker's qual directory:
This is the default behavior. Simply place those annotations within the qual directory.
- Support annotations located in a checker's qual directory and a list of other
annotations:
Place those annotations within the qual directory, and override
createSupportedTypeQualifiers()
by callinggetBundledTypeQualifiers(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); }
- Supporting only annotations that are explicitly listed: Override
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)); }
createSupportedTypeQualifiers()
must be a fresh, mutable set. The methodsgetBundledTypeQualifiers(Class...)
must return a fresh, mutable set
- Returns:
- the type qualifiers supported this processor, or an empty set if none
- Only support annotations located in a checker's qual directory:
-
getBundledTypeQualifiers
@SafeVarargs protected final Set<Class<? extends Annotation>> getBundledTypeQualifiers(Class<? extends Annotation>... explicitlyListedAnnotations) Loads all annotations contained in the qual directory of a checker via reflection; if a polymorphic type qualifier exists, and an explicit array of annotations to the set of annotation classes.This method can be called in the overridden versions of
createSupportedTypeQualifiers()
in each checker.- Parameters:
explicitlyListedAnnotations
- a varargs array of explicitly listed annotation classes to be added to the returned set. For example, it is used frequently to add Bottom qualifiers.- Returns:
- a mutable set of the loaded and listed annotation classes
-
createAnnotatedTypeFormatter
Creates the AnnotatedTypeFormatter used by this type factory and all AnnotatedTypeMirrors it creates. The AnnotatedTypeFormatter is used in AnnotatedTypeMirror.toString and will affect the error messages printed for checkers that use this type factory.- Returns:
- the AnnotatedTypeFormatter to pass to all instantiated AnnotatedTypeMirrors
-
getAnnotatedTypeFormatter
-
createAnnotationFormatter
-
getAnnotationFormatter
-
getSupportedTypeQualifiers
Returns an immutable set of the classes corresponding to the type qualifiers supported by this checker.Subclasses cannot override this method; they should override
createSupportedTypeQualifiers
instead.- Returns:
- an immutable set of the supported type qualifiers, or an empty set if no qualifiers are supported
- See Also:
-
getSupportedTypeQualifierNames
Returns an immutable set of the fully qualified names of the type qualifiers supported by this checker.Subclasses cannot override this method; they should override
createSupportedTypeQualifiers
instead.- Returns:
- an immutable set of the supported type qualifiers, or an empty set if no qualifiers are supported
- See Also:
-
getCacheSize
protected int getCacheSize()Returns the size for LRU caches. It is either the value supplied via the-AatfCacheSize
option or the default cache size.- Returns:
- cache size passed as argument to checker or DEFAULT_CACHE_SIZE
-
getAnnotatedType
Returns an AnnotatedTypeMirror representing the annotated type ofelt
.- Parameters:
elt
- the element- Returns:
- the annotated type of
elt
-
getAnnotatedType
Returns an AnnotatedTypeMirror representing the annotated type ofclazz
.- Parameters:
clazz
- a class- Returns:
- the annotated type of
clazz
-
getAnnotationMirror
public @Nullable AnnotationMirror getAnnotationMirror(Tree tree, Class<? extends Annotation> target) Description copied from interface:AnnotationProvider
Return the annotation ontree
that is in the hierarchy that contains the qualifiertarget
. Returns null if none exists.- Specified by:
getAnnotationMirror
in interfaceAnnotationProvider
- Parameters:
tree
- the tree of which the annotation is returnedtarget
- the class of the annotation- Returns:
- the annotation on
tree
that has the classtarget
, or null
-
getAnnotatedType
Returns an AnnotatedTypeMirror representing the annotated type oftree
.- Parameters:
tree
- the AST node- Returns:
- the annotated type of
tree
-
preProcessClassTree
Called byBaseTypeVisitor.visitClass(ClassTree, Void)
before the classTree is type checked.- Parameters:
classTree
- the class on which to perform preprocessing
-
postProcessClassTree
Called byBaseTypeVisitor.visitClass(ClassTree, Void)
after the ClassTree has been type checked.The default implementation uses this to store the defaulted AnnotatedTypeMirrors and inherited declaration annotations back into the corresponding Elements. Subclasses might want to override this method if storing defaulted types is not desirable.
-
getAnnotatedTypeFromTypeTree
Determines the annotated type from a type in tree form.Note that we cannot decide from a Tree whether it is a type use or an expression. TreeUtils.isTypeTree is only an under-approximation. For example, an identifier can be either a type or an expression.
- Parameters:
tree
- the type tree- Returns:
- the annotated type of the type in the AST
-
getTypeDeclarationBounds
Returns the set of qualifiers that are the upper bounds for a use of the type.- Parameters:
type
- a type whose upper bounds to obtain- Returns:
- the set of qualifiers that are the upper bounds for a use of the type
-
getDefaultTypeDeclarationBounds
Returns the set of qualifiers that are the upper bound for a type use if no other bound is specified for the type.This implementation returns the top qualifiers by default. Subclass may override to return different qualifiers.
- Returns:
- the set of qualifiers that are the upper bound for a type use if no other bound is specified for the type
-
getTypeOfExtendsImplements
Returns the type of the extends or implements clause.The primary qualifier is either an explicit annotation on
clause
, or it is the qualifier upper bounds for uses of the type of the clause.- Parameters:
clause
- tree that represents an extends or implements clause- Returns:
- the type of the extends or implements clause
-
fromElement
Creates an AnnotatedTypeMirror forelt
that includes: annotations explicitly written on the element and annotations from stub files.Does not include default qualifiers. To obtain them, use
getAnnotatedType(Element)
.Does not include fake overrides from the stub file.
- Parameters:
elt
- the element- Returns:
- AnnotatedTypeMirror of the element with explicitly-written and stub file annotations
-
mergeAnnotationFileAnnosIntoType
protected AnnotatedTypeMirror mergeAnnotationFileAnnosIntoType(@Nullable AnnotatedTypeMirror type, Element elt, AnnotationFileElementTypes source) Merges types from annotation files forelt
intotype
by taking the greatest lower bound of the annotations in both.- Parameters:
type
- the type to apply annotation file types toelt
- the element from which to read annotation file typessource
- storage for current annotation file annotations- Returns:
- the type, side-effected to add the annotation file types
-
addComputedTypeAnnotations
Changes annotations on a type obtained from aTree
. By default, this method does nothing. GenericAnnotatedTypeFactory uses this method to implement defaulting and inference (flow-sensitive type refinement). Its subclasses usually override it only to customize default annotations.Subclasses that override this method should also override
addComputedTypeAnnotations(Element, AnnotatedTypeMirror)
.In classes that extend
GenericAnnotatedTypeFactory
, overrideGenericAnnotatedTypeFactory.addComputedTypeAnnotations(Tree, AnnotatedTypeMirror, boolean)
instead of this method.- Parameters:
tree
- an AST nodetype
- the type obtained fromtree
-
addComputedTypeAnnotations
Changes annotations on a type obtained from anElement
. By default, this method does nothing. GenericAnnotatedTypeFactory uses this method to implement defaulting.Subclasses that override this method should also override
addComputedTypeAnnotations(Tree, AnnotatedTypeMirror)
.- Parameters:
elt
- an elementtype
- the type obtained fromelt
-
addDefaultAnnotations
Adds default annotations totype
. This method should only be used in places where the correct annotations cannot be computed because of type argument of raw types. (SeeAnnotatedTypeMirror.AnnotatedWildcardType.isTypeArgOfRawType()
.)- Parameters:
type
- annotated type to which default annotations are added
-
postDirectSuperTypes
protected void postDirectSuperTypes(AnnotatedTypeMirror type, List<? extends AnnotatedTypeMirror> supertypes) A callback method for the AnnotatedTypeFactory subtypes to customize directSupertypes(). Overriding methods should merely change the annotations on the supertypes, without adding or removing new types.The default provided implementation adds
type
annotations tosupertypes
. This allows thetype
and its supertypes to have the qualifiers.- Parameters:
type
- the type whose supertypes are desiredsupertypes
- the supertypes as specified by the base AnnotatedTypeFactory
-
postAsMemberOf
A callback method for the AnnotatedTypeFactory subtypes to customize AnnotatedTypes.asMemberOf(). Overriding methods should merely change the annotations on the subtypes, without changing the types.- Parameters:
type
- the annotated type of the elementowner
- the annotated type of the receiver of the accessing treeelement
- the element of the field or method
-
addAnnotationFromFieldInvariant
protected void addAnnotationFromFieldInvariant(AnnotatedTypeMirror type, AnnotatedTypeMirror accessedVia, VariableElement field) Adds the qualifier specified by a field invariant forfield
totype
.- Parameters:
type
- annotated type to which the annotation is addedaccessedVia
- the annotated type of the receiver of the accessing tree. (Only used to get the type element of the underling type.)field
- element representing the field
-
getFieldInvariants
Returns the field invariants for the given class, as expressed by the user in@FieldInvariant
method annotations.Subclasses may implement their own field invariant annotations if
@FieldInvariant
is not expressive enough. They must override this method to properly create AnnotationMirror and also overridegetFieldInvariantDeclarationAnnotations()
to return their field invariants.- Parameters:
element
- class for which to get invariants- Returns:
- field invariants for
element
-
getFieldInvariantAnnotationTree
public @Nullable AnnotationTree getFieldInvariantAnnotationTree(@Nullable List<? extends AnnotationTree> annoTrees) Returns the element ofannoTrees
that is a use of one of the field invariant annotations (as specified viagetFieldInvariantDeclarationAnnotations()
. If one isn't found, null is returned.- Parameters:
annoTrees
- list of trees to search; the result is one of the list elements, or null- Returns:
- the AnnotationTree that is a use of one of the field invariant annotations, or null if one isn't found
-
getFieldInvariantDeclarationAnnotations
Returns the set of classes of field invariant annotations.- Returns:
- the set of classes of field invariant annotations
-
typeVariablesFromUse
public List<AnnotatedTypeParameterBounds> typeVariablesFromUse(AnnotatedTypeMirror.AnnotatedDeclaredType type, TypeElement element) Adapt the upper bounds of the type variables of a class relative to the type instantiation. In some type systems, the upper bounds depend on the instantiation of the class. For example, in the Generic Universe Type system, consider a class declaration
then the instantiationclass C<X extends @Peer Object>
is legal. The upper bounds of class C have to be adapted by the main modifier.@Rep C<@Rep Object>
An example of an adaptation follows. Suppose, I have a declaration:
And an instantiation:class MyClass<E extends List<E>>
new MyClass<@NonNull String>()
The upper bound of E adapted to the argument String, would be
List<@NonNull String>
and the lower bound would be an AnnotatedNullType.TODO: ensure that this method is consistently used instead of directly querying the type variables.
- Parameters:
type
- the use of the typeelement
- the corresponding element- Returns:
- the adapted bounds of the type parameters
-
getAnnotatedNullType
public AnnotatedTypeMirror.AnnotatedNullType getAnnotatedNullType(Set<? extends AnnotationMirror> annotations) Creates and returns an AnnotatedNullType qualified withannotations
.- Parameters:
annotations
- the set of AnnotationMirrors to qualify the returned type with- Returns:
- AnnotatedNullType qualified with
annotations
-
getImplicitReceiverType
protected @Nullable AnnotatedTypeMirror.AnnotatedDeclaredType getImplicitReceiverType(ExpressionTree tree) Return the implicit receiver type of an expression tree.The result is null for expressions that don't have a receiver, e.g. for a local variable or method parameter access. The result is also null for expressions that have an explicit receiver.
Clients should generally call
getReceiverType(com.sun.source.tree.ExpressionTree)
.- Parameters:
tree
- the expression that might have an implicit receiver- Returns:
- the type of the implicit receiver. Returns null if the expression has an explicit receiver or doesn't have a receiver.
-
getSelfType
Returns the type ofthis
at the location oftree
. Returnsnull
iftree
is in a location wherethis
has no meaning, such as the body of a static method.The parameter is an arbitrary tree and does not have to mention "this", neither explicitly nor implicitly. This method can be overridden for type-system specific behavior.
- Parameters:
tree
- location used to decide the type ofthis
- Returns:
- the type of
this
at the location oftree
-
getEnclosingClassOrMethod
Returns the innermost enclosing method or class tree oftree
. Iftree
is artificial (that is, created by dataflow), thenartificialTreeToEnclosingElementMap
is used to find the enclosing tree.If the tree is inside an annotation, then
null
is returned.- Parameters:
tree
- tree to whose innermost enclosing method or class to return- Returns:
- the innermost enclosing method or class tree of
tree
, ornull
iftree
is inside an annotation
-
getEnclosingType
public AnnotatedTypeMirror.AnnotatedDeclaredType getEnclosingType(TypeElement typeElement, Tree tree) Returns theAnnotatedTypeMirror
of the enclosing type at the location oftree
that is the same type astypeElement
.- Parameters:
typeElement
- type of the enclosing type to returntree
- location to use- Returns:
- the enclosing type at the location of
tree
that is the same type astypeElement
-
getEnclosingSubType
public AnnotatedTypeMirror.AnnotatedDeclaredType getEnclosingSubType(TypeElement typeElement, Tree tree) Returns theAnnotatedTypeMirror
of the enclosing type at the location oftree
that is a subtype oftypeElement
.- Parameters:
typeElement
- super type of the enclosing type to returntree
- location to use- Returns:
- the enclosing type at the location of
tree
that is a subtype oftypeElement
-
getReceiverType
Returns the receiver type of the expression tree, which might be the type of an implicitthis
. Returns null if the expression has no explicit or implicit receiver.- Parameters:
expression
- the expression for which to determine the receiver type- Returns:
- the type of the receiver of expression
-
methodFromUse
public final AnnotatedTypeFactory.ParameterizedExecutableType methodFromUse(MethodInvocationTree tree) Determines the type of the invoked method based on the passed method invocation tree.The returned method type has all type variables resolved, whether based on receiver type, passed type parameters if any, and method invocation parameter.
Subclasses may override this method to customize inference of types or qualifiers based on method invocation parameters.
As an implementation detail, this method depends on
AnnotatedTypes.asMemberOf(Types, AnnotatedTypeFactory, AnnotatedTypeMirror, Element)
, and customization based on receiver type should be in accordance to its specification.The return type is a pair of the type of the invoked method and the (inferred) type arguments. Note that neither the explicitly passed nor the inferred type arguments are guaranteed to be subtypes of the corresponding upper bounds. See method
BaseTypeVisitor.checkTypeArguments(com.sun.source.tree.Tree, java.util.List<? extends org.checkerframework.framework.type.AnnotatedTypeParameterBounds>, java.util.List<? extends org.checkerframework.framework.type.AnnotatedTypeMirror>, java.util.List<? extends com.sun.source.tree.Tree>, java.lang.CharSequence, java.util.List<?>)
for the checks of type argument well-formedness.Note that "this" and "super" constructor invocations are also handled by this method (explicit or implicit ones, at the beginning of a constructor). Method
constructorFromUse(NewClassTree)
is only used for a constructor invocation in a "new" expression.- Parameters:
tree
- the method invocation tree- Returns:
- the type of the invoked method and any (explict or inferred) type arguments
-
methodFromUseWithoutTypeArgInference
public AnnotatedTypeFactory.ParameterizedExecutableType methodFromUseWithoutTypeArgInference(MethodInvocationTree tree) Returns the same asmethodFromUse(MethodInvocationTree)
, but without inferred type arguments.- Parameters:
tree
- a method invocation tree- Returns:
- the type of the invoked method and any explicit type arguments
-
methodFromUse
protected AnnotatedTypeFactory.ParameterizedExecutableType methodFromUse(MethodInvocationTree tree, boolean inferTypeArgs) The implementation ofmethodFromUse(MethodInvocationTree)
andmethodFromUseWithoutTypeArgInference(MethodInvocationTree)
.- Parameters:
tree
- a method invocation treeinferTypeArgs
- whether type arguments should be inferred- Returns:
- the type of the invoked method, any explicit type arguments, and if
inferTypeArgs
is true, any inferred type arguments
-
methodFromUse
public final AnnotatedTypeFactory.ParameterizedExecutableType methodFromUse(ExpressionTree tree, ExecutableElement methodElt, AnnotatedTypeMirror receiverType) Determines the type of the invoked method based on the passed expression tree, executable element, and receiver type.- Parameters:
tree
- either a MethodInvocationTree or a MemberReferenceTreemethodElt
- the element of the referenced methodreceiverType
- the type of the receiver- Returns:
- the type of the method being invoked with tree and the (inferred) type arguments
- See Also:
-
methodFromUseWithoutTypeArgInference
public final AnnotatedTypeFactory.ParameterizedExecutableType methodFromUseWithoutTypeArgInference(ExpressionTree tree, ExecutableElement methodElt, AnnotatedTypeMirror receiverType) Returns the same asmethodFromUse(ExpressionTree, ExecutableElement, AnnotatedTypeMirror)
, but without inferred type arguments.- Parameters:
tree
- either a MethodInvocationTree or a MemberReferenceTreemethodElt
- the element of the referenced methodreceiverType
- the type of the receiver- Returns:
- the type of the method being invoked with tree without inferring type arguments
-
methodFromUse
protected AnnotatedTypeFactory.ParameterizedExecutableType methodFromUse(ExpressionTree tree, ExecutableElement methodElt, AnnotatedTypeMirror receiverType, boolean inferTypeArgs) The implementation ofmethodFromUse(ExpressionTree, ExecutableElement, AnnotatedTypeMirror)
andmethodFromUseWithoutTypeArgInference(ExpressionTree, ExecutableElement, AnnotatedTypeMirror)
.- Parameters:
tree
- either a MethodInvocationTree or a MemberReferenceTreemethodElt
- the element of the referenced methodreceiverType
- the type of the receiverinferTypeArgs
- whether type arguments should be inferred- Returns:
- the type of the invoked method
-
methodFromUsePreSubstitution
protected void methodFromUsePreSubstitution(ExpressionTree tree, AnnotatedTypeMirror.AnnotatedExecutableType type, boolean resolvePolyQuals) A callback method for the AnnotatedTypeFactory subtypes to customize the handling of the declared method type before type variable substitution.- Parameters:
tree
- either a method invocation or a member reference treetype
- declared method type before type variable substitutionresolvePolyQuals
- whether to resolve polymorphic qualifiers
-
adaptGetClassReturnTypeToReceiver
protected void adaptGetClassReturnTypeToReceiver(AnnotatedTypeMirror.AnnotatedExecutableType getClassType, AnnotatedTypeMirror receiverType, ExpressionTree tree) Java special-cases the return type ofgetClass()
. Though the method has a return type ofClass<?>
, the compiler special cases this return-type and changes the bound of the type argument to the erasure of the receiver type. For example:x.getClass()
has the typeClass< ? extends erasure_of_x >
someInteger.getClass()
has the typeClass< ? extends Integer >
- Parameters:
getClassType
- this must be a type representing a call to Object.getClass otherwise a runtime exception will be thrown. It is modified by side effect.receiverType
- the receiver type of the method invocation (not the declared receiver type)tree
- getClass method invocation tree
-
getIterableElementType
Return the element type ofexpression
. This is usually the type ofexpression.itertor().next()
. Ifexpression
is an array, it is the component type of the array.- Parameters:
expression
- an expression whose type is an array or implementsIterable
- Returns:
- the type of
expression.itertor().next()
or ifexpression
is an array, the component type of the array.
-
getIterableElementType
protected AnnotatedTypeMirror getIterableElementType(ExpressionTree expression, AnnotatedTypeMirror iterableType) Return the element type ofiterableType
. This is usually the type ofexpression.itertor().next()
. Ifexpression
is an array, it is the component type of the array.- Parameters:
expression
- an expression whose type is an array or implementsIterable
iterableType
- the type of the expression- Returns:
- the type of
expression.itertor().next()
or ifexpression
is an array, the component type of the array.
-
constructorFromUse
Determines the type of the invoked constructor based on the passed new class tree.The returned method type has all type variables resolved, whether based on receiver type, passed type parameters if any, and constructor invocation parameter.
Subclasses may override this method to customize inference of types or qualifiers based on constructor invocation parameters.
As an implementation detail, this method depends on
AnnotatedTypes.asMemberOf(Types, AnnotatedTypeFactory, AnnotatedTypeMirror, Element)
, and customization based on receiver type should be in accordance with its specification.The return type is a pair of the type of the invoked constructor and the (inferred) type arguments. Note that neither the explicitly passed nor the inferred type arguments are guaranteed to be subtypes of the corresponding upper bounds. See method
BaseTypeVisitor.checkTypeArguments(com.sun.source.tree.Tree, java.util.List<? extends org.checkerframework.framework.type.AnnotatedTypeParameterBounds>, java.util.List<? extends org.checkerframework.framework.type.AnnotatedTypeMirror>, java.util.List<? extends com.sun.source.tree.Tree>, java.lang.CharSequence, java.util.List<?>)
for the checks of type argument well-formedness.Note that "this" and "super" constructor invocations are handled by method
methodFromUse(com.sun.source.tree.MethodInvocationTree)
. This method only handles constructor invocations in a "new" expression.- Parameters:
tree
- the constructor invocation tree- Returns:
- the annotated type of the invoked constructor (as an executable type) and the (inferred) type arguments
-
constructorFromUseWithoutTypeArgInference
public AnnotatedTypeFactory.ParameterizedExecutableType constructorFromUseWithoutTypeArgInference(NewClassTree tree) The same asconstructorFromUse(NewClassTree)
, but no type arguments are inferred.- Parameters:
tree
- the constructor invocation tree- Returns:
- the annotated type of the invoked constructor (as an executable type) and the explicit type arguments
-
getResultingTypeOfConstructorMemberReference
public AnnotatedTypeMirror getResultingTypeOfConstructorMemberReference(MemberReferenceTree memberReferenceTree, AnnotatedTypeMirror.AnnotatedExecutableType constructorType) Gets the type of the resulting constructor call of a MemberReferenceTree.- Parameters:
memberReferenceTree
- MemberReferenceTree where the member is a constructorconstructorType
- AnnotatedExecutableType of the declaration of the constructor- Returns:
- AnnotatedTypeMirror of the resulting type of the constructor
-
constructorFromUse
protected AnnotatedTypeFactory.ParameterizedExecutableType constructorFromUse(NewClassTree tree, boolean inferTypeArgs) The implementation ofconstructorFromUse(NewClassTree)
andconstructorFromUseWithoutTypeArgInference(NewClassTree)
.- Parameters:
tree
- the constructor invocation treeinferTypeArgs
- whether the type arguments should be inferred- Returns:
- the annotated type of the invoked constructor (as an executable type) and the type arguments
-
getEnumConstructorQualifiers
Returns the annotations that should be applied to enum constructors. This implementation returns an empty set. Subclasses can override to return a different set.- Returns:
- the annotations that should be applied to enum constructors
-
getExplicitNewClassAnnos
Returns the annotations explicitly written on a NewClassTree.new @HERE Class()
- Parameters:
newClassTree
- a constructor invocation- Returns:
- the annotations explicitly written on a NewClassTree
-
getExplicitNewClassClassTypeArgs
Returns the partially-annotated explicit class type arguments of the new class tree. TheAnnotatedTypeMirror
only include the annotations explicitly written on the explict type arguments. (IfnewClass
use a diamond operator, this method returns the empty list.) For example, when called withnew MyClass<@HERE String>()
this method would return a list containing@HERE String
.- Parameters:
newClass
- a new class tree- Returns:
- the partially annotated
AnnotatedTypeMirror
s for the (explicit) class type arguments of the new class tree
-
constructorFromUsePreSubstitution
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.- Parameters:
tree
- a NewClassTree from constructorFromUse()type
- declared method type before type variable substitutionresolvePolyQuals
- whether to resolve polymorphic qualifiers
-
getMethodReturnType
Returns the return type of the methodm
.- Parameters:
m
- tree of a method declaration- Returns:
- the return type of the method
-
getMethodReturnType
Returns the return type of the methodm
at the return statementr
. This implementation just callsgetMethodReturnType(MethodTree)
, but subclasses may override this method to change the type based on the return statement.- Parameters:
m
- tree of a method declarationr
- a return statement within methodm
- Returns:
- the return type of the method
m
at the return statementr
-
getBoxedType
public AnnotatedTypeMirror.AnnotatedDeclaredType getBoxedType(AnnotatedTypeMirror.AnnotatedPrimitiveType type) Returns the annotated boxed type of the given primitive type. The returned type would only have the annotations on the given type.Subclasses may override this method safely to override this behavior.
- Parameters:
type
- the primitive type- Returns:
- the boxed declared type of the passed primitive type
-
applyUnboxing
Return a primitive type: either the argument, or the result of unboxing it (which might affect its annotations).Subclasses should override
getUnboxedType(org.checkerframework.framework.type.AnnotatedTypeMirror.AnnotatedDeclaredType)
rather than this method.- Parameters:
type
- a type: a primitive or boxed primitive- Returns:
- the unboxed variant of the type
-
getUnboxedType
public AnnotatedTypeMirror.AnnotatedPrimitiveType getUnboxedType(AnnotatedTypeMirror.AnnotatedDeclaredType type) throws IllegalArgumentException Returns the annotated primitive type of the given declared type if it is a boxed declared type. Otherwise, it throws IllegalArgumentException exception.In the
AnnotatedTypeFactory
implementation, the returned type has the same primary annotations as the given type. Subclasses may override this behavior.- Parameters:
type
- the declared type- Returns:
- the unboxed primitive type
- Throws:
IllegalArgumentException
- if the type given has no unbox conversion
-
getStringType
Returns AnnotatedDeclaredType with underlying type String and annotations copied from type. Subclasses may change the annotations.- Parameters:
type
- type to convert to String- Returns:
- AnnotatedTypeMirror that results from converting type to a String type
-
getWidenedType
public final AnnotatedTypeMirror getWidenedType(AnnotatedTypeMirror exprType, AnnotatedTypeMirror widenedType) Returns a widened type if applicable, otherwise returns its first argument.Subclasses should override
getWidenedAnnotations(org.checkerframework.javacutil.AnnotationMirrorSet, javax.lang.model.type.TypeKind, javax.lang.model.type.TypeKind)
rather than this method.- Parameters:
exprType
- type to possibly widenwidenedType
- type to possibly widen to; its annotations are ignored- Returns:
- if widening is applicable, the result of converting
type
to the underlying type ofwidenedType
; otherwisetype
-
getWidenedType
public final AnnotatedTypeMirror getWidenedType(AnnotationMirrorSet exprAnnos, TypeMirror exprTypeMirror, AnnotatedTypeMirror widenedType) Applies widening if applicable, otherwise returns its first argument.Subclasses should override
getWidenedAnnotations(org.checkerframework.javacutil.AnnotationMirrorSet, javax.lang.model.type.TypeKind, javax.lang.model.type.TypeKind)
rather than this method.- Parameters:
exprAnnos
- annotations to possibly widenexprTypeMirror
- type to possibly widenwidenedType
- type to possibly widen to; its annotations are ignored- Returns:
- if widening is applicable, the result of converting
type
to the underlying type ofwidenedType
; otherwisetype
-
getNarrowedAnnotations
public AnnotationMirrorSet getNarrowedAnnotations(AnnotationMirrorSet annos, TypeKind typeKind, TypeKind narrowedTypeKind) Returns annotations applicable to typenarrowedTypeKind
, that are copied or adapted fromannos
.- Parameters:
annos
- annotations to narrow, from a primitive or boxed primitivetypeKind
- primitive type to narrownarrowedTypeKind
- target for the returned annotations; a primitive type that is narrower thantypeKind
(in the sense of JLS 5.1.3).- Returns:
- result of converting
annos
fromtypeKind
tonarrowedTypeKind
-
getWidenedAnnotations
public AnnotationMirrorSet getWidenedAnnotations(AnnotationMirrorSet annos, TypeKind typeKind, TypeKind widenedTypeKind) Returns annotations applicable to typewidenedTypeKind
, that are copied or adapted fromannos
.- Parameters:
annos
- annotations to widen, from a primitive or boxed primitivetypeKind
- primitive type to widenwidenedTypeKind
- target for the returned annotations; a primitive type that is wider thantypeKind
(in the sense of JLS 5.1.2)- Returns:
- result of converting
annos
fromtypeKind
towidenedTypeKind
-
binaryTreeArgTypes
public org.plumelib.util.IPair<AnnotatedTypeMirror,AnnotatedTypeMirror> binaryTreeArgTypes(BinaryTree tree) Returns the types of the two arguments to the BinaryTree, accounting for widening and unboxing if applicable.- Parameters:
tree
- a binary tree- Returns:
- the types of the two arguments
-
compoundAssignmentTreeArgTypes
public org.plumelib.util.IPair<AnnotatedTypeMirror,AnnotatedTypeMirror> compoundAssignmentTreeArgTypes(CompoundAssignmentTree tree) Returns the types of the two arguments to the CompoundAssignmentTree, accounting for widening and unboxing if applicable.- Parameters:
tree
- a compound assignment tree- Returns:
- the types of the two arguments
-
binaryTreeArgTypes
public org.plumelib.util.IPair<AnnotatedTypeMirror,AnnotatedTypeMirror> binaryTreeArgTypes(AnnotatedTypeMirror left, AnnotatedTypeMirror right) Returns the types of the two arguments to a binary operation, accounting for widening and unboxing if applicable.- Parameters:
left
- the type of the left argument of a binary operationright
- the type of the right argument of a binary operation- Returns:
- the types of the two arguments
-
getNarrowedPrimitive
public AnnotatedTypeMirror.AnnotatedPrimitiveType getNarrowedPrimitive(AnnotatedTypeMirror.AnnotatedPrimitiveType type, TypeMirror narrowedTypeMirror) Returns AnnotatedPrimitiveType with underlying typenarrowedTypeMirror
and with annotations copied or adapted fromtype
.Currently this method is called only for primitives that are narrowed at assignments from literal ints, for example,
byte b = 1;
. All other narrowing conversions happen at typecasts.- Parameters:
type
- type to narrownarrowedTypeMirror
- underlying type for the returned type mirror- Returns:
- result of converting
type
tonarrowedTypeMirror
-
getAnnotatedType
- See Also:
-
getAnnotatedType
- See Also:
-
getAnnotatedType
- See Also:
-
getAnnotatedType
- See Also:
-
getAnnotatedType
- See Also:
-
getAnnotatedType
- See Also:
-
fromElement
SeefromElement(Element)
.- See Also:
-
fromElement
SeefromElement(Element)
.- See Also:
-
isSupportedQualifier
@EnsuresNonNullIf(expression="#1", result=true) public boolean isSupportedQualifier(@Nullable AnnotationMirror a) Returns true if the given annotation is a part of the type system under which this type factory operates. Null is never a supported qualifier; the parameter is nullable to allow the result of canonicalAnnotation to be passed in directly.- Parameters:
a
- any annotation- Returns:
- true if that annotation is part of the type system under which this type factory operates, false otherwise
-
isSupportedQualifier
Returns true if the given class is a part of the type system under which this type factory operates.- Parameters:
clazz
- annotation class- Returns:
- true if that class is a type qualifier in the type system under which this type factory operates, false otherwise
-
isSupportedQualifier
Returns true if the given class name is a part of the type system under which this type factory operates.- Parameters:
className
- fully-qualified annotation class name- Returns:
- true if that class name is a type qualifier in the type system under which this type factory operates, false otherwise
-
addAliasedTypeAnnotation
Adds the annotationaliasClass
as an alias for the canonical annotationcanonicalAnno
that will be used by the Checker Framework in the alias's place.By specifying the alias/canonical relationship using this method, the elements of the alias are not preserved when the canonical annotation to use is constructed from the alias. If you want the elements to be copied over as well, use
addAliasedTypeAnnotation(Class, Class, boolean, String...)
.- Parameters:
aliasClass
- the class of the aliased annotationcanonicalAnno
- the canonical annotation
-
addAliasedTypeAnnotation
protected void addAliasedTypeAnnotation(@FullyQualifiedName String aliasName, AnnotationMirror canonicalAnno) Adds the annotation, whose fully-qualified name is given byaliasName
, as an alias for the canonical annotationcanonicalAnno
that will be used by the Checker Framework in the alias's place.Use this method if the alias class is not necessarily on the classpath at Checker Framework compile and run time. Otherwise, use
addAliasedTypeAnnotation(Class, AnnotationMirror)
which prevents the possibility of a typo in the class name.- Parameters:
aliasName
- the canonical name of the aliased annotationcanonicalAnno
- the canonical annotation
-
addAliasedTypeAnnotation
protected void addAliasedTypeAnnotation(Class<?> aliasClass, Class<?> canonicalClass, boolean copyElements, String... ignorableElements) Adds the annotationaliasClass
as an alias for the canonical annotationcanonicalClass
that will be used by the Checker Framework in the alias's place.You may specify the copyElements flag to indicate whether you want the elements of the alias to be copied over when the canonical annotation is constructed as a copy of
canonicalClass
. Be careful that the framework will try to copy the elements by name matching, so make sure that names and types of the elements to be copied over are exactly the same as the ones in the canonical annotation. Otherwise, an 'Couldn't find element in annotation' error is raised.To facilitate the cases where some of the elements are ignored on purpose when constructing the canonical annotation, this method also provides a varargs
ignorableElements
for you to explicitly specify the ignoring rules. For example,org.checkerframework.checker.index.qual.IndexFor
is an alias oforg.checkerframework.checker.index.qual.NonNegative
, but the element "value" of@IndexFor
should be ignored when constructing@NonNegative
. In the cases where all elements are ignored, we can simply useaddAliasedTypeAnnotation(Class, AnnotationMirror)
instead.- Parameters:
aliasClass
- the class of the aliased annotationcanonicalClass
- the class of the canonical annotationcopyElements
- a flag that indicates whether you want to copy the elements over when getting the alias from the canonical annotationignorableElements
- a list of elements that can be safely dropped when the elements are being copied over
-
addAliasedTypeAnnotation
protected void addAliasedTypeAnnotation(@FullyQualifiedName String aliasName, Class<?> canonicalAnno, boolean copyElements, String... ignorableElements) Adds the annotation, whose fully-qualified name is given byaliasName
, as an alias for the canonical annotationcanonicalAnno
that will be used by the Checker Framework in the alias's place.Use this method if the alias class is not necessarily on the classpath at Checker Framework compile and run time. Otherwise, use
addAliasedTypeAnnotation(Class, Class, boolean, String[])
which prevents the possibility of a typo in the class name.- Parameters:
aliasName
- the canonical name of the aliased classcanonicalAnno
- the canonical annotationcopyElements
- a flag that indicates whether we want to copy the elements over when getting the alias from the canonical annotationignorableElements
- a list of elements that can be safely dropped when the elements are being copied over
-
canonicalAnnotation
Returns the canonical annotation for the passed annotation. Returns null if the passed annotation is not an alias of a canonical one in the framework.A canonical annotation is the internal annotation that will be used by the Checker Framework in the aliased annotation's place.
- Parameters:
a
- the qualifier to check for an alias- Returns:
- the canonical annotation, or null if none exists
-
addAliasedDeclAnnotation
protected void addAliasedDeclAnnotation(Class<? extends Annotation> alias, Class<? extends Annotation> annotation, AnnotationMirror annotationToUse) Add the annotationalias
as an alias for the declaration annotationannotation
, where the annotation mirrorannotationToUse
will be used instead. If multiple calls are made with the sameannotation
, then theannotationToUse
must be the same.The point of
annotationToUse
is that it may include elements/fields.- Parameters:
alias
- the class of the alias annotationannotation
- the class of the canonical annotationannotationToUse
- the annotation mirror to use
-
addInheritedAnnotation
Adds the annotationannotation
in the set of declaration annotations that should be inherited. A declaration annotation will be inherited if it is in this list, or if it has the meta-annotation @InheritedAnnotation. The meta-annotation @InheritedAnnotation should be used instead of this method, if possible. -
toAnnotatedType
A convenience method that converts aTypeMirror
to an emptyAnnotatedTypeMirror
usingAnnotatedTypeMirror.createType(javax.lang.model.type.TypeMirror, org.checkerframework.framework.type.AnnotatedTypeFactory, boolean)
.- Parameters:
t
- theTypeMirror
declaration
- true if the result should be marked as a type declaration- Returns:
- an
AnnotatedTypeMirror
that hast
as its underlying type
-
type
Determines an empty annotated type of the given tree. In other words, finds theTypeMirror
for the tree and converts that into anAnnotatedTypeMirror
, but does not add any annotations to the result.Most users will want to use
getAnnotatedType(Tree)
instead; this method is mostly for internal use.- Parameters:
tree
- the tree to analyze- Returns:
- the type of
tree
, without any annotations
-
declarationFromElement
Gets the declaration tree for the element, if the source is available.TODO: would be nice to move this to InternalUtils/TreeUtils.
- Parameters:
elt
- an element- Returns:
- the tree declaration of the element if found
-
isWithinConstructor
Returns true iftree
is within a constructor.- Parameters:
tree
- the tree that might be within a constructor- Returns:
- true if
tree
is within a constructor
-
setVisitorTreePath
Sets the path to the tree that an external "visitor" is visiting. The visitor is either a subclass ofBaseTypeVisitor
orCFAbstractTransfer
.- Parameters:
visitorTreePath
- path to the current tree that an external "visitor" is visiting
-
getVisitorTreePath
Returns the path to the tree that an external "visitor" is visiting. The type factory does not update this value as it computes the types of any tree or element needed compute the type of the tree being visited. Therefore this path may not be the path to the tree whose type is being computed. This method should not be used directly. UsegetPath(Tree)
instead.This method is used to save the previous tree path and to give a hint to
getPath(Tree)
on where to look for a tree rather than searching starting at the root.- Returns:
- the path to the tree that an external "visitor" is visiting
-
getPath
Gets the path for the givenTree
under the current root by checking from the visitor's current path, and usingTrees.getPath(CompilationUnitTree, Tree)
(which is much slower) only iftree
is not found on the current path.Note that the given Tree has to be within the current compilation unit, otherwise null will be returned.
Within a subclass of BaseTypeVisitor, use
getCurrentPath()
rather than this method.- Parameters:
tree
- theTree
to get the path for- Returns:
- the path for
tree
under the current root. Returns null iftree
is not within the current compilation unit.
-
getEnclosingElementForArtificialTree
-
setEnclosingElementForArtificialTree
Adds the given mapping from a synthetic (generated) tree to its enclosing element.See
org.checkerframework.framework.flow.CFCFGBuilder.CFCFGTranslationPhaseOne.handleArtificialTree(Tree)
.- Parameters:
tree
- artifical treeenclosing
- element that enclosestree
-
parseAnnotationFiles
protected void parseAnnotationFiles()Parses all annotation files in the following order:- jdk.astub in the same directory as the checker, if it exists and ignorejdkastub option is not supplied
- jdkN.astub (where N is the Java version or any higher value) in the same directory as the checker, if it exists and ignorejdkastub option is not supplied
- Stub files listed in @StubFiles annotation on the checker; must be in same directory as the checker
- Stub files provided via
-Astubs
compiler option - Ajava files provided via
-Aajava
compiler option
If a type is annotated with a qualifier from the same hierarchy in more than one stub file, the qualifier in the last stub file is applied.
The annotations are stored by side-effecting
stubTypes
andajavaTypes
. -
getDeclAnnotation
Returns all of the declaration annotations whose name equals the passed annotation class (or is an alias for it) including annotations:- on the element
- written in stubfiles
- inherited from overridden methods, (see
InheritedAnnotation
) - inherited from superclasses or super interfaces (see
Inherited
)
- Specified by:
getDeclAnnotation
in interfaceAnnotationProvider
- Parameters:
elt
- the element to retrieve the declaration annotation fromanno
- annotation class- Returns:
- the annotation mirror for anno
- See Also:
-
getDeclAnnotationNoAliases
public final @Nullable AnnotationMirror getDeclAnnotationNoAliases(Element elt, Class<? extends Annotation> anno) Returns the annotation mirror used to annotate this element, whose name equals the passed annotation class. Looks in the same places specified bygetDeclAnnotation(Element, Class)
. Returns null if none exists. Does not check for aliases of the annotation class.Call this method from a checker that needs to alias annotations for one purpose and not for another. For example, in the Lock Checker,
@LockingFree
and@ReleasesNoLocks
are both aliases of@SideEffectFree
since they are all considered side-effect-free with regard to the set of locks held before and after the method call. However, asynchronized
block is permitted inside a@ReleasesNoLocks
method but not inside a@LockingFree
or@SideEffectFree
method.- Parameters:
elt
- the element to retrieve the declaration annotation fromanno
- annotation class- Returns:
- the annotation mirror for anno
- See Also:
-
isFromStubFile
Returns true if the element appears in a stub file (Currently only works for methods, constructors, and fields). -
isFromByteCode
Returns true if the element is from bytecode and the if the element did not appear in a stub file. Currently only works for methods, constructors, and fields. -
shouldWarnIfStubRedundantWithBytecode
public boolean shouldWarnIfStubRedundantWithBytecode()Returns true if redundancy between a stub file and bytecode should be reported.For most type systems the default behavior of returning true is correct. For subcheckers, redundancy in one of the type hierarchies can be ok. Such implementations should return false.
- Returns:
- whether to warn about redundancy between a stub file and bytecode
-
getDeclAnnotations
Returns all of the declaration annotations on this element including annotations:- on the element
- written in stubfiles
- inherited from overridden methods, (see
InheritedAnnotation
) - inherited from superclasses or super interfaces (see
Inherited
)
This method returns the actual annotations not their aliases.
getDeclAnnotation(Element, Class)
returns aliases.- Parameters:
elt
- the element for which to determine annotations- Returns:
- all of the declaration annotations on this element, written in stub files, or inherited
-
getDeclAnnotationWithMetaAnnotation
public List<org.plumelib.util.IPair<AnnotationMirror,AnnotationMirror>> getDeclAnnotationWithMetaAnnotation(Element element, Class<? extends Annotation> metaAnnotationClass) Returns a list of all declaration annotations used to annotate the element, which have a meta-annotation (i.e., an annotation on that annotation) with classmetaAnnotationClass
.- Parameters:
element
- the element for which to determine annotationsmetaAnnotationClass
- the class of the meta-annotation that needs to be present- Returns:
- a list of pairs
(anno, metaAnno)
whereanno
is the annotation mirror atelement
, andmetaAnno
is the annotation mirror (of typemetaAnnotationClass
) used to meta-annotate the declaration ofanno
-
getAnnotationWithMetaAnnotation
public List<org.plumelib.util.IPair<AnnotationMirror,AnnotationMirror>> getAnnotationWithMetaAnnotation(Element element, Class<? extends Annotation> metaAnnotationClass) Returns a list of all annotations used to annotate this element, which have a meta-annotation (i.e., an annotation on that annotation) with classmetaAnnotationClass
.- Parameters:
element
- the element at which to look for annotationsmetaAnnotationClass
- the class of the meta-annotation that needs to be present- Returns:
- a list of pairs
(anno, metaAnno)
whereanno
is the annotation mirror atelement
, andmetaAnno
is the annotation mirror used to annotateanno
.
-
hasQualifierParameterInHierarchy
public boolean hasQualifierParameterInHierarchy(AnnotatedTypeMirror annotatedTypeMirror, AnnotationMirror top) Whether or not theannotatedTypeMirror
has a qualifier parameter.- Parameters:
annotatedTypeMirror
- the type to checktop
- the top of the hierarchy to check- Returns:
- true if the type has a qualifier parameter
-
hasQualifierParameterInHierarchy
Whether or not theelement
has a qualifier parameter.- Parameters:
element
- element to checktop
- the top of the hierarchy to check- Returns:
- true if the type has a qualifier parameter
-
hasExplicitQualifierParameterInHierarchy
Returns whether theHasQualifierParameter
annotation was explicitly written onelement
for the hierarchy given bytop
.- Parameters:
element
- the Element to checktop
- the top qualifier for the hierarchy to check- Returns:
- whether the class given by
element
has been explicitly annotated withHasQualifierParameter
for the given hierarchy
-
hasExplicitNoQualifierParameterInHierarchy
Returns whether theNoQualifierParameter
annotation was explicitly written onelement
for the hierarchy given bytop
.- Parameters:
element
- the Element to checktop
- the top qualifier for the hierarchy to check- Returns:
- whether the class given by
element
has been explicitly annotated withNoQualifierParameter
for the given hierarchy
-
getQualifierParameterHierarchies
Returns the set of top annotations representing all the hierarchies for which this type has a qualifier parameter.- Parameters:
annotatedType
- the type to check- Returns:
- the set of top annotations representing all the hierarchies for which this type has a qualifier parameter
-
getQualifierParameterHierarchies
Returns the set of top annotations representing all the hierarchies for which this element has a qualifier parameter.- Parameters:
element
- the Element to check- Returns:
- the set of top annotations representing all the hierarchies for which this element has a qualifier parameter
-
replaceAnnotations
Replaces or adds all annotations fromfrom
toto
. Annotations fromfrom
will be used everywhere they exist, but annotations into
will be kept anywhere thatfrom
is unannotated.- Parameters:
from
- the annotated type mirror from which to take new annotationsto
- the annotated type mirror to which the annotations will be added
-
replaceAnnotations
public void replaceAnnotations(AnnotatedTypeMirror from, AnnotatedTypeMirror to, AnnotationMirror top) Replaces or adds annotations intop
's hierarchy fromfrom
toto
. Annotations fromfrom
will be used everywhere they exist, but annotations into
will be kept anywhere thatfrom
is unannotated.- Parameters:
from
- the annotated type mirror from which to take new annotationsto
- the annotated type mirror to which the annotations will be addedtop
- the top type of the hierarchy whose annotations will be added
-
containsCapturedTypes
Returns true iftype
contains any captured type variables.- Parameters:
type
- type to check- Returns:
- true if
type
contains any captured type variables
-
getFunctionTypeFromTree
public AnnotatedTypeMirror.AnnotatedExecutableType getFunctionTypeFromTree(MemberReferenceTree tree) Returns the function type that this member reference targets.The function type is the type of the single method declared in the functional interface adapted as if it were invoked using the functional interface as the receiver expression.
The target type of a member reference is the type to which it is assigned or casted.
- Parameters:
tree
- member reference tree- Returns:
- the function type that this method reference targets
-
getFunctionTypeFromTree
public AnnotatedTypeMirror.AnnotatedExecutableType getFunctionTypeFromTree(LambdaExpressionTree tree) Returns the function type that this lambda targets.The function type is the type of the single method declared in the functional interface adapted as if it were invoked using the functional interface as the receiver expression.
The target type of a lambda is the type to which it is assigned or casted.
- Parameters:
tree
- lambda expression tree- Returns:
- the function type that this lambda targets
-
getFnInterfaceFromTree
public org.plumelib.util.IPair<AnnotatedTypeMirror,AnnotatedTypeMirror.AnnotatedExecutableType> getFnInterfaceFromTree(Tree tree) Returns the functional interface and the function type that this lambda or member references targets.The function type is the type of the single method declared in the functional interface adapted as if it were invoked using the functional interface as the receiver expression.
The target type of a lambda or a method reference is the type to which it is assigned or casted.
- Parameters:
tree
- lambda expression tree or member reference tree- Returns:
- the functional interface and the function type that this method reference or lambda targets
-
applyCaptureConversion
Apply capture conversion totypeToCapture
.Capture conversion is the process of converting wildcards in a parameterized type to fresh type variables. See JLS 5.1.10 for details.
If
type
is not a declared type or if it does not have any wildcard type arguments, this method returnstype
.- Parameters:
typeToCapture
- type to capture- Returns:
- the result of applying capture conversion to
typeToCapture
-
applyCaptureConversion
Apply capture conversion totype
.Capture conversion is the process of converting wildcards in a parameterized type to fresh type variables. See JLS 5.1.10 for details.
If
type
is not a declared type or if it does not have any wildcard type arguments, this method returnstype
.- Parameters:
type
- type to capturetypeMirror
- the result of applying capture conversion to the underlying type oftype
; it is used as the underlying type of the returned type- Returns:
- the result of applying capture conversion to
type
-
order
public List<AnnotatedTypeMirror.AnnotatedTypeVariable> order(Collection<AnnotatedTypeMirror.AnnotatedTypeVariable> collection) Returns the list of type variables such that a type variable in the list only references type variables at a lower index than itself.- Parameters:
collection
- a collection of type variables- Returns:
- the type variables ordered so that each type variable only references earlier type variables
-
getElementUtils
Returns the utility class for working withElement
s.- Returns:
- the utility class for working with
Element
s
-
getTreeUtils
Accessor for the tree utilities. -
getProcessingEnv
Accessor for the processing environment.- Returns:
- the processing environment
-
getExpressionAndOffset
Given an expression, split it into a subexpression and a constant offset. For example:
There are methods that can only take as input an expression that represents a JavaExpression. The purpose of this is to pre-process expressions to make those methods more likely to succeed."a" => <"a", "0"> "a + 5" => <"a", "5"> "a + -5" => <"a", "-5"> "a - 5" => <"a", "-5">
- Parameters:
expression
- an expression to remove a constant offset from- Returns:
- a sub-expression and a constant offset. The offset is "0" if this routine is unable to splite the given expression
-
negateConstant
Given an expression string, returns its negation.- Parameters:
constantExpression
- a string representing an integer constant- Returns:
- the negation of constantExpression
-
getDummyAssignedTo
Returnsnull
or an annotated type mirror that type argument inference should assumeexpressionTree
is assigned to.If
null
is returned, inference proceeds normally.If a type is returned, then inference assumes that
expressionTree
was asigned to it. This biases the inference algorithm toward the annotations in the returned type. In particular, if the annotations on type variables in invariant positions are a super type of the annotations inferred, the super type annotations are chosen.This implementation returns null, but subclasses may override this method to return a type.
- Parameters:
expressionTree
- an expression which has no assignment context and for which type arguments need to be inferred- Returns:
null
or an annotated type mirror that inferrence should pretendexpressionTree
is assigned to
-
areSameByClass
Checks that the annotationam
has the name ofannoClass
. Values are ignored.This method is faster than
AnnotationUtils.areSameByClass(AnnotationMirror, Class)
because it caches the name of the class rather than computing it each time.- Parameters:
am
- the AnnotationMirror whose class to compareannoClass
- the class to compare- Returns:
- true if annoclass is the class of am
-
containsSameByClass
public boolean containsSameByClass(Collection<? extends AnnotationMirror> c, Class<? extends Annotation> anno) Checks that the collection contains the annotation. UsingCollection.contains
does not always work, because it does not useareSame()
for comparison.This method is faster than
AnnotationUtils.containsSameByClass(Collection, Class)
because is caches the name of the class rather than computing it each time.- Parameters:
c
- a collection of AnnotationMirrorsanno
- the annotation class to search for in c- Returns:
- true iff c contains anno, according to areSameByClass
-
getAnnotationByClass
public @Nullable AnnotationMirror getAnnotationByClass(Collection<? extends AnnotationMirror> c, Class<? extends Annotation> anno) Returns the AnnotationMirror inc
that has the same class asanno
.This method is faster than
AnnotationUtils.getAnnotationByClass(Collection, Class)
because is caches the name of the class rather than computing it each time.- Parameters:
c
- a collection of AnnotationMirrorsanno
- the class to search for in c- Returns:
- AnnotationMirror with the same class as
anno
iff c contains anno, according to areSameByClass; otherwise,null
-
wpiAdjustForUpdateField
public void wpiAdjustForUpdateField(Tree lhsTree, Element element, String fieldName, AnnotatedTypeMirror rhsATM) Changes the type ofrhsATM
when being assigned to a field, for use by whole-program inference. The default implementation does nothing.- Parameters:
lhsTree
- the tree for the field whose type will be changedelement
- the element for the field whose type will be changedfieldName
- the name of the field whose type will be changedrhsATM
- the type of the expression being assigned to the field, which is side-effected by this method
-
wpiAdjustForUpdateNonField
Changes the type ofrhsATM
when being assigned to anything other than a field, for use by whole-program inference. The default implementation does nothing.- Parameters:
rhsATM
- the type of the rhs of the pseudo-assignment, which is side-effected by this method
-
wpiShouldInferTypesForReceivers
public boolean wpiShouldInferTypesForReceivers()Returns whether whole-program inference should infer types for receiver expressions. For some type systems, such as nullness, it doesn't make sense for WPI to do inference on receivers.- Returns:
- true if WPI should infer types for method receiver parameters, false otherwise
-
wpiPrepareMethodForWriting
public void wpiPrepareMethodForWriting(org.checkerframework.afu.scenelib.el.AMethod methodAnnos) Side-effects the method or constructor annotations to make any desired changes before writing to an annotation file.- Parameters:
methodAnnos
- the method or constructor annotations to modify
-
wpiPrepareMethodForWriting
public void wpiPrepareMethodForWriting(WholeProgramInferenceJavaParserStorage.CallableDeclarationAnnos methodAnnos, Collection<WholeProgramInferenceJavaParserStorage.CallableDeclarationAnnos> inSupertypes, Collection<WholeProgramInferenceJavaParserStorage.CallableDeclarationAnnos> inSubtypes) Side-effects the method or constructor annotations to make any desired changes before writing to an ajava file.Overriding implementations should call
super.wpiPrepareMethodForWriting()
.- Parameters:
methodAnnos
- the method or constructor annotations to modifyinSupertypes
- the method or constructor annotations for all overridden methods; not side-effectedinSubtypes
- the method or constructor annotations for all overriding methods; not side-effected
-
makeConditionConsistentWithOtherMethod
protected void makeConditionConsistentWithOtherMethod(Map<String, org.plumelib.util.IPair<AnnotatedTypeMirror, AnnotatedTypeMirror>> conditionMap, WholeProgramInferenceJavaParserStorage.CallableDeclarationAnnos otherDeclAnnos, boolean isPrecondition, boolean otherIsSupertype) Performs side effects to makeconditionMap
obey behavioral subtyping constraints withotherDeclAnnos
, that is, postconditions must be at least as strong as the postcondition on the superclass, and preconditions must be at most as strong as the condition on the superclass.Overriding implementations should call
super.makeConditionConsistentWithOtherMethod()
.- Parameters:
conditionMap
- pre- or post-condition annotations on a method M; may be side-effectedotherDeclAnnos
- annotations on a method that M overrides or that overrides M; that is, on a method in the same "method family" as M; may be side-effectedisPrecondition
- true if the annotations are pre-condition annotations, false if they are post-condition annotationsotherIsSupertype
- true ifotherDeclAnnos
are on a supertype; false if they are on a subtype
-
doesAnnotatedForApplyToThisChecker
Doesanno
, which is anAnnotatedFor
annotation, apply to this checker?- Parameters:
annotatedForAnno
- anAnnotatedFor
annotation- Returns:
- whether
anno
applies to this checker
-
getContractExpressions
Get theexpression
field/element of the given contract annotation.- Parameters:
contractAnno
- aRequiresQualifier
,EnsuresQualifier
, orEnsuresQualifier
- Returns:
- the
expression
field/element of the given annotation
-
getContractListValues
Get thevalue
field/element of the given contract list annotation.- Parameters:
contractListAnno
- aRequiresQualifier.List
,EnsuresQualifier.List
, orEnsuresQualifierIf.List
- Returns:
- the
value
field/element of the given annotation
-
isImmutable
Returns true if the type is immutable. Subclasses can override this method to add types that are mutable, but the annotated type of an object is immutable.- Parameters:
type
- type to test- Returns:
- true if the type is immutable
-
isSideEffectFree
Description copied from interface:AnnotationProvider
Returns true if the given method is side-effect-free according to this AnnotationProvider — that is, if a call to the given method does not undo flow-sensitive type refinement.Note that this method takes account of this AnnotationProvider's semantics, whereas
org.checkerframework.dataflow.util.PurityUtils#isSideEffectFree
does not.- Specified by:
isSideEffectFree
in interfaceAnnotationProvider
- Parameters:
methodElement
- a method- Returns:
- true if a call to the method does not undo flow-sensitive type refinement
-
isDeterministic
Description copied from interface:AnnotationProvider
Returns true if the given method is deterministic according to this AnnotationProvider — that is, if multiple calls to the given method (with the same arguments) return the same value.Note that this method takes account of this AnnotationProvider's semantics, whereas
org.checkerframework.dataflow.util.PurityUtils#isDeterministic
does not.- Specified by:
isDeterministic
in interfaceAnnotationProvider
- Parameters:
methodElement
- a method- Returns:
- true if multiple calls to the method (with the same arguments) return the same value
-
logGat
Output a message aboutgetAnnotatedType(javax.lang.model.element.Element)
, if logging is on.Set the value of
debugGat
to true to enable logging.- Parameters:
format
- a format stringargs
- arguments to the format string
-