Class AnnotatedTypeFactory
- java.lang.Object
-
- org.checkerframework.framework.type.AnnotatedTypeFactory
-
- All Implemented Interfaces:
AnnotationProvider
- Direct Known Subclasses:
GenericAnnotatedTypeFactory
,TypeOutputtingChecker.GeneralAnnotatedTypeFactory
public class AnnotatedTypeFactory extends java.lang.Object implements AnnotationProvider
The methods of this class take an element or AST node, and return the annotated type as anAnnotatedTypeMirror
. 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)
andaddComputedTypeAnnotations(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
Nested Classes Modifier and Type Class Description static class
AnnotatedTypeFactory.ParameterizedExecutableType
The type for an instantiated generic method or constructor.
-
Field Summary
Fields Modifier and Type Field Description AnnotationFileElementTypes
ajavaTypes
Parses ajava files and stores annotations on public elements from ajava files.protected javax.lang.model.element.ExecutableElement
annotatedForValueElement
The AnnotatedFor.value argument/element.protected BaseTypeChecker
checker
The checker to use for option handling and resource management.protected @Nullable AnnotationFileElementTypes
currentFileAjavaTypes
If type checking a Java file, stores annotations read from an ajava file for that class if one exists.protected javax.lang.model.util.Elements
elements
Utility class for working withElement
s.protected javax.lang.model.element.ExecutableElement
ensuresQualifierExpressionElement
The EnsuresQualifier.expression field/element.protected javax.lang.model.element.ExecutableElement
ensuresQualifierIfExpressionElement
The EnsuresQualifierIf.expression field/element.protected javax.lang.model.type.TypeMirror
ensuresQualifierIfListTM
The EnsuresQualifierIf.List type.protected javax.lang.model.element.ExecutableElement
ensuresQualifierIfListValueElement
The EnsuresQualifierIf.List.value field/element.protected javax.lang.model.element.ExecutableElement
ensuresQualifierIfResultElement
The EnsuresQualifierIf.result argument/element.protected javax.lang.model.type.TypeMirror
ensuresQualifierIfTM
The EnsuresQualifierIf type.protected javax.lang.model.type.TypeMirror
ensuresQualifierListTM
The EnsuresQualifier.List type.protected javax.lang.model.element.ExecutableElement
ensuresQualifierListValueElement
The EnsuresQualifier.List.value field/element.protected javax.lang.model.type.TypeMirror
ensuresQualifierTM
The EnsuresQualifier type.protected javax.lang.model.element.ExecutableElement
fieldInvariantFieldElement
The FieldInvariant.field argument/element.protected javax.lang.model.element.ExecutableElement
fieldInvariantQualifierElement
The FieldInvariant.qualifier argument/element.protected java.util.Map<com.sun.source.tree.Tree,AnnotatedTypeMirror>
fromExpressionTreeCache
Mapping from an expression tree to its annotated type; before defaults are applied, just what the programmer wrote.protected java.util.Map<com.sun.source.tree.Tree,AnnotatedTypeMirror>
fromMemberTreeCache
Mapping from a member tree to its annotated type; before defaults are applied, just what the programmer wrote.protected java.util.Map<com.sun.source.tree.Tree,AnnotatedTypeMirror>
fromTypeTreeCache
Mapping from a type tree to its annotated type; before defaults are applied, just what the programmer wrote.protected javax.lang.model.element.ExecutableElement
hasQualifierParameterValueElement
The HasQualifierParameter.value field/element.boolean
ignoreUninferredTypeArguments
Whether to ignore uninferred type arguments.protected AnnotationClassLoader
loader
This loads type annotation classes via reflective lookup.javax.lang.model.element.ExecutableElement
methodValClassNameElement
The MethodVal.className argument/element.javax.lang.model.element.ExecutableElement
methodValMethodNameElement
The MethodVal.methodName argument/element.javax.lang.model.element.ExecutableElement
methodValParamsElement
The MethodVal.params argument/element.protected javax.lang.model.element.ExecutableElement
noQualifierParameterValueElement
The NoQualifierParameter.value field/element.protected javax.lang.model.element.ExecutableElement
objectGetClass
The Object.getClass method.protected javax.annotation.processing.ProcessingEnvironment
processingEnv
The processing environment to use for accessing compiler internals.protected QualifierHierarchy
qualHierarchy
Represent the annotation relations.protected QualifierUpperBounds
qualifierUpperBounds
Holds the qualifier upper bounds for type uses.protected ReflectionResolver
reflectionResolver
Object that is used to resolve reflective method calls, if reflection resolution is turned on.protected javax.lang.model.element.ExecutableElement
requiresQualifierExpressionElement
The RequiresQualifier.expression field/element.protected javax.lang.model.type.TypeMirror
requiresQualifierListTM
The RequiresQualifier.List type.protected javax.lang.model.element.ExecutableElement
requiresQualifierListValueElement
The RequiresQualifier.List.value field/element.protected javax.lang.model.type.TypeMirror
requiresQualifierTM
The RequiresQualifier type.protected @Nullable com.sun.source.tree.CompilationUnitTree
root
Optional! The AST of the source file being operated on.boolean
shouldCache
Should results be cached? This means that ATM.deepCopy() will be called.AnnotationFileElementTypes
stubTypes
Parses stub files and stores annotations on public elements from stub files.protected com.sun.source.util.Trees
trees
TheTrees
instance to use for tree node path finding.protected TypeArgumentInference
typeArgumentInference
Provides utility method to infer type arguments.protected AnnotatedTypeFormatter
typeFormatter
This formatter is used for converting AnnotatedTypeMirrors to Strings.protected TypeHierarchy
typeHierarchy
Represent the type relations.javax.lang.model.util.Types
types
Utility class for working withTypeMirror
s.protected TypeVariableSubstitutor
typeVarSubstitutor
Provides utility method to substitute arguments for their type variables.int
uid
Unique ID of the current object; for debugging purposes.protected @Nullable ViewpointAdapter
viewpointAdapter
Viewpoint adapter used to perform viewpoint adaptation or null
-
Constructor Summary
Constructors Constructor Description AnnotatedTypeFactory(BaseTypeChecker checker)
Constructs a factory from the given checker.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description protected void
adaptGetClassReturnTypeToReceiver(AnnotatedTypeMirror.AnnotatedExecutableType getClassType, AnnotatedTypeMirror receiverType, com.sun.source.tree.ExpressionTree tree)
Java special-cases the return type ofgetClass()
.protected void
addAliasedDeclAnnotation(@FullyQualifiedName java.lang.String alias, @FullyQualifiedName java.lang.String annotation, javax.lang.model.element.AnnotationMirror annotationToUse)
Add the annotationalias
as an alias for the declaration annotationannotation
, where the annotation mirrorannotationToUse
will be used instead.protected void
addAliasedDeclAnnotation(java.lang.Class<? extends java.lang.annotation.Annotation> alias, java.lang.Class<? extends java.lang.annotation.Annotation> annotation, javax.lang.model.element.AnnotationMirror annotationToUse)
Add the annotationalias
as an alias for the declaration annotationannotation
, where the annotation mirrorannotationToUse
will be used instead.protected void
addAliasedTypeAnnotation(@FullyQualifiedName java.lang.String aliasName, java.lang.Class<?> canonicalAnno, boolean copyElements, java.lang.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 java.lang.String aliasName, javax.lang.model.element.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(java.lang.Class<?> aliasClass, java.lang.Class<?> canonicalClass, boolean copyElements, java.lang.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(java.lang.Class<?> aliasClass, javax.lang.model.element.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, javax.lang.model.element.VariableElement field)
Adds the qualifier specified by a field invariant forfield
totype
.protected void
addComputedTypeAnnotations(com.sun.source.tree.Tree tree, AnnotatedTypeMirror type)
Changes annotations on a type obtained from aTree
.protected void
addComputedTypeAnnotations(javax.lang.model.element.Element elt, AnnotatedTypeMirror type)
Changes annotations on a type obtained from anElement
.void
addDefaultAnnotations(AnnotatedTypeMirror type)
Adds default annotations totype
.protected void
addInheritedAnnotation(javax.lang.model.element.AnnotationMirror annotation)
Adds the annotationannotation
in the set of declaration annotations that should be inherited.AnnotatedTypeMirror
applyCaptureConversion(AnnotatedTypeMirror typeToCapture)
Apply capture conversion totypeToCapture
.AnnotatedTypeMirror
applyCaptureConversion(AnnotatedTypeMirror type, javax.lang.model.type.TypeMirror typeMirror)
Apply capture conversion totype
.AnnotatedTypeMirror.AnnotatedPrimitiveType
applyUnboxing(AnnotatedTypeMirror type)
Return a primitive type: either the argument, or the result of unboxing it (which might affect its annotations).boolean
areSameByClass(javax.lang.model.element.AnnotationMirror am, java.lang.Class<? extends java.lang.annotation.Annotation> annoClass)
Checks that the annotationam
has the name ofannoClass
.org.plumelib.util.IPair<AnnotatedTypeMirror,AnnotatedTypeMirror>
binaryTreeArgTypes(com.sun.source.tree.BinaryTree tree)
Returns the types of the two arguments to the BinaryTree.protected org.plumelib.util.IPair<AnnotatedTypeMirror,AnnotatedTypeMirror>
binaryTreeArgTypes(javax.lang.model.type.TypeMirror resultType, AnnotatedTypeMirror left, AnnotatedTypeMirror right)
Returns the types of the two arguments to a binary operation.org.plumelib.util.IPair<AnnotatedTypeMirror,AnnotatedTypeMirror>
binaryTreeArgTypes(AnnotatedTypeMirror left, AnnotatedTypeMirror right)
@Nullable javax.lang.model.element.AnnotationMirror
canonicalAnnotation(javax.lang.model.element.AnnotationMirror a)
Returns the canonical annotation for the passed annotation.org.plumelib.util.IPair<AnnotatedTypeMirror,AnnotatedTypeMirror>
compoundAssignmentTreeArgTypes(com.sun.source.tree.CompoundAssignmentTree tree)
Returns the types of the two arguments to the CompoundAssignmentTree.AnnotatedTypeFactory.ParameterizedExecutableType
constructorFromUse(com.sun.source.tree.NewClassTree tree)
Determines the type of the invoked constructor based on the passed new class tree.protected void
constructorFromUsePreSubstitution(com.sun.source.tree.NewClassTree tree, AnnotatedTypeMirror.AnnotatedExecutableType type)
A callback method for the AnnotatedTypeFactory subtypes to customize the handling of the declared constructor type before type variable substitution.boolean
containsSameByClass(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c, java.lang.Class<? extends java.lang.annotation.Annotation> anno)
Checks that the collection contains the annotation.boolean
containsUninferredTypeArguments(AnnotatedTypeMirror type)
Returns whether this type or any component type is a wildcard type for which Java 7 type inference is insufficient.protected AnnotatedTypeFormatter
createAnnotatedTypeFormatter()
Creates the AnnotatedTypeFormatter used by this type factory and all AnnotatedTypeMirrors it creates.protected AnnotationClassLoader
createAnnotationClassLoader()
Factory method to easily change whatAnnotationClassLoader
is created to load type annotation classes.protected AnnotationFormatter
createAnnotationFormatter()
protected QualifierHierarchy
createQualifierHierarchy()
Returns theQualifierHierarchy
to be used by this checker.protected QualifierUpperBounds
createQualifierUpperBounds()
CreatesQualifierUpperBounds
for this type factory.protected java.util.Set<java.lang.Class<? extends java.lang.annotation.Annotation>>
createSupportedTypeQualifiers()
Returns a mutable set of annotation classes that are supported by a checker.protected TypeArgumentInference
createTypeArgumentInference()
TypeArgumentInference infers the method type arguments when they are not explicitly written.protected TypeHierarchy
createTypeHierarchy()
Creates the type hierarchy to be used by this factory.protected TypeVariableSubstitutor
createTypeVariableSubstitutor()
TypeVariableSubstitutor provides a method to replace type parameters with their arguments.protected @Nullable ViewpointAdapter
createViewpointAdapter()
Factory method to create a ViewpointAdapter.@Nullable com.sun.source.tree.Tree
declarationFromElement(javax.lang.model.element.Element elt)
Gets the declaration tree for the element, if the source is available.boolean
doesAnnotatedForApplyToThisChecker(javax.lang.model.element.AnnotationMirror annotatedForAnno)
Doesanno
, which is anAnnotatedFor
annotation, apply to this checker?AnnotatedTypeMirror
fromElement(javax.lang.model.element.Element elt)
Creates an AnnotatedTypeMirror forelt
that includes: annotations explicitly written on the element and annotations from stub files.AnnotatedTypeMirror.AnnotatedExecutableType
fromElement(javax.lang.model.element.ExecutableElement elt)
SeefromElement(Element)
.AnnotatedTypeMirror.AnnotatedDeclaredType
fromElement(javax.lang.model.element.TypeElement elt)
SeefromElement(Element)
.AnnotatedTypeMirror.AnnotatedDeclaredType
fromNewClass(com.sun.source.tree.NewClassTree newClassTree)
Deprecated.AnnotatedTypeMirror.AnnotatedNullType
getAnnotatedNullType(java.util.Set<? extends javax.lang.model.element.AnnotationMirror> annotations)
Creates and returns an AnnotatedNullType qualified withannotations
.AnnotatedTypeMirror.AnnotatedDeclaredType
getAnnotatedType(com.sun.source.tree.ClassTree tree)
AnnotatedTypeMirror.AnnotatedExecutableType
getAnnotatedType(com.sun.source.tree.MethodTree tree)
AnnotatedTypeMirror.AnnotatedArrayType
getAnnotatedType(com.sun.source.tree.NewArrayTree tree)
AnnotatedTypeMirror.AnnotatedDeclaredType
getAnnotatedType(com.sun.source.tree.NewClassTree tree)
AnnotatedTypeMirror
getAnnotatedType(com.sun.source.tree.Tree tree)
Returns an AnnotatedTypeMirror representing the annotated type oftree
.AnnotatedTypeMirror
getAnnotatedType(java.lang.Class<?> clazz)
Returns an AnnotatedTypeMirror representing the annotated type ofclazz
.AnnotatedTypeMirror
getAnnotatedType(javax.lang.model.element.Element elt)
Returns an AnnotatedTypeMirror representing the annotated type ofelt
.AnnotatedTypeMirror.AnnotatedExecutableType
getAnnotatedType(javax.lang.model.element.ExecutableElement elt)
AnnotatedTypeMirror.AnnotatedDeclaredType
getAnnotatedType(javax.lang.model.element.TypeElement elt)
AnnotatedTypeFormatter
getAnnotatedTypeFormatter()
AnnotatedTypeMirror
getAnnotatedTypeFromTypeTree(com.sun.source.tree.Tree tree)
Determines the annotated type from a type in tree form.@Nullable javax.lang.model.element.AnnotationMirror
getAnnotationByClass(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c, java.lang.Class<? extends java.lang.annotation.Annotation> anno)
Returns the AnnotationMirror inc
that has the same class asanno
.AnnotationFormatter
getAnnotationFormatter()
@Nullable javax.lang.model.element.AnnotationMirror
getAnnotationMirror(com.sun.source.tree.Tree tree, java.lang.Class<? extends java.lang.annotation.Annotation> target)
Return the annotation ontree
that is in the hierarchy that contains the qualifiertarget
.AnnotationMirrorSet
getAnnotationOrTypeDeclarationBound(javax.lang.model.type.TypeMirror type, java.util.Set<? extends javax.lang.model.element.AnnotationMirror> annos)
Compare the givenannos
with the declaration bounds oftype
and return the appropriate qualifiers.java.util.List<org.plumelib.util.IPair<javax.lang.model.element.AnnotationMirror,javax.lang.model.element.AnnotationMirror>>
getAnnotationWithMetaAnnotation(javax.lang.model.element.Element element, java.lang.Class<? extends java.lang.annotation.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
.AnnotatedTypeMirror.AnnotatedDeclaredType
getBoxedType(AnnotatedTypeMirror.AnnotatedPrimitiveType type)
Returns the annotated boxed type of the given primitive type.protected java.util.Set<java.lang.Class<? extends java.lang.annotation.Annotation>>
getBundledTypeQualifiers(java.lang.Class<? extends java.lang.annotation.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
getCacheSize()
Returns the size for LRU caches.BaseTypeChecker
getChecker()
Returns the checker associated with this factory.java.util.List<java.lang.String>
getCheckerNames()
Returns the names of the annotation processors that are being run.java.util.List<java.lang.String>
getContractExpressions(javax.lang.model.element.AnnotationMirror contractAnno)
Get theexpression
field/element of the given contract annotation.java.util.List<javax.lang.model.element.AnnotationMirror>
getContractListValues(javax.lang.model.element.AnnotationMirror contractListAnno)
Get thevalue
field/element of the given contract list annotation.protected com.sun.source.tree.ClassTree
getCurrentClassTree(com.sun.source.tree.Tree tree)
Deprecated.UseTreePathUtil.enclosingClass(getPath(tree))
instead.protected @Nullable AnnotatedTypeMirror.AnnotatedDeclaredType
getCurrentMethodReceiver(com.sun.source.tree.Tree tree)
Deprecated.UsegetSelfType(Tree)
insteadjavax.lang.model.element.AnnotationMirror
getDeclAnnotation(javax.lang.model.element.Element elt, java.lang.Class<? extends java.lang.annotation.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
)@Nullable javax.lang.model.element.AnnotationMirror
getDeclAnnotationNoAliases(javax.lang.model.element.Element elt, java.lang.Class<? extends java.lang.annotation.Annotation> anno)
Returns the annotation mirror used to annotate this element, whose name equals the passed annotation class.AnnotationMirrorSet
getDeclAnnotations(javax.lang.model.element.Element elt)
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
)java.util.List<org.plumelib.util.IPair<javax.lang.model.element.AnnotationMirror,javax.lang.model.element.AnnotationMirror>>
getDeclAnnotationWithMetaAnnotation(javax.lang.model.element.Element element, java.lang.Class<? extends java.lang.annotation.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
getDefaultTypeDeclarationBounds()
Returns the set of qualifiers that are the upper bound for a type use if no other bound is specified for the type.@Nullable AnnotatedTypeMirror
getDummyAssignedTo(com.sun.source.tree.ExpressionTree expressionTree)
Returnsnull
or an annotated type mirror that type argument inference should assumeexpressionTree
is assigned to.javax.lang.model.util.Elements
getElementUtils()
Returns the utility class for working withElement
s.@Nullable com.sun.source.tree.Tree
getEnclosingClassOrMethod(com.sun.source.tree.Tree tree)
Returns the innermost enclosing method or class tree oftree
.AnnotatedTypeMirror.AnnotatedDeclaredType
getEnclosingSubType(javax.lang.model.element.TypeElement typeElement, com.sun.source.tree.Tree tree)
Returns theAnnotatedTypeMirror
of the enclosing type at the location oftree
that is a subtype oftypeElement
.AnnotatedTypeMirror.AnnotatedDeclaredType
getEnclosingType(javax.lang.model.element.TypeElement typeElement, com.sun.source.tree.Tree tree)
Returns theAnnotatedTypeMirror
of the enclosing type at the location oftree
that is the same type astypeElement
.protected java.util.Set<javax.lang.model.element.AnnotationMirror>
getEnumConstructorQualifiers()
Returns the annotations that should be applied to enum constructors.AnnotationMirrorSet
getExplicitNewClassAnnos(com.sun.source.tree.NewClassTree newClassTree)
Returns the annotations explicitly written on a NewClassTree.protected java.util.List<AnnotatedTypeMirror>
getExplicitNewClassClassTypeArgs(com.sun.source.tree.NewClassTree newClass)
Returns the partially-annotated explicit class type arguments of the new class tree.static org.plumelib.util.IPair<java.lang.String,java.lang.String>
getExpressionAndOffset(java.lang.String expression)
Given an expression, split it into a subexpression and a constant offset.@Nullable com.sun.source.tree.AnnotationTree
getFieldInvariantAnnotationTree(@Nullable java.util.List<? extends com.sun.source.tree.AnnotationTree> annoTrees)
Returns the element ofannoTrees
that is a use of one of the field invariant annotations (as specified viagetFieldInvariantDeclarationAnnotations()
.protected java.util.Set<java.lang.Class<? extends java.lang.annotation.Annotation>>
getFieldInvariantDeclarationAnnotations()
Returns the set of classes of field invariant annotations.@Nullable FieldInvariants
getFieldInvariants(javax.lang.model.element.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(com.sun.source.tree.Tree tree)
Returns the functional interface and the function type that this lambda or member references targets.AnnotatedTypeMirror.AnnotatedExecutableType
getFunctionTypeFromTree(com.sun.source.tree.LambdaExpressionTree tree)
Returns the function type that this lambda targets.AnnotatedTypeMirror.AnnotatedExecutableType
getFunctionTypeFromTree(com.sun.source.tree.MemberReferenceTree tree)
Returns the function type that this member reference targets.protected @Nullable AnnotatedTypeMirror.AnnotatedDeclaredType
getImplicitReceiverType(com.sun.source.tree.ExpressionTree tree)
Return the implicit receiver type of an expression tree.AnnotatedTypeMirror
getIterableElementType(com.sun.source.tree.ExpressionTree expression)
Return the element type ofexpression
.protected AnnotatedTypeMirror
getIterableElementType(com.sun.source.tree.ExpressionTree expression, AnnotatedTypeMirror iterableType)
Return the element type ofiterableType
.AnnotatedTypeMirror
getMethodReturnType(com.sun.source.tree.MethodTree m)
Returns the return type of the methodm
.AnnotatedTypeMirror
getMethodReturnType(com.sun.source.tree.MethodTree m, com.sun.source.tree.ReturnTree r)
Returns the return type of the methodm
at the return statementr
.AnnotationMirrorSet
getNarrowedAnnotations(AnnotationMirrorSet annos, javax.lang.model.type.TypeKind typeKind, javax.lang.model.type.TypeKind narrowedTypeKind)
Returns annotations applicable to typenarrowedTypeKind
, that are copied or adapted fromannos
.AnnotatedTypeMirror.AnnotatedPrimitiveType
getNarrowedPrimitive(AnnotatedTypeMirror.AnnotatedPrimitiveType type, javax.lang.model.type.TypeMirror narrowedTypeMirror)
Returns AnnotatedPrimitiveType with underlying typenarrowedTypeMirror
and with annotations copied or adapted fromtype
.@Nullable com.sun.source.util.TreePath
getPath(com.sun.source.tree.Tree tree)
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.javax.annotation.processing.ProcessingEnvironment
getProcessingEnv()
Accessor for the processing environment.QualifierHierarchy
getQualifierHierarchy()
Returns the type qualifier hierarchy graph to be used by this processor.AnnotationMirrorSet
getQualifierParameterHierarchies(javax.lang.model.element.Element element)
Returns the set of top annotations representing all the hierarchies for which this element has a qualifier parameter.AnnotationMirrorSet
getQualifierParameterHierarchies(AnnotatedTypeMirror annotatedType)
Returns the set of top annotations representing all the hierarchies for which this type has a qualifier parameter.QualifierUpperBounds
getQualifierUpperBounds()
ReturnQualifierUpperBounds
for this type factory.@Nullable AnnotatedTypeMirror
getReceiverType(com.sun.source.tree.ExpressionTree expression)
Returns the receiver type of the expression tree, which might be the type of an implicitthis
.@Nullable AnnotatedTypeMirror.AnnotatedDeclaredType
getSelfType(com.sun.source.tree.Tree tree)
Returns the type ofthis
at the location oftree
.AnnotatedTypeMirror.AnnotatedDeclaredType
getStringType(AnnotatedTypeMirror type)
Returns AnnotatedDeclaredType with underlying type String and annotations copied from type.java.util.Set<@CanonicalName java.lang.String>
getSupportedTypeQualifierNames()
Returns an immutable set of the fully qualified names of the type qualifiers supported by this checker.java.util.Set<java.lang.Class<? extends java.lang.annotation.Annotation>>
getSupportedTypeQualifiers()
Returns an immutable set of the classes corresponding to the type qualifiers supported by this checker.com.sun.source.util.Trees
getTreeUtils()
Accessor for the tree utilities.TypeArgumentInference
getTypeArgumentInference()
AnnotationMirrorSet
getTypeDeclarationBounds(javax.lang.model.type.TypeMirror type)
Returns the set of qualifiers that are the upper bounds for a use of the type.TypeHierarchy
getTypeHierarchy()
AnnotatedTypeMirror
getTypeOfExtendsImplements(com.sun.source.tree.Tree clause)
Returns the type of the extends or implements clause.TypeVariableSubstitutor
getTypeVarSubstitutor()
AnnotatedTypeMirror.AnnotatedPrimitiveType
getUnboxedType(AnnotatedTypeMirror.AnnotatedDeclaredType type)
Returns the annotated primitive type of the given declared type if it is a boxed declared type.AnnotatedTypeMirror.AnnotatedWildcardType
getUninferredWildcardType(AnnotatedTypeMirror.AnnotatedTypeVariable typeVar)
Returns a wildcard type to be used as a type argument when the correct type could not be inferred.@Nullable com.sun.source.util.TreePath
getVisitorTreePath()
Returns the path to the tree that an external "visitor" is visiting.AnnotationMirrorSet
getWidenedAnnotations(AnnotationMirrorSet annos, javax.lang.model.type.TypeKind typeKind, javax.lang.model.type.TypeKind widenedTypeKind)
Returns annotations applicable to typewidenedTypeKind
, that are copied or adapted fromannos
.AnnotatedTypeMirror
getWidenedType(AnnotatedTypeMirror exprType, AnnotatedTypeMirror widenedType)
Returns a widened type if applicable, otherwise returns its first argument.AnnotatedTypeMirror
getWidenedType(AnnotationMirrorSet exprAnnos, javax.lang.model.type.TypeMirror exprTypeMirror, AnnotatedTypeMirror widenedType)
Applies widening if applicable, otherwise returns its first argument.boolean
hasExplicitNoQualifierParameterInHierarchy(javax.lang.model.element.Element element, javax.lang.model.element.AnnotationMirror top)
Returns whether theNoQualifierParameter
annotation was explicitly written onelement
for the hierarchy given bytop
.boolean
hasExplicitQualifierParameterInHierarchy(javax.lang.model.element.Element element, javax.lang.model.element.AnnotationMirror top)
Returns whether theHasQualifierParameter
annotation was explicitly written onelement
for the hierarchy given bytop
.boolean
hasQualifierParameterInHierarchy(@Nullable javax.lang.model.element.Element element, javax.lang.model.element.AnnotationMirror top)
Whether or not theelement
has a qualifier parameter.boolean
hasQualifierParameterInHierarchy(AnnotatedTypeMirror annotatedTypeMirror, javax.lang.model.element.AnnotationMirror top)
Whether or not theannotatedTypeMirror
has a qualifier parameter.protected void
initializeReflectionResolution()
Initialize reflection resolution.boolean
isFromByteCode(javax.lang.model.element.Element element)
Returns true if the element is from bytecode and the if the element did not appear in a stub file.boolean
isFromStubFile(javax.lang.model.element.Element element)
Returns true if the element appears in a stub file (Currently only works for methods, constructors, and fields).boolean
isImmutable(javax.lang.model.type.TypeMirror type)
Returns true if the type is immutable.boolean
isSideEffectFree(javax.lang.model.element.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
isSupportedQualifier(@Nullable javax.lang.model.element.AnnotationMirror a)
Returns true if the given annotation is a part of the type system under which this type factory operates.boolean
isSupportedQualifier(java.lang.Class<? extends java.lang.annotation.Annotation> clazz)
Returns true if the given class is a part of the type system under which this type factory operates.boolean
isSupportedQualifier(java.lang.String className)
Returns true if the given class name is a part of the type system under which this type factory operates.protected boolean
isWithinConstructor(com.sun.source.tree.Tree tree)
Returns true iftree
is within a constructor.protected AnnotatedTypeMirror
mergeAnnotationFileAnnosIntoType(@Nullable AnnotatedTypeMirror type, javax.lang.model.element.Element elt, AnnotationFileElementTypes source)
Merges types from annotation files forelt
intotype
by taking the greatest lower bound of the annotations in both.AnnotatedTypeFactory.ParameterizedExecutableType
methodFromUse(com.sun.source.tree.ExpressionTree tree, javax.lang.model.element.ExecutableElement methodElt, AnnotatedTypeMirror receiverType)
Determines the type of the invoked method based on the passed expression tree, executable element, and receiver type.AnnotatedTypeFactory.ParameterizedExecutableType
methodFromUse(com.sun.source.tree.MethodInvocationTree tree)
Determines the type of the invoked method based on the passed method invocation tree.protected void
methodFromUsePreSubstitution(com.sun.source.tree.ExpressionTree tree, AnnotatedTypeMirror.AnnotatedExecutableType type)
A callback method for the AnnotatedTypeFactory subtypes to customize the handling of the declared method type before type variable substitution.static java.lang.String
negateConstant(java.lang.String constantExpression)
Given an expression string, returns its negation.java.util.List<AnnotatedTypeMirror.AnnotatedTypeVariable>
order(java.util.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
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 optionvoid
postAsMemberOf(AnnotatedTypeMirror type, AnnotatedTypeMirror owner, javax.lang.model.element.Element element)
A callback method for the AnnotatedTypeFactory subtypes to customize AnnotatedTypes.asMemberOf().protected void
postDirectSuperTypes(AnnotatedTypeMirror type, java.util.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
postProcessClassTree(com.sun.source.tree.ClassTree tree)
Called byBaseTypeVisitor.visitClass(ClassTree, Void)
after the ClassTree has been type checked.void
preProcessClassTree(com.sun.source.tree.ClassTree classTree)
Called byBaseTypeVisitor.visitClass(ClassTree, Void)
before the classTree is type checked.void
replaceAnnotations(AnnotatedTypeMirror from, AnnotatedTypeMirror to)
Replaces or adds all annotations fromfrom
toto
.void
replaceAnnotations(AnnotatedTypeMirror from, AnnotatedTypeMirror to, javax.lang.model.element.AnnotationMirror top)
Replaces or adds annotations intop
's hierarchy fromfrom
toto
.void
setPathForArtificialTree(com.sun.source.tree.Tree tree, com.sun.source.util.TreePath path)
Set the tree path for the given artificial tree.void
setRoot(@Nullable com.sun.source.tree.CompilationUnitTree root)
Set the CompilationUnitTree that should be used.void
setVisitorTreePath(@Nullable com.sun.source.util.TreePath visitorTreePath)
Sets the path to the tree that an external "visitor" is visiting.boolean
shouldWarnIfStubRedundantWithBytecode()
Returns true if redundancy between a stub file and bytecode should be reported.protected AnnotatedTypeMirror
toAnnotatedType(javax.lang.model.type.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)
.java.lang.String
toString()
protected AnnotatedTypeMirror
type(com.sun.source.tree.Tree tree)
Determines an empty annotated type of the given tree.java.util.List<AnnotatedTypeParameterBounds>
typeVariablesFromUse(AnnotatedTypeMirror.AnnotatedDeclaredType type, javax.lang.model.element.TypeElement element)
Adapt the upper bounds of the type variables of a class relative to the type instantiation.
-
-
-
Field Detail
-
trees
protected final com.sun.source.util.Trees trees
TheTrees
instance to use for tree node path finding.
-
root
protected @Nullable com.sun.source.tree.CompilationUnitTree root
Optional! The AST of the source file being operated on.
-
processingEnv
protected final javax.annotation.processing.ProcessingEnvironment processingEnv
The processing environment to use for accessing compiler internals.
-
elements
protected final javax.lang.model.util.Elements elements
Utility class for working withElement
s.
-
types
public final javax.lang.model.util.Types types
Utility class for working withTypeMirror
s.
-
annotatedForValueElement
protected final javax.lang.model.element.ExecutableElement annotatedForValueElement
The AnnotatedFor.value argument/element.
-
ensuresQualifierExpressionElement
protected final javax.lang.model.element.ExecutableElement ensuresQualifierExpressionElement
The EnsuresQualifier.expression field/element.
-
ensuresQualifierListValueElement
protected final javax.lang.model.element.ExecutableElement ensuresQualifierListValueElement
The EnsuresQualifier.List.value field/element.
-
ensuresQualifierIfExpressionElement
protected final javax.lang.model.element.ExecutableElement ensuresQualifierIfExpressionElement
The EnsuresQualifierIf.expression field/element.
-
ensuresQualifierIfResultElement
protected final javax.lang.model.element.ExecutableElement ensuresQualifierIfResultElement
The EnsuresQualifierIf.result argument/element.
-
ensuresQualifierIfListValueElement
protected final javax.lang.model.element.ExecutableElement ensuresQualifierIfListValueElement
The EnsuresQualifierIf.List.value field/element.
-
fieldInvariantFieldElement
protected final javax.lang.model.element.ExecutableElement fieldInvariantFieldElement
The FieldInvariant.field argument/element.
-
fieldInvariantQualifierElement
protected final javax.lang.model.element.ExecutableElement fieldInvariantQualifierElement
The FieldInvariant.qualifier argument/element.
-
hasQualifierParameterValueElement
protected final javax.lang.model.element.ExecutableElement hasQualifierParameterValueElement
The HasQualifierParameter.value field/element.
-
methodValClassNameElement
public final javax.lang.model.element.ExecutableElement methodValClassNameElement
The MethodVal.className argument/element.
-
methodValMethodNameElement
public final javax.lang.model.element.ExecutableElement methodValMethodNameElement
The MethodVal.methodName argument/element.
-
methodValParamsElement
public final javax.lang.model.element.ExecutableElement methodValParamsElement
The MethodVal.params argument/element.
-
noQualifierParameterValueElement
protected final javax.lang.model.element.ExecutableElement noQualifierParameterValueElement
The NoQualifierParameter.value field/element.
-
requiresQualifierExpressionElement
protected final javax.lang.model.element.ExecutableElement requiresQualifierExpressionElement
The RequiresQualifier.expression field/element.
-
requiresQualifierListValueElement
protected final javax.lang.model.element.ExecutableElement requiresQualifierListValueElement
The RequiresQualifier.List.value field/element.
-
requiresQualifierTM
protected final javax.lang.model.type.TypeMirror requiresQualifierTM
The RequiresQualifier type.
-
requiresQualifierListTM
protected final javax.lang.model.type.TypeMirror requiresQualifierListTM
The RequiresQualifier.List type.
-
ensuresQualifierTM
protected final javax.lang.model.type.TypeMirror ensuresQualifierTM
The EnsuresQualifier type.
-
ensuresQualifierListTM
protected final javax.lang.model.type.TypeMirror ensuresQualifierListTM
The EnsuresQualifier.List type.
-
ensuresQualifierIfTM
protected final javax.lang.model.type.TypeMirror ensuresQualifierIfTM
The EnsuresQualifierIf type.
-
ensuresQualifierIfListTM
protected final javax.lang.model.type.TypeMirror ensuresQualifierIfListTM
The EnsuresQualifierIf.List type.
-
qualHierarchy
protected QualifierHierarchy qualHierarchy
Represent the annotation relations.
-
typeHierarchy
protected TypeHierarchy typeHierarchy
Represent the type relations.
-
viewpointAdapter
protected @Nullable ViewpointAdapter viewpointAdapter
Viewpoint adapter used to perform viewpoint adaptation or null
-
typeFormatter
protected final AnnotatedTypeFormatter 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
protected QualifierUpperBounds qualifierUpperBounds
Holds the qualifier upper bounds for type uses.
-
typeVarSubstitutor
protected TypeVariableSubstitutor 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
protected TypeArgumentInference typeArgumentInference
Provides utility method to infer type arguments.
-
stubTypes
public final AnnotationFileElementTypes stubTypes
Parses stub files and stores annotations on public elements from stub files.
-
ajavaTypes
public final AnnotationFileElementTypes ajavaTypes
Parses ajava files and stores annotations on public elements from ajava files.
-
currentFileAjavaTypes
protected @Nullable AnnotationFileElementTypes 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
protected final BaseTypeChecker checker
The checker to use for option handling and resource management.
-
uid
public final int uid
Unique ID of the current object; for debugging purposes.
-
reflectionResolver
protected ReflectionResolver reflectionResolver
Object that is used to resolve reflective method calls, if reflection resolution is turned on.
-
loader
protected AnnotationClassLoader loader
This loads type annotation classes via reflective lookup.
-
shouldCache
public boolean shouldCache
Should 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
protected final java.util.Map<com.sun.source.tree.Tree,AnnotatedTypeMirror> fromExpressionTreeCache
Mapping from an expression tree to its annotated type; before defaults are applied, just what the programmer wrote.
-
fromMemberTreeCache
protected final java.util.Map<com.sun.source.tree.Tree,AnnotatedTypeMirror> fromMemberTreeCache
Mapping from a member tree to its annotated type; before defaults are applied, just what the programmer wrote.
-
fromTypeTreeCache
protected final java.util.Map<com.sun.source.tree.Tree,AnnotatedTypeMirror> fromTypeTreeCache
Mapping from a type tree to its annotated type; before defaults are applied, just what the programmer wrote.
-
ignoreUninferredTypeArguments
public final boolean ignoreUninferredTypeArguments
Whether to ignore uninferred type arguments. This is a temporary flag to work around Issue 979.
-
objectGetClass
protected final javax.lang.model.element.ExecutableElement objectGetClass
The Object.getClass method.
-
-
Constructor Detail
-
AnnotatedTypeFactory
public AnnotatedTypeFactory(BaseTypeChecker checker)
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 Detail
-
postInit
protected void postInit(@UnderInitialization(AnnotatedTypeFactory.class) AnnotatedTypeFactory this)
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
public BaseTypeChecker getChecker()
Returns the checker associated with this factory.- Returns:
- the checker associated with this factory
-
getCheckerNames
public java.util.List<java.lang.String> getCheckerNames()
Returns the names of the annotation processors that are being run.- Returns:
- the names of the annotation processors that are being run
-
createQualifierUpperBounds
protected QualifierUpperBounds createQualifierUpperBounds()
CreatesQualifierUpperBounds
for this type factory.- Returns:
- a new
QualifierUpperBounds
for this type factory
-
getQualifierUpperBounds
public QualifierUpperBounds getQualifierUpperBounds()
ReturnQualifierUpperBounds
for this type factory.- Returns:
QualifierUpperBounds
for this type factory
-
initializeReflectionResolution
protected void initializeReflectionResolution()
Initialize reflection resolution.
-
setRoot
public void setRoot(@Nullable com.sun.source.tree.CompilationUnitTree root)
Set the CompilationUnitTree that should be used.- Parameters:
root
- the new compilation unit to use
-
toString
@SideEffectFree public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
createQualifierHierarchy
protected QualifierHierarchy 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
public final QualifierHierarchy getQualifierHierarchy()
Returns the type qualifier hierarchy graph to be used by this processor.- Returns:
- the
QualifierHierarchy
for this checker - See Also:
createQualifierHierarchy()
-
createTypeHierarchy
protected TypeHierarchy 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
public final TypeHierarchy getTypeHierarchy()
-
createViewpointAdapter
protected @Nullable ViewpointAdapter createViewpointAdapter()
Factory method to create a ViewpointAdapter. Subclasses should implement and instantiate a ViewpointAdapter subclass if viewpoint adaptation is needed for a type system.- Returns:
- viewpoint adapter to perform viewpoint adaptation or null
-
createTypeVariableSubstitutor
protected TypeVariableSubstitutor createTypeVariableSubstitutor()
TypeVariableSubstitutor provides a method to replace type parameters with their arguments.
-
getTypeVarSubstitutor
public TypeVariableSubstitutor getTypeVarSubstitutor()
-
createTypeArgumentInference
protected TypeArgumentInference createTypeArgumentInference()
TypeArgumentInference infers the method type arguments when they are not explicitly written.
-
getTypeArgumentInference
public TypeArgumentInference getTypeArgumentInference()
-
createAnnotationClassLoader
protected AnnotationClassLoader 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
protected java.util.Set<java.lang.Class<? extends java.lang.annotation.Annotation>> createSupportedTypeQualifiers()
Returns a mutable set of annotation classes that are supported by a checker.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 java.util.Set<java.lang.Class<? extends java.lang.annotation.Annotation>> getBundledTypeQualifiers(java.lang.Class<? extends java.lang.annotation.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
protected AnnotatedTypeFormatter 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
public AnnotatedTypeFormatter getAnnotatedTypeFormatter()
-
createAnnotationFormatter
protected AnnotationFormatter createAnnotationFormatter()
-
getAnnotationFormatter
public AnnotationFormatter getAnnotationFormatter()
-
getSupportedTypeQualifiers
public final java.util.Set<java.lang.Class<? extends java.lang.annotation.Annotation>> 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:
createSupportedTypeQualifiers()
-
getSupportedTypeQualifierNames
public final java.util.Set<@CanonicalName java.lang.String> 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:
createSupportedTypeQualifiers()
-
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
public AnnotatedTypeMirror getAnnotatedType(javax.lang.model.element.Element elt)
Returns an AnnotatedTypeMirror representing the annotated type ofelt
.- Parameters:
elt
- the element- Returns:
- the annotated type of
elt
-
getAnnotatedType
public AnnotatedTypeMirror getAnnotatedType(java.lang.Class<?> clazz)
Returns an AnnotatedTypeMirror representing the annotated type ofclazz
.- Parameters:
clazz
- a class- Returns:
- the annotated type of
clazz
-
getAnnotationMirror
public @Nullable javax.lang.model.element.AnnotationMirror getAnnotationMirror(com.sun.source.tree.Tree tree, java.lang.Class<? extends java.lang.annotation.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
public AnnotatedTypeMirror getAnnotatedType(com.sun.source.tree.Tree tree)
Returns an AnnotatedTypeMirror representing the annotated type oftree
.- Parameters:
tree
- the AST node- Returns:
- the annotated type of
tree
-
preProcessClassTree
public void preProcessClassTree(com.sun.source.tree.ClassTree classTree)
Called byBaseTypeVisitor.visitClass(ClassTree, Void)
before the classTree is type checked.- Parameters:
classTree
- the class on which to perform preprocessing
-
postProcessClassTree
public void postProcessClassTree(com.sun.source.tree.ClassTree tree)
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
public AnnotatedTypeMirror getAnnotatedTypeFromTypeTree(com.sun.source.tree.Tree tree)
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
public AnnotationMirrorSet getTypeDeclarationBounds(javax.lang.model.type.TypeMirror type)
Returns the set of qualifiers that are the upper bounds for a use of the type.For a specific type system, the type declaration bound is retrieved in the following precedence: (1) the annotation on the type declaration bound (2) if an annotation with
@UpperBoundFor
mentions the type or the type kind, use that annotation (3) the top annotation- 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
-
getAnnotationOrTypeDeclarationBound
public AnnotationMirrorSet getAnnotationOrTypeDeclarationBound(javax.lang.model.type.TypeMirror type, java.util.Set<? extends javax.lang.model.element.AnnotationMirror> annos)
Compare the givenannos
with the declaration bounds oftype
and return the appropriate qualifiers. For each qualifier inannos
, if it is a subtype of the declaration bound in the same hierarchy, it will be added to the result; otherwise, the declaration bound will be added to the result instead.- Parameters:
type
- java type that specifies the qualifier upper boundannos
- a set of qualifiers to be compared with the declaration bounds oftype
- Returns:
- the modified
annos
after applying the rules described above
-
getDefaultTypeDeclarationBounds
protected AnnotationMirrorSet 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
public AnnotatedTypeMirror getTypeOfExtendsImplements(com.sun.source.tree.Tree clause)
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
public AnnotatedTypeMirror fromElement(javax.lang.model.element.Element elt)
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, javax.lang.model.element.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
protected void addComputedTypeAnnotations(com.sun.source.tree.Tree tree, AnnotatedTypeMirror type)
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
protected void addComputedTypeAnnotations(javax.lang.model.element.Element elt, AnnotatedTypeMirror type)
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
public void addDefaultAnnotations(AnnotatedTypeMirror type)
Adds default annotations totype
. This method should only be used in places where the correct annotations cannot be computed because of uninferred type arguments. (SeeAnnotatedTypeMirror.AnnotatedWildcardType.isUninferredTypeArgument()
.)- Parameters:
type
- annotated type to which default annotations are added
-
postDirectSuperTypes
protected void postDirectSuperTypes(AnnotatedTypeMirror type, java.util.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
public void postAsMemberOf(AnnotatedTypeMirror type, AnnotatedTypeMirror owner, javax.lang.model.element.Element element)
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, javax.lang.model.element.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
public @Nullable FieldInvariants getFieldInvariants(javax.lang.model.element.TypeElement element)
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 com.sun.source.tree.AnnotationTree getFieldInvariantAnnotationTree(@Nullable java.util.List<? extends com.sun.source.tree.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
protected java.util.Set<java.lang.Class<? extends java.lang.annotation.Annotation>> getFieldInvariantDeclarationAnnotations()
Returns the set of classes of field invariant annotations.- Returns:
- the set of classes of field invariant annotations
-
typeVariablesFromUse
public java.util.List<AnnotatedTypeParameterBounds> typeVariablesFromUse(AnnotatedTypeMirror.AnnotatedDeclaredType type, javax.lang.model.element.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(java.util.Set<? extends javax.lang.model.element.AnnotationMirror> annotations)
Creates and returns an AnnotatedNullType qualified withannotations
.- Parameters:
annotations
- set of AnnotationMirrors to qualify the returned type with- Returns:
- AnnotatedNullType qualified with
annotations
-
getImplicitReceiverType
protected @Nullable AnnotatedTypeMirror.AnnotatedDeclaredType getImplicitReceiverType(com.sun.source.tree.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
public @Nullable AnnotatedTypeMirror.AnnotatedDeclaredType getSelfType(com.sun.source.tree.Tree tree)
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
public @Nullable com.sun.source.tree.Tree getEnclosingClassOrMethod(com.sun.source.tree.Tree tree)
Returns the innermost enclosing method or class tree oftree
. Since artificial trees are assigned to be the child node of the original tree, their enclosing trees are found the same way as normal trees.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(javax.lang.model.element.TypeElement typeElement, com.sun.source.tree.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(javax.lang.model.element.TypeElement typeElement, com.sun.source.tree.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
public final @Nullable AnnotatedTypeMirror getReceiverType(com.sun.source.tree.ExpressionTree expression)
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 AnnotatedTypeFactory.ParameterizedExecutableType methodFromUse(com.sun.source.tree.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 method type being invoked with tree and the (inferred) type arguments
-
methodFromUse
public AnnotatedTypeFactory.ParameterizedExecutableType methodFromUse(com.sun.source.tree.ExpressionTree tree, javax.lang.model.element.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 method type being invoked with tree and the (inferred) type arguments
- See Also:
methodFromUse(MethodInvocationTree)
-
methodFromUsePreSubstitution
protected void methodFromUsePreSubstitution(com.sun.source.tree.ExpressionTree tree, AnnotatedTypeMirror.AnnotatedExecutableType type)
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 substitution
-
adaptGetClassReturnTypeToReceiver
protected void adaptGetClassReturnTypeToReceiver(AnnotatedTypeMirror.AnnotatedExecutableType getClassType, AnnotatedTypeMirror receiverType, com.sun.source.tree.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
public AnnotatedTypeMirror getIterableElementType(com.sun.source.tree.ExpressionTree expression)
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(com.sun.source.tree.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
public AnnotatedTypeFactory.ParameterizedExecutableType constructorFromUse(com.sun.source.tree.NewClassTree tree)
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
-
getEnumConstructorQualifiers
protected java.util.Set<javax.lang.model.element.AnnotationMirror> 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
-
fromNewClass
@Deprecated public AnnotatedTypeMirror.AnnotatedDeclaredType fromNewClass(com.sun.source.tree.NewClassTree newClassTree)
Deprecated.Creates an AnnotatedDeclaredType for a NewClassTree. Only adds explicit annotations, unless newClassTree has a diamond operator. In that case, the annotations on the type arguments are inferred using the assignment context and contain defaults.(Subclass beside
GenericAnnotatedTypeFactory
should not override this method.)- Parameters:
newClassTree
- a NewClassTree- Returns:
- the AnnotatedDeclaredType
-
getExplicitNewClassAnnos
public AnnotationMirrorSet getExplicitNewClassAnnos(com.sun.source.tree.NewClassTree newClassTree)
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
protected java.util.List<AnnotatedTypeMirror> getExplicitNewClassClassTypeArgs(com.sun.source.tree.NewClassTree newClass)
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(com.sun.source.tree.NewClassTree tree, AnnotatedTypeMirror.AnnotatedExecutableType type)
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 substitution
-
getMethodReturnType
public AnnotatedTypeMirror getMethodReturnType(com.sun.source.tree.MethodTree m)
Returns the return type of the methodm
.- Parameters:
m
- tree of a method declaration- Returns:
- the return type of the method
-
getMethodReturnType
public AnnotatedTypeMirror getMethodReturnType(com.sun.source.tree.MethodTree m, com.sun.source.tree.ReturnTree r)
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
public final AnnotatedTypeMirror.AnnotatedPrimitiveType applyUnboxing(AnnotatedTypeMirror type)
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 java.lang.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:
java.lang.IllegalArgumentException
- if the type given has no unbox conversion
-
getStringType
public AnnotatedTypeMirror.AnnotatedDeclaredType getStringType(AnnotatedTypeMirror type)
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, javax.lang.model.type.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, javax.lang.model.type.TypeKind typeKind, javax.lang.model.type.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, javax.lang.model.type.TypeKind typeKind, javax.lang.model.type.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(com.sun.source.tree.BinaryTree tree)
Returns the types of the two arguments to the BinaryTree. Please refer tobinaryTreeArgTypes(TypeMirror, AnnotatedTypeMirror, AnnotatedTypeMirror)
)} for more details.- Parameters:
tree
- a binary tree- Returns:
- the types of the two arguments
-
compoundAssignmentTreeArgTypes
public org.plumelib.util.IPair<AnnotatedTypeMirror,AnnotatedTypeMirror> compoundAssignmentTreeArgTypes(com.sun.source.tree.CompoundAssignmentTree tree)
Returns the types of the two arguments to the CompoundAssignmentTree. Please refer tobinaryTreeArgTypes(TypeMirror, AnnotatedTypeMirror, AnnotatedTypeMirror)
) for more details.- Parameters:
tree
- a compound assignment tree- Returns:
- the types of the two arguments
-
binaryTreeArgTypes
protected org.plumelib.util.IPair<AnnotatedTypeMirror,AnnotatedTypeMirror> binaryTreeArgTypes(javax.lang.model.type.TypeMirror resultType, AnnotatedTypeMirror left, AnnotatedTypeMirror right)
Returns the types of the two arguments to a binary operation. There are two special cases:1. If both operands have numeric type, widening and unboxing will be applied accordingly.
2. If we have a non-string operand in a string concatenation (i.e., result is a string), we will always return a string ATM for the operand. The resulting ATM will have the original annotations with the declaration bounds of string type applied. Please check
getAnnotationOrTypeDeclarationBound(javax.lang.model.type.TypeMirror, java.util.Set<? extends javax.lang.model.element.AnnotationMirror>)
for more details.- Parameters:
resultType
- the type of the result of a binary operationleft
- 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
-
binaryTreeArgTypes
@Deprecated public org.plumelib.util.IPair<AnnotatedTypeMirror,AnnotatedTypeMirror> binaryTreeArgTypes(AnnotatedTypeMirror left, AnnotatedTypeMirror right)
Deprecated.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, javax.lang.model.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
public final AnnotatedTypeMirror.AnnotatedDeclaredType getAnnotatedType(com.sun.source.tree.ClassTree tree)
- See Also:
getAnnotatedType(Tree)
-
getAnnotatedType
public final AnnotatedTypeMirror.AnnotatedDeclaredType getAnnotatedType(com.sun.source.tree.NewClassTree tree)
- See Also:
getAnnotatedType(Tree)
-
getAnnotatedType
public final AnnotatedTypeMirror.AnnotatedArrayType getAnnotatedType(com.sun.source.tree.NewArrayTree tree)
- See Also:
getAnnotatedType(Tree)
-
getAnnotatedType
public final AnnotatedTypeMirror.AnnotatedExecutableType getAnnotatedType(com.sun.source.tree.MethodTree tree)
- See Also:
getAnnotatedType(Tree)
-
getAnnotatedType
public final AnnotatedTypeMirror.AnnotatedDeclaredType getAnnotatedType(javax.lang.model.element.TypeElement elt)
- See Also:
getAnnotatedType(Element)
-
getAnnotatedType
public final AnnotatedTypeMirror.AnnotatedExecutableType getAnnotatedType(javax.lang.model.element.ExecutableElement elt)
- See Also:
getAnnotatedType(Element)
-
fromElement
public final AnnotatedTypeMirror.AnnotatedDeclaredType fromElement(javax.lang.model.element.TypeElement elt)
SeefromElement(Element)
.- See Also:
fromElement(Element)
-
fromElement
public final AnnotatedTypeMirror.AnnotatedExecutableType fromElement(javax.lang.model.element.ExecutableElement elt)
SeefromElement(Element)
.- See Also:
fromElement(Element)
-
isSupportedQualifier
@EnsuresNonNullIf(expression="#1", result=true) public boolean isSupportedQualifier(@Nullable javax.lang.model.element.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
public boolean isSupportedQualifier(java.lang.Class<? extends java.lang.annotation.Annotation> clazz)
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
public boolean isSupportedQualifier(java.lang.String className)
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
protected void addAliasedTypeAnnotation(java.lang.Class<?> aliasClass, javax.lang.model.element.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.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 java.lang.String aliasName, javax.lang.model.element.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(java.lang.Class<?> aliasClass, java.lang.Class<?> canonicalClass, boolean copyElements, java.lang.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 java.lang.String aliasName, java.lang.Class<?> canonicalAnno, boolean copyElements, java.lang.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
public @Nullable javax.lang.model.element.AnnotationMirror canonicalAnnotation(javax.lang.model.element.AnnotationMirror a)
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(java.lang.Class<? extends java.lang.annotation.Annotation> alias, java.lang.Class<? extends java.lang.annotation.Annotation> annotation, javax.lang.model.element.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
-
addAliasedDeclAnnotation
protected void addAliasedDeclAnnotation(@FullyQualifiedName java.lang.String alias, @FullyQualifiedName java.lang.String annotation, javax.lang.model.element.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 fully-qualified name of the alias annotationannotation
- the fully-qualified name of the canonical annotationannotationToUse
- the annotation mirror to use
-
addInheritedAnnotation
protected void addInheritedAnnotation(javax.lang.model.element.AnnotationMirror annotation)
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
protected final AnnotatedTypeMirror toAnnotatedType(javax.lang.model.type.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)
.- 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
protected final AnnotatedTypeMirror type(com.sun.source.tree.Tree tree)
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
public final @Nullable com.sun.source.tree.Tree declarationFromElement(javax.lang.model.element.Element elt)
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
-
getCurrentClassTree
@Deprecated protected final com.sun.source.tree.ClassTree getCurrentClassTree(com.sun.source.tree.Tree tree)
Deprecated.UseTreePathUtil.enclosingClass(getPath(tree))
instead.Returns the class tree enclosingtree
.- Parameters:
tree
- the tree whose enclosing class is returned- Returns:
- the class tree enclosing
tree
-
getCurrentMethodReceiver
@Deprecated protected final @Nullable AnnotatedTypeMirror.AnnotatedDeclaredType getCurrentMethodReceiver(com.sun.source.tree.Tree tree)
Deprecated.UsegetSelfType(Tree)
insteadReturns the receiver type of the method enclosingtree
.The method uses the parameter only if the most enclosing method cannot be found directly.
- Parameters:
tree
- the tree used to find the enclosing method- Returns:
- receiver type of the most enclosing method being visited
-
isWithinConstructor
protected final boolean isWithinConstructor(com.sun.source.tree.Tree tree)
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
public void setVisitorTreePath(@Nullable com.sun.source.util.TreePath visitorTreePath)
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
public @Nullable com.sun.source.util.TreePath 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
public final @Nullable com.sun.source.util.TreePath getPath(@FindDistinct com.sun.source.tree.Tree tree)
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.
- 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.
-
setPathForArtificialTree
public final void setPathForArtificialTree(com.sun.source.tree.Tree tree, com.sun.source.util.TreePath path)
Set the tree path for the given artificial tree.See
org.checkerframework.framework.flow.CFCFGBuilder.CFCFGTranslationPhaseOne.handleArtificialTree(Tree)
.- Parameters:
tree
- the artificialTree
to set the path forpath
- theTreePath
for the artificial tree
-
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
public final javax.lang.model.element.AnnotationMirror getDeclAnnotation(javax.lang.model.element.Element elt, java.lang.Class<? extends java.lang.annotation.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, (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(javax.lang.model.element.Element, java.lang.Class<? extends java.lang.annotation.Annotation>)
-
getDeclAnnotationNoAliases
public final @Nullable javax.lang.model.element.AnnotationMirror getDeclAnnotationNoAliases(javax.lang.model.element.Element elt, java.lang.Class<? extends java.lang.annotation.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:
getDeclAnnotation(javax.lang.model.element.Element, java.lang.Class<? extends java.lang.annotation.Annotation>)
-
isFromStubFile
public boolean isFromStubFile(javax.lang.model.element.Element element)
Returns true if the element appears in a stub file (Currently only works for methods, constructors, and fields).
-
isFromByteCode
public boolean isFromByteCode(javax.lang.model.element.Element element)
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
public AnnotationMirrorSet getDeclAnnotations(javax.lang.model.element.Element elt)
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 java.util.List<org.plumelib.util.IPair<javax.lang.model.element.AnnotationMirror,javax.lang.model.element.AnnotationMirror>> getDeclAnnotationWithMetaAnnotation(javax.lang.model.element.Element element, java.lang.Class<? extends java.lang.annotation.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 java.util.List<org.plumelib.util.IPair<javax.lang.model.element.AnnotationMirror,javax.lang.model.element.AnnotationMirror>> getAnnotationWithMetaAnnotation(javax.lang.model.element.Element element, java.lang.Class<? extends java.lang.annotation.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, javax.lang.model.element.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
public boolean hasQualifierParameterInHierarchy(@Nullable javax.lang.model.element.Element element, javax.lang.model.element.AnnotationMirror top)
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
public boolean hasExplicitQualifierParameterInHierarchy(javax.lang.model.element.Element element, javax.lang.model.element.AnnotationMirror top)
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
public boolean hasExplicitNoQualifierParameterInHierarchy(javax.lang.model.element.Element element, javax.lang.model.element.AnnotationMirror top)
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
public AnnotationMirrorSet getQualifierParameterHierarchies(AnnotatedTypeMirror annotatedType)
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
public AnnotationMirrorSet getQualifierParameterHierarchies(javax.lang.model.element.Element element)
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
public void replaceAnnotations(AnnotatedTypeMirror from, AnnotatedTypeMirror to)
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, javax.lang.model.element.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
-
containsUninferredTypeArguments
public boolean containsUninferredTypeArguments(AnnotatedTypeMirror type)
Returns whether this type or any component type is a wildcard type for which Java 7 type inference is insufficient. See issue 979, or the documentation on AnnotatedWildcardType.- Parameters:
type
- type to check- Returns:
- whether this type or any component type is a wildcard type for which Java 7 type inference is insufficient
-
getUninferredWildcardType
public AnnotatedTypeMirror.AnnotatedWildcardType getUninferredWildcardType(AnnotatedTypeMirror.AnnotatedTypeVariable typeVar)
Returns a wildcard type to be used as a type argument when the correct type could not be inferred. The wildcard will be marked as an uninferred wildcard so thatAnnotatedTypeMirror.AnnotatedWildcardType.isUninferredTypeArgument()
returns true.This method should only be used by type argument inference. org.checkerframework.framework.util.AnnotatedTypes.inferTypeArguments(ProcessingEnvironment, AnnotatedTypeFactory, ExpressionTree, ExecutableElement)
- Parameters:
typeVar
- the TypeVariable that could not be inferred- Returns:
- a wildcard that is marked as an uninferred type argument
-
getFunctionTypeFromTree
public AnnotatedTypeMirror.AnnotatedExecutableType getFunctionTypeFromTree(com.sun.source.tree.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(com.sun.source.tree.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(com.sun.source.tree.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
public AnnotatedTypeMirror applyCaptureConversion(AnnotatedTypeMirror typeToCapture)
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
public AnnotatedTypeMirror applyCaptureConversion(AnnotatedTypeMirror type, javax.lang.model.type.TypeMirror typeMirror)
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 java.util.List<AnnotatedTypeMirror.AnnotatedTypeVariable> order(java.util.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
public final javax.lang.model.util.Elements getElementUtils()
Returns the utility class for working withElement
s.- Returns:
- the utility class for working with
Element
s
-
getTreeUtils
public com.sun.source.util.Trees getTreeUtils()
Accessor for the tree utilities.
-
getProcessingEnv
public javax.annotation.processing.ProcessingEnvironment getProcessingEnv()
Accessor for the processing environment.- Returns:
- the processing environment
-
getExpressionAndOffset
public static org.plumelib.util.IPair<java.lang.String,java.lang.String> getExpressionAndOffset(java.lang.String expression)
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
public static java.lang.String negateConstant(java.lang.String constantExpression)
Given an expression string, returns its negation.- Parameters:
constantExpression
- a string representing an integer constant- Returns:
- the negation of constantExpression
-
getDummyAssignedTo
public @Nullable AnnotatedTypeMirror getDummyAssignedTo(com.sun.source.tree.ExpressionTree expressionTree)
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
public boolean areSameByClass(javax.lang.model.element.AnnotationMirror am, java.lang.Class<? extends java.lang.annotation.Annotation> annoClass)
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(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c, java.lang.Class<? extends java.lang.annotation.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 javax.lang.model.element.AnnotationMirror getAnnotationByClass(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c, java.lang.Class<? extends java.lang.annotation.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
-
doesAnnotatedForApplyToThisChecker
public boolean doesAnnotatedForApplyToThisChecker(javax.lang.model.element.AnnotationMirror annotatedForAnno)
Doesanno
, which is anAnnotatedFor
annotation, apply to this checker?- Parameters:
annotatedForAnno
- anAnnotatedFor
annotation- Returns:
- whether
anno
applies to this checker
-
getContractExpressions
public java.util.List<java.lang.String> getContractExpressions(javax.lang.model.element.AnnotationMirror contractAnno)
Get theexpression
field/element of the given contract annotation.- Parameters:
contractAnno
- aRequiresQualifier
,EnsuresQualifier
, orEnsuresQualifier
- Returns:
- the
expression
field/element of the given annotation
-
getContractListValues
public java.util.List<javax.lang.model.element.AnnotationMirror> getContractListValues(javax.lang.model.element.AnnotationMirror contractListAnno)
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
public boolean isImmutable(javax.lang.model.type.TypeMirror type)
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
public boolean isSideEffectFree(javax.lang.model.element.ExecutableElement methodElement)
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
-
-