public abstract class BaseTypeChecker extends SourceChecker
SourceChecker
that provides a simple SourceVisitor
implementation for typical assignment and
pseudo-assignment checking of annotated types. Pseudo-assignment checks
include method overriding checks, parameter passing, and method invocation.
Most type-checker plug-ins will want to extend this class, instead of
SourceChecker
. Checkers which require annotated types but not
subtype checking (e.g. for testing purposes)
should extend SourceChecker
.
Non-type checkers (e.g. checkers to enforce coding
styles) should extend SourceChecker
or AbstractProcessor
directly; the Checker Framework is not designed for such checkers.
It is a convention that, for a type system Foo, the checker, the visitor, and the annotated type factory are named as FooChecker, FooVisitor, and FooAnnotatedTypeFactory. Some factory methods uses this convention to construct the appropriate classes reflectively.
BaseTypeChecker
encapsulates a group for factories for various
representations/classes related the type system, mainly:
QualifierHierarchy
:
to represent the supported qualifiers in addition to their hierarchy,
mainly, subtyping rulesTypeHierarchy
:
to check subtyping rules between annotated types rather than qualifiersAnnotatedTypeFactory
:
to construct qualified types enriched with implicit qualifiers
according to the type system rulesBaseTypeVisitor
:
to visit the compiled Java files and check for violations of the type
system rules
Subclasses must specify the set of type qualifiers they support either by
annotating the subclass with TypeQualifiers
or by overriding the
getSupportedTypeQualifiers()
method.
If the specified type qualifiers are meta-annotated with SubtypeOf
,
this implementation will automatically construct the type qualifier
hierarchy. Otherwise, or if this behavior must be overridden, the subclass
may override the createQualifierHierarchy()
method.
checkers.quals
SourceChecker.CheckerError
currentPath, currentRoot, env, messager, messages, trees
processingEnv
Constructor and Description |
---|
BaseTypeChecker() |
Modifier and Type | Method and Description |
---|---|
AnnotatedTypeFactory |
createFactory(@Nullable CompilationUnitTree root)
Constructs an instance of the appropriate type factory for the
implemented type system.
|
protected @Nullable QualifierHierarchy |
createQualifierHierarchy()
Returns the type qualifier hierarchy graph to be used by this processor.
|
protected MultiGraphQualifierHierarchy.MultiGraphFactory |
createQualifierHierarchyFactory()
Factory method to easily change what Factory is used to
create a QualifierHierarchy.
|
protected SourceVisitor<?,?> |
createSourceVisitor(@Nullable CompilationUnitTree root)
Returns the appropriate visitor that type checks the compilation unit
according to the type system rules.
|
protected Set<Class<? extends Annotation>> |
createSupportedTypeQualifiers()
If the checker class is annotated with
TypeQualifiers , return an immutable set with the same set
of classes as the annotation. |
protected TypeHierarchy |
createTypeHierarchy()
Creates the type subtyping checker using the current type qualifier
hierarchy.
|
@Nullable QualifierHierarchy |
getQualifierHierarchy()
Returns the type qualifier hierarchy graph to be used by this processor.
|
Set<@ReadOnly String> |
getSupportedLintOptions()
Specify 'flow' and 'cast' as supported lint options for all Type checkers.
|
Set<Class<? extends Annotation>> |
getSupportedTypeQualifiers()
Returns an immutable set of the type qualifiers supported by this
checker.
|
void |
initChecker(ProcessingEnvironment processingEnv)
Initialize the checker.
|
static <T extends @Nullable Object> |
invokeConstructorFor(@ReadOnly String name,
Class<?>[] paramTypes,
Object[] args)
Invokes the constructor belonging to the class
named by
name having the given parameter types on the given
arguments. |
boolean |
isAssignable(@Mutable AnnotatedTypeMirror varType,
@Mutable AnnotatedTypeMirror receiverType,
@Nullable Tree variable,
AnnotatedTypeFactory factory)
Tests whether the variable accessed is an assignable variable or not,
given the current scope
TODO: document which parameters are nullable; e.g.
|
boolean |
isSubtype(@Mutable AnnotatedTypeMirror sub,
@Mutable AnnotatedTypeMirror sup)
Tests whether one annotated type is a subtype of another, with
respect to the annotations on these types.
|
errorAbort, errorAbort, formatStackTrace, fullMessageOf, getLintOption, getLintOption, getMessages, getProcessingEnvironment, getSupportedAnnotationTypes, getSupportedOptions, getSupportedSourceVersion, getSuppressWarningsKey, init, message, report, shouldSkipDefs, shouldSkipDefs, shouldSkipUses, typeProcess
process, typeProcessingOver
getCompletions, isInitialized, toString
public void initChecker(ProcessingEnvironment processingEnv)
SourceChecker
initChecker
in class SourceChecker
AbstractProcessor.init(ProcessingEnvironment)
protected Set<Class<? extends Annotation>> createSupportedTypeQualifiers()
TypeQualifiers
, return an immutable set with the same set
of classes as the annotation. If the class is not so annotated,
return an empty set.
Subclasses may override this method to return an immutable set
of their supported type qualifiers.TypeQualifiers
public final Set<Class<? extends Annotation>> getSupportedTypeQualifiers()
createSupportedTypeQualifiers()
protected MultiGraphQualifierHierarchy.MultiGraphFactory createQualifierHierarchyFactory()
protected @Nullable QualifierHierarchy createQualifierHierarchy()
getSupportedTypeQualifiers()
using the
meta-annotations found in them. The current implementation returns an
instance of GraphQualifierHierarchy
.
Subclasses may override this method to express any relationships that
cannot be inferred using meta-annotations (e.g. due to lack of
meta-annotations).public final @Nullable QualifierHierarchy getQualifierHierarchy()
QualifierHierarchy
for this checkercreateQualifierHierarchy()
protected TypeHierarchy createTypeHierarchy()
protected SourceVisitor<?,?> createSourceVisitor(@Nullable CompilationUnitTree root)
BaseTypeVisitor
. It reflectively invokes the constructor that
accepts this checker and the compilation unit tree (in that order)
as arguments.
Subclasses have to override this method to create the appropriate
visitor if they do not follow the checker naming convention.createSourceVisitor
in class SourceChecker
root
- the compilation unit currently being visitedpublic AnnotatedTypeFactory createFactory(@Nullable CompilationUnitTree root)
BasicAnnotatedTypeFactory
. It reflectively invokes the
constructor that accepts this checker and compilation unit tree
(in that order) as arguments.
Subclasses have to override this method to create the appropriate
visitor if they do not follow the checker naming convention.createFactory
in class SourceChecker
root
- the currently visited compilation unitpublic boolean isSubtype(@Mutable AnnotatedTypeMirror sub, @Mutable AnnotatedTypeMirror sup)
TypeHierarchy
. Its behavior is undefined for any annotations
not specified by either TypeQualifiers
or the result of
getSupportedTypeQualifiers()
.sub
- the child typesup
- the parent typesub
is a subtype of sup
public boolean isAssignable(@Mutable AnnotatedTypeMirror varType, @Mutable AnnotatedTypeMirror receiverType, @Nullable Tree variable, AnnotatedTypeFactory factory)
varType
- the annotated variable typevariable
- tree used to access the variablepublic Set<@ReadOnly String> getSupportedLintOptions()
getSupportedLintOptions
in class SourceChecker
Set
of the lint options recognized by
this checkerpublic static <T extends @Nullable Object> T invokeConstructorFor(@ReadOnly String name, Class<?>[] paramTypes, Object[] args)
name
having the given parameter types on the given
arguments. Returns null
if the class cannot be found, or the
constructor does not exist or cannot be invoked on the given arguments.T
- the type to which the constructor belongsname
- the name of the class to which the constructor belongsparamTypes
- the types of the constructor's parametersargs
- the arguments on which to invoke the constructorargs
, or
null if the constructor does not exist or could not be invoked