public abstract class BaseTypeChecker extends SourceChecker
SourceChecker
that provides a simple SourceVisitor
implementation that type-checks assignments,
pseudo-assignments such as parameter passing and method invocation, and method overriding.
Most type-checker annotation processor should extend this class, instead of SourceChecker
. Checkers that 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) can extend SourceChecker
or AbstractTypeProcessor
; 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 use 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 rules
TypeHierarchy
: to check subtyping rules between annotated types rather than
qualifiers
AnnotatedTypeFactory
: to construct qualified types enriched with default qualifiers
according to the type system rules
BaseTypeVisitor
: 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. See AnnotatedTypeFactory.createSupportedTypeQualifiers()
.
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 AnnotatedTypeFactory.createQualifierHierarchy()
method.
currentRoot, DETAILS_SEPARATOR, elementsWithSuppressedWarnings, errsOnLastExit, javacErrored, messager, messagesProperties, MSGS_FILE, OPTION_SEPARATOR, parentChecker, SUPPRESS_ALL_MESSAGE_KEY, SUPPRESS_ALL_PREFIX, trees, UNNEEDED_SUPPRESSION_KEY, upstreamCheckerNames, useAllcheckersPrefix, visitor
processingEnv
Constructor and Description |
---|
BaseTypeChecker() |
Modifier and Type | Method and Description |
---|---|
protected BaseTypeVisitor<?> |
createSourceVisitor()
Returns the appropriate visitor that type-checks the compilation unit according to the type
system rules.
|
BaseTypeVisitor<?> |
createSourceVisitorPublic()
A public variant of
createSourceVisitor() . |
AnnotationProvider |
getAnnotationProvider()
Returns the AnnotationProvider (the type factory) associated with this.
|
List<String> |
getExtraStubFiles()
Return a list of additional stub files to be treated as if they had been written in a
@StubFiles annotation. |
protected LinkedHashSet<Class<? extends BaseTypeChecker>> |
getImmediateSubcheckerClasses()
Returns the set of subchecker classes on which this checker depends.
|
Map<String,String> |
getOptions()
Return all active options for this checker.
|
Map<String,String> |
getOptionsNoSubcheckers()
Like
getOptions() , but only includes options provided to this checker. |
static @ClassGetName String |
getRelatedClassName(Class<?> checkerClass,
String replacement)
Returns the name of a class related to a given one, by replacing "Checker" or "Subchecker" by
replacement . |
<T extends BaseTypeChecker> |
getSubchecker(Class<T> checkerClass)
Returns the requested subchecker.
|
List<BaseTypeChecker> |
getSubcheckers()
Get the list of all subcheckers (if any).
|
Set<String> |
getSupportedLintOptions()
Specify supported lint options for all type-checkers.
|
Set<String> |
getSupportedOptions()
Map the Checker Framework version of
SupportedOptions to the standard annotation
provided version SupportedOptions . |
Collection<String> |
getSuppressWarningsPrefixesOfSubcheckers()
Like
SourceChecker.getSuppressWarningsPrefixes() , but includes all prefixes supported
by this checker or any of its subcheckers. |
TreePathCacher |
getTreePathCacher()
Get the shared TreePathCacher instance.
|
GenericAnnotatedTypeFactory<?,?,?,?> |
getTypeFactory()
Return the type factory associated with this checker.
|
<T extends GenericAnnotatedTypeFactory<?,?,?,?>> |
getTypeFactoryOfSubchecker(Class<? extends BaseTypeChecker> subCheckerClass)
Returns the type factory used by a subchecker.
|
BaseTypeChecker |
getUltimateParentChecker()
Finds the ultimate parent checker of this checker.
|
BaseTypeVisitor<?> |
getVisitor()
Returns the SourceVisitor associated with this.
|
boolean |
hasOptionNoSubcheckers(String name)
Like
SourceChecker.hasOption(java.lang.String) , but checks whether the given option is provided to this checker. |
void |
initChecker()
Initialize the checker.
|
static <T> T |
invokeConstructorFor(@ClassGetName 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. |
protected void |
printOrStoreMessage(Diagnostic.Kind kind,
String message,
Tree source,
CompilationUnitTree root)
If this is a compound checker or a subchecker of a compound checker, then the message is stored
until all messages from all checkers for the compilation unit are issued.
|
protected Object |
processArg(Object arg)
Process an argument to an error message before it is passed to String.format.
|
protected void |
reportJavacError(TreePath p)
Report "type.checking.not.run" error.
|
protected void |
setRoot(CompilationUnitTree newRoot)
Invoked when the current compilation unit root changes.
|
protected boolean |
shouldAddShutdownHook()
Return true to indicate that method
SourceChecker.shutdownHook() should be added as a shutdownHook of
the JVM. |
boolean |
shouldResolveReflection()
Returns whether or not reflection should be resolved.
|
protected void |
shutdownHook()
Method that gets called exactly once at shutdown time of the JVM.
|
void |
typeProcess(TypeElement element,
TreePath tree)
Type-check the code using this checker's visitor.
|
void |
typeProcessingOver()
A method to be called once all the classes are processed.
|
protected void |
warnUnneededSuppressions()
Issues a warning about any
@SuppressWarnings that didn't suppress a warning, but starts
with this checker name or "allcheckers". |
addOptions, createSupportedLintOptions, expandCFOptions, fullMessageOf, getBooleanOption, getBooleanOption, getElementUtils, getLintOption, getLintOption, getMessagesProperties, getOption, getOption, getOptionConfiguration, getParentChecker, getPathToCompilationUnit, getProcessingEnvironment, getProperties, getStandardSuppressWarningsPrefixes, getSupportedAnnotationTypes, getSupportedSourceVersion, getSuppressWarningsPrefixes, getTreeUtils, getTypeUtils, getUpstreamCheckerNames, hasOption, init, message, message, printOrStoreMessage, printStats, report, reportError, reportWarning, setLintOption, setParentChecker, setProcessingEnvironment, setSupportedLintOptions, shouldSkipDefs, shouldSkipDefs, shouldSkipUses, shouldSkipUses, shouldSuppressWarnings, shouldSuppressWarnings, shouldSuppressWarnings, typeProcessingStart, useConservativeDefault, warnUnneededSuppressions
getCompilerLog, process
getCompletions, isInitialized
public void initChecker()
SourceChecker
initChecker
in class SourceChecker
AbstractProcessor.init(ProcessingEnvironment)
protected void setRoot(CompilationUnitTree newRoot)
SourceChecker
setRoot
in class SourceChecker
newRoot
- the new compilation unit rootprotected LinkedHashSet<Class<? extends BaseTypeChecker>> getImmediateSubcheckerClasses()
Subclasses should override this method to specify subcheckers. If they do so, they should call the super implementation of this method and add dependencies to the returned set so that checkers required for reflection resolution are included if reflection resolution is requested.
Each subchecker of this checker may also depend on other checkers. If this checker and one of its subcheckers both depend on a third checker, that checker will only be instantiated once.
Though each checker is run on a whole compilation unit before the next checker is run, error
and warning messages are collected and sorted based on the location in the source file before
being printed. (See printOrStoreMessage(Diagnostic.Kind, String, Tree,
CompilationUnitTree)
.)
WARNING: Circular dependencies are not supported nor do checkers verify that their dependencies are not circular. Make sure no circular dependencies are created when overriding this method. (In other words, if checker A depends on checker B, checker B cannot depend on checker A.)
This method is protected so it can be overridden, but it should only be called internally by the BaseTypeChecker.
The BaseTypeChecker will not modify the list returned by this method, but other clients do modify the list.
public boolean shouldResolveReflection()
protected BaseTypeVisitor<?> createSourceVisitor()
This implementation uses the checker naming convention to create the appropriate visitor. If
no visitor is found, it returns an instance of 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
public BaseTypeVisitor<?> createSourceVisitorPublic()
createSourceVisitor()
. Only use this if you know what you are doing.public static @ClassGetName String getRelatedClassName(Class<?> checkerClass, String replacement)
replacement
.checkerClass
- the checker classreplacement
- the string to replace "Checker" or "Subchecker" bypublic Set<String> getSupportedLintOptions()
getSupportedLintOptions
in class SourceChecker
Set
of the lint options recognized by this checkerpublic static <T> T invokeConstructorFor(@ClassGetName String name, Class<?>[] paramTypes, Object[] args)
name
having the given parameter
types on the given arguments. Returns null
if the class cannot be found. Otherwise,
throws an exception if there is trouble with the constructor invocation.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 class does not
existpublic BaseTypeVisitor<?> getVisitor()
SourceChecker
getVisitor
in class SourceChecker
public GenericAnnotatedTypeFactory<?,?,?,?> getTypeFactory()
public AnnotationProvider getAnnotationProvider()
SourceChecker
getAnnotationProvider
in class SourceChecker
public <T extends BaseTypeChecker> T getSubchecker(Class<T> checkerClass)
checkerClass
- the class of the subcheckerpublic <T extends GenericAnnotatedTypeFactory<?,?,?,?>> T getTypeFactoryOfSubchecker(Class<? extends BaseTypeChecker> subCheckerClass)
Because the visitor state is copied, call this method each time a subfactory is needed rather than store the returned subfactory in a field.
T
- the type of subCheckerClass
's AnnotatedTypeFactory
subCheckerClass
- the class of the subcheckerpublic List<BaseTypeChecker> getSubcheckers()
public TreePathCacher getTreePathCacher()
protected void reportJavacError(TreePath p)
SourceChecker
reportJavacError
in class SourceChecker
p
- error is reported at the leaf of the pathpublic void typeProcess(TypeElement element, TreePath tree)
SourceChecker
typeProcess
in class SourceChecker
element
- element of the analyzed classtree
- the tree path to the element, with the leaf being a ClassTree
Processor.process(Set, RoundEnvironment)
public Collection<String> getSuppressWarningsPrefixesOfSubcheckers()
SourceChecker.getSuppressWarningsPrefixes()
, but includes all prefixes supported
by this checker or any of its subcheckers. Does not guarantee that the result is in any
particular order. The result is immutable.public BaseTypeChecker getUltimateParentChecker()
protected void warnUnneededSuppressions()
@SuppressWarnings
that didn't suppress a warning, but starts
with this checker name or "allcheckers".
This implementation collects needed warning suppressions for all subcheckers.
warnUnneededSuppressions
in class SourceChecker
protected void printOrStoreMessage(Diagnostic.Kind kind, String message, Tree source, CompilationUnitTree root)
Otherwise, it prints the message.
printOrStoreMessage
in class SourceChecker
kind
- the kind of message to printmessage
- the message textsource
- the source code position of the diagnostic messageroot
- the compilation unitpublic void typeProcessingOver()
AbstractTypeProcessor
Subclasses may override this method to do any aggregate analysis (e.g. generate report, persistence) or resource deallocation.
Method AbstractTypeProcessor.getCompilerLog()
can be used to access the number of compiler errors.
typeProcessingOver
in class AbstractTypeProcessor
public Set<String> getSupportedOptions()
SourceChecker
SupportedOptions
to the standard annotation
provided version SupportedOptions
.getSupportedOptions
in interface Processor
getSupportedOptions
in interface OptionConfiguration
getSupportedOptions
in class SourceChecker
public Map<String,String> getOptions()
SourceChecker
getOptions
in interface OptionConfiguration
getOptions
in class SourceChecker
public Map<String,String> getOptionsNoSubcheckers()
getOptions()
, but only includes options provided to this checker. Does not include
those passed to subcheckers.public final boolean hasOptionNoSubcheckers(String name)
SourceChecker.hasOption(java.lang.String)
, but checks whether the given option is provided to this checker. Does
not consider those passed to subcheckers.name
- the name of the option to checkpublic List<String> getExtraStubFiles()
@StubFiles
annotation.@StubFiles
annotationprotected Object processArg(Object arg)
SourceChecker
This implementation expands the argument if it is exactly a message key.
By contrast, SourceChecker.fullMessageOf(java.lang.String, java.lang.String)
processes the message key itself but not the arguments,
and tries suffixes.
processArg
in class SourceChecker
arg
- the argumentprotected boolean shouldAddShutdownHook()
SourceChecker
SourceChecker.shutdownHook()
should be added as a shutdownHook of
the JVM.shouldAddShutdownHook
in class SourceChecker
SourceChecker.shutdownHook()
as a shutdown hook of the JVMprotected void shutdownHook()
SourceChecker
shutdownHook
in class SourceChecker