Class BaseTypeChecker
- java.lang.Object
-
- javax.annotation.processing.AbstractProcessor
-
- org.checkerframework.javacutil.AbstractTypeProcessor
-
- org.checkerframework.framework.source.SourceChecker
-
- org.checkerframework.common.basetype.BaseTypeChecker
-
- All Implemented Interfaces:
javax.annotation.processing.Processor
,OptionConfiguration
- Direct Known Subclasses:
AccumulationChecker
,AliasingChecker
,ClassValChecker
,FenumChecker
,FormatterChecker
,GuiEffectChecker
,I18nFormatterChecker
,I18nSubchecker
,InitializationChecker
,InitializationFieldAccessSubchecker
,InterningChecker
,KeyForSubchecker
,LessThanChecker
,LockChecker
,LowerBoundChecker
,MethodValChecker
,MustCallChecker
,NullnessNoInitSubchecker
,OptionalChecker
,PropertyKeyChecker
,PurityChecker
,RegexChecker
,ReportChecker
,ReturnsReceiverChecker
,SameLenChecker
,SearchIndexChecker
,SignatureChecker
,SignednessChecker
,SubstringIndexChecker
,SubtypingChecker
,TaintingChecker
,TypeOutputtingChecker
,UnitsChecker
,UpperBoundChecker
,ValueChecker
public abstract class BaseTypeChecker extends SourceChecker
An abstractSourceChecker
that provides a simpleSourceVisitor
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 extendSourceChecker
. Non-type checkers (e.g. checkers to enforce coding styles) can extendSourceChecker
orAbstractTypeProcessor
; 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 rulesTypeHierarchy
: to check subtyping rules between annotated types rather than qualifiersAnnotatedTypeFactory
: to construct qualified types enriched with default 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. 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 theAnnotatedTypeFactory.createQualifierHierarchy()
method.- See the Checker Framework Manual:
- The checker class
-
-
Field Summary
-
Fields inherited from class org.checkerframework.framework.source.SourceChecker
currentRoot, DETAILS_SEPARATOR, elements, elementsWithSuppressedWarnings, errsOnLastExit, javacErrored, messager, messagesProperties, MSGS_FILE, OPTION_SEPARATOR, parentChecker, SUPPRESS_ALL_MESSAGE_KEY, SUPPRESS_ALL_PREFIX, treePathCacher, trees, types, UNNEEDED_SUPPRESSION_KEY, upstreamCheckerNames, useAllcheckersPrefix, visitor
-
-
Constructor Summary
Constructors Constructor Description BaseTypeChecker()
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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 ofcreateSourceVisitor()
.AnnotationProvider
getAnnotationProvider()
Returns the AnnotationProvider (the type factory) associated with this.java.util.List<java.lang.String>
getExtraStubFiles()
Return a list of additional stub files to be treated as if they had been written in a@StubFiles
annotation.protected java.util.Set<java.lang.Class<? extends BaseTypeChecker>>
getImmediateSubcheckerClasses()
Returns the set of subchecker classes on which this checker depends.java.util.Map<java.lang.String,java.lang.String>
getOptions()
Return all active options for this checker.java.util.Map<java.lang.String,java.lang.String>
getOptionsNoSubcheckers()
LikegetOptions()
, but only includes options provided to this checker.static @ClassGetName java.lang.String
getRelatedClassName(java.lang.Class<?> checkerClass, java.lang.String replacement)
Returns the name of a class related to a given one, by replacing "Checker" or "Subchecker" byreplacement
.<T extends BaseTypeChecker>
@Nullable TgetSubchecker(java.lang.Class<T> checkerClass)
Returns the requested subchecker.java.util.List<BaseTypeChecker>
getSubcheckers()
Get the list of all subcheckers (if any).java.util.Set<java.lang.String>
getSupportedLintOptions()
Specify supported lint options for all type-checkers.java.util.Set<java.lang.String>
getSupportedOptions()
Map the Checker Framework version ofSupportedOptions
to the standard annotation provided versionSupportedOptions
.java.util.Collection<java.lang.String>
getSuppressWarningsPrefixesOfSubcheckers()
LikeSourceChecker.getSuppressWarningsPrefixes()
, but includes all prefixes supported by this checker or any of its subcheckers.GenericAnnotatedTypeFactory<?,?,?,?>
getTypeFactory()
Return the type factory associated with this checker.<T extends GenericAnnotatedTypeFactory<?,?,?,?>>
@Nullable TgetTypeFactoryOfSubcheckerOrNull(java.lang.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(java.lang.String name)
LikeSourceChecker.hasOption(java.lang.String)
, but checks whether the given option is provided to this checker.void
initChecker()
Initialize the checker.static <T> @Nullable T
invokeConstructorFor(@ClassGetName java.lang.String name, java.lang.Class<?>[] paramTypes, java.lang.Object[] args)
Invokes the constructor belonging to the class named byname
having the given parameter types on the given arguments.protected void
printOrStoreMessage(javax.tools.Diagnostic.Kind kind, java.lang.String message, com.sun.source.tree.Tree source, com.sun.source.tree.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 java.lang.Object
processErrorMessageArg(java.lang.Object arg)
Process an argument to an error message before it is passed to String.format.protected void
setRoot(com.sun.source.tree.CompilationUnitTree newRoot)
Invoked when the current compilation unit root changes.protected boolean
shouldAddShutdownHook()
Return true to indicate that methodSourceChecker.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(javax.lang.model.element.TypeElement element, com.sun.source.util.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".-
Methods inherited from class org.checkerframework.framework.source.SourceChecker
addOptions, createSupportedLintOptions, expandCFOptions, fullMessageOf, getBooleanOption, getBooleanOption, getElementUtils, getLintOption, getLintOption, getMessagesProperties, getOption, getOption, getOptionConfiguration, getParentChecker, getPathToCompilationUnit, getProcessingEnvironment, getProperties, getStandardSuppressWarningsPrefixes, getStringsOption, getStringsOption, getSupportedAnnotationTypes, getSupportedSourceVersion, getSuppressWarningsPrefixes, getTreePathCacher, getTreeUtils, getTypeUtils, getUpstreamCheckerNames, getWarningMessagePrefix, hasOption, init, message, message, messageKeyMatches, printOrStoreMessage, printStats, report, reportError, reportWarning, setLintOption, setParentChecker, setProcessingEnvironment, setSupportedLintOptions, shouldSkipDefs, shouldSkipDefs, shouldSkipUses, shouldSkipUses, shouldSuppressWarnings, shouldSuppressWarnings, shouldSuppressWarnings, typeProcessingStart, useConservativeDefault, warnUnneededSuppressions
-
Methods inherited from class org.checkerframework.javacutil.AbstractTypeProcessor
getCompilerLog, process
-
Methods inherited from class javax.annotation.processing.AbstractProcessor
getCompletions, isInitialized
-
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
-
Methods inherited from interface org.checkerframework.framework.util.OptionConfiguration
getStringsOption, getStringsOption
-
-
-
-
Method Detail
-
initChecker
public void initChecker()
Description copied from class:SourceChecker
Initialize the checker.- Overrides:
initChecker
in classSourceChecker
- See Also:
AbstractProcessor.init(ProcessingEnvironment)
-
setRoot
protected void setRoot(com.sun.source.tree.CompilationUnitTree newRoot)
Description copied from class:SourceChecker
Invoked when the current compilation unit root changes.- Overrides:
setRoot
in classSourceChecker
- Parameters:
newRoot
- the new compilation unit root
-
getImmediateSubcheckerClasses
protected java.util.Set<java.lang.Class<? extends BaseTypeChecker>> getImmediateSubcheckerClasses()
Returns the set of subchecker classes on which this checker depends. Returns an empty set if this checker does not depend on any others.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 set returned by this method, but clients that override the method do modify the set.
- Returns:
- the subchecker classes on which this checker depends; will be modified by callees in overriding methods
-
shouldResolveReflection
public boolean shouldResolveReflection()
Returns whether or not reflection should be resolved.- Returns:
- true if reflection should be resolved
-
createSourceVisitor
protected BaseTypeVisitor<?> createSourceVisitor()
Returns the appropriate visitor that type-checks the compilation unit according to the type system rules.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.
- Specified by:
createSourceVisitor
in classSourceChecker
- Returns:
- the type-checking visitor
-
createSourceVisitorPublic
public BaseTypeVisitor<?> createSourceVisitorPublic()
A public variant ofcreateSourceVisitor()
. Only use this if you know what you are doing.- Returns:
- the type-checking visitor
-
getRelatedClassName
public static @ClassGetName java.lang.String getRelatedClassName(java.lang.Class<?> checkerClass, java.lang.String replacement)
Returns the name of a class related to a given one, by replacing "Checker" or "Subchecker" byreplacement
.- Parameters:
checkerClass
- the checker classreplacement
- the string to replace "Checker" or "Subchecker" by- Returns:
- the name of the related class
-
getSupportedLintOptions
public java.util.Set<java.lang.String> getSupportedLintOptions()
Specify supported lint options for all type-checkers.- Overrides:
getSupportedLintOptions
in classSourceChecker
- Returns:
- an unmodifiable
Set
of the lint options recognized by this checker
-
invokeConstructorFor
public static <T> @Nullable T invokeConstructorFor(@ClassGetName java.lang.String name, java.lang.Class<?>[] paramTypes, java.lang.Object[] args)
Invokes the constructor belonging to the class named byname
having the given parameter types on the given arguments. Returnsnull
if the class cannot be found. Otherwise, throws an exception if there is trouble with the constructor invocation.- Type Parameters:
T
- the type to which the constructor belongs- Parameters:
name
- the name of the class to which the constructor belongsparamTypes
- the types of the constructor's parametersargs
- the arguments on which to invoke the constructor- Returns:
- the result of the constructor invocation on
args
, or null if the class does not exist
-
getVisitor
public BaseTypeVisitor<?> getVisitor()
Description copied from class:SourceChecker
Returns the SourceVisitor associated with this.- Overrides:
getVisitor
in classSourceChecker
- Returns:
- the SourceVisitor associated with this
-
getTypeFactory
public GenericAnnotatedTypeFactory<?,?,?,?> getTypeFactory()
Return the type factory associated with this checker.- Returns:
- the type factory associated with this checker
-
getAnnotationProvider
public AnnotationProvider getAnnotationProvider()
Description copied from class:SourceChecker
Returns the AnnotationProvider (the type factory) associated with this.- Overrides:
getAnnotationProvider
in classSourceChecker
- Returns:
- the AnnotationProvider (the type factory) associated with this
-
getSubchecker
public <T extends BaseTypeChecker> @Nullable T getSubchecker(java.lang.Class<T> checkerClass)
Returns the requested subchecker. A checker of a given class can only be run once, so this returns the only such checker, or null if none was found. The caller must know the exact checker class to request.- Type Parameters:
T
- the class of the subchecker to return- Parameters:
checkerClass
- the class of the subchecker to return- Returns:
- the requested subchecker or null if not found
-
getTypeFactoryOfSubcheckerOrNull
public <T extends GenericAnnotatedTypeFactory<?,?,?,?>> @Nullable T getTypeFactoryOfSubcheckerOrNull(java.lang.Class<? extends BaseTypeChecker> subCheckerClass)
Returns the type factory used by a subchecker. Returns null if no matching subchecker was found or if the type factory is null. The caller must know the exact checker class to request.Because the visitor state is copied, call this method each time a subfactory is needed rather than store the returned subfactory in a field.
- Type Parameters:
T
- the type ofsubCheckerClass
'sAnnotatedTypeFactory
- Parameters:
subCheckerClass
- the class of the subchecker- Returns:
- the type factory of the requested subchecker or null if not found
-
getSubcheckers
public java.util.List<BaseTypeChecker> getSubcheckers()
Get the list of all subcheckers (if any). via the instantiateSubcheckers method. This list is only non-empty for the one checker that runs all other subcheckers. These are recursively instantiated via instantiateSubcheckers the first time the method is called if subcheckers is null. Assumes all checkers run on the same thread.- Returns:
- the list of all subcheckers (if any)
-
typeProcess
public void typeProcess(javax.lang.model.element.TypeElement element, com.sun.source.util.TreePath tree)
Description copied from class:SourceChecker
Type-check the code using this checker's visitor.- Overrides:
typeProcess
in classSourceChecker
- Parameters:
element
- element of the analyzed classtree
- the tree path to the element, with the leaf being aClassTree
- See Also:
Processor.process(Set, RoundEnvironment)
-
getSuppressWarningsPrefixesOfSubcheckers
public java.util.Collection<java.lang.String> getSuppressWarningsPrefixesOfSubcheckers()
LikeSourceChecker.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.- Returns:
- the suppress warnings prefixes supported by this checker or any of its subcheckers
-
getUltimateParentChecker
public BaseTypeChecker getUltimateParentChecker()
Finds the ultimate parent checker of this checker. The ultimate parent checker is the checker that the user actually requested, i.e. the one with no parent. The ultimate parent might be this checker itself.- Returns:
- the first checker in the parent checker chain with no parent checker of its own, i.e., the ultimate parent checker
-
warnUnneededSuppressions
protected void warnUnneededSuppressions()
Issues a warning about any@SuppressWarnings
that didn't suppress a warning, but starts with this checker name or "allcheckers".This implementation collects needed warning suppressions for all subcheckers.
- Overrides:
warnUnneededSuppressions
in classSourceChecker
-
printOrStoreMessage
protected void printOrStoreMessage(javax.tools.Diagnostic.Kind kind, java.lang.String message, com.sun.source.tree.Tree source, com.sun.source.tree.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.Otherwise, it prints the message.
- Overrides:
printOrStoreMessage
in classSourceChecker
- Parameters:
kind
- the kind of message to printmessage
- the message textsource
- the source code position of the diagnostic messageroot
- the compilation unit
-
typeProcessingOver
public void typeProcessingOver()
Description copied from class:AbstractTypeProcessor
A method to be called once all the classes are processed.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.- Overrides:
typeProcessingOver
in classAbstractTypeProcessor
-
getSupportedOptions
public java.util.Set<java.lang.String> getSupportedOptions()
Description copied from class:SourceChecker
Map the Checker Framework version ofSupportedOptions
to the standard annotation provided versionSupportedOptions
.- Specified by:
getSupportedOptions
in interfaceOptionConfiguration
- Specified by:
getSupportedOptions
in interfacejavax.annotation.processing.Processor
- Overrides:
getSupportedOptions
in classSourceChecker
- Returns:
- the supported options
-
getOptions
public java.util.Map<java.lang.String,java.lang.String> getOptions()
Description copied from interface:OptionConfiguration
Return all active options for this checker.- Specified by:
getOptions
in interfaceOptionConfiguration
- Overrides:
getOptions
in classSourceChecker
- Returns:
- all active options for this checker
-
getOptionsNoSubcheckers
public java.util.Map<java.lang.String,java.lang.String> getOptionsNoSubcheckers()
LikegetOptions()
, but only includes options provided to this checker. Does not include those passed to subcheckers.- Returns:
- the active options for this checker, not including those passed to subcheckers
-
hasOptionNoSubcheckers
public final boolean hasOptionNoSubcheckers(java.lang.String name)
LikeSourceChecker.hasOption(java.lang.String)
, but checks whether the given option is provided to this checker. Does not consider those passed to subcheckers.- Parameters:
name
- the name of the option to check- Returns:
- true if the option name was provided to this checker, false otherwise
-
getExtraStubFiles
public java.util.List<java.lang.String> getExtraStubFiles()
Return a list of additional stub files to be treated as if they had been written in a@StubFiles
annotation.- Returns:
- stub files to be treated as if they had been written in a
@StubFiles
annotation
-
processErrorMessageArg
protected java.lang.Object processErrorMessageArg(java.lang.Object arg)
Description copied from class:SourceChecker
Process an argument to an error message before it is passed to String.format.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.- Overrides:
processErrorMessageArg
in classSourceChecker
- Parameters:
arg
- the argument- Returns:
- the result after processing
-
shouldAddShutdownHook
protected boolean shouldAddShutdownHook()
Description copied from class:SourceChecker
Return true to indicate that methodSourceChecker.shutdownHook()
should be added as a shutdownHook of the JVM.- Overrides:
shouldAddShutdownHook
in classSourceChecker
- Returns:
- true to add
SourceChecker.shutdownHook()
as a shutdown hook of the JVM
-
shutdownHook
protected void shutdownHook()
Description copied from class:SourceChecker
Method that gets called exactly once at shutdown time of the JVM. Checkers can override this method to customize the behavior.If you override this, you must also override
SourceChecker.shouldAddShutdownHook()
to return true.- Overrides:
shutdownHook
in classSourceChecker
-
-