@SupportedOptions(value={"skipUses","onlyUses","skipDefs","onlyDefs","suppressWarnings","showSuppressWarningKeys","assumeSideEffectFree","ignoreRawTypeArguments","enablePurity","invariantArrays","checkCastElementType","warns","lint","suggestPureMethods","assumeAssertionsAreEnabled","assumeAssertionsAreDisabled","concurrentSemantics","stubs","stubWarnIfNotFound","printAllQualifiers","detailedmsgtext","printErrorStack","nomsgtext","ignorejdkastub","nocheckjdk","stubDebug","filenames","showchecks","flowdotdir","resourceStats"}) public abstract class SourceChecker extends AbstractTypeProcessor implements ErrorHandler
javac
's annotation processing API, routines for error
reporting via the JSR 199 compiler API, and an implementation for using a
SourceVisitor
to perform the type-checking.
TODO update: Subclasses must implement the following methods:
SourceVisitor
)
AnnotatedTypeFactory
)
BaseTypeChecker
,
instead of this class. Only checkers that require annotated types but not
subtype checking (e.g. for testing purposes) should extend this.
Non-type checkers (e.g. for enforcing coding styles) should extend
AbstractProcessor
(or even this class) as the Checker Framework is
not designed for such checkers.Modifier and Type | Class and Description |
---|---|
static class |
SourceChecker.CheckerError
Exception type used only internally to abort
processing.
|
Modifier and Type | Field and Description |
---|---|
protected com.sun.source.util.TreePath |
currentPath
The source path that is being scanned.
|
protected com.sun.source.tree.CompilationUnitTree |
currentRoot
The source tree that is being scanned.
|
static java.lang.String |
DETAILS_SEPARATOR |
protected javax.annotation.processing.Messager |
messager
Used to report error messages and warnings via the compiler.
|
protected java.util.Properties |
messages
Maps error keys to localized/custom error messages.
|
protected static java.lang.String |
MSGS_FILE
File name of the localized messages.
|
protected com.sun.source.util.Trees |
trees
Used as a helper for the
SourceVisitor . |
protected SourceVisitor<?,?> |
visitor
The visitor to use.
|
Constructor and Description |
---|
SourceChecker() |
Modifier and Type | Method and Description |
---|---|
protected void |
addOptions(java.util.Map<java.lang.String,java.lang.String> moreopts)
Add additional active options.
|
protected abstract SourceVisitor<?,?> |
createSourceVisitor()
Provides the
SourceVisitor that the checker should use to scan
input source trees. |
protected java.util.Set<java.lang.String> |
createSupportedLintOptions()
Compute the set of supported lint options.
|
void |
errorAbort(java.lang.String msg)
Log an error message and abort processing.
|
void |
errorAbort(java.lang.String msg,
java.lang.Throwable cause) |
protected java.util.Collection<java.lang.String> |
expandCFOptions(java.util.List<? extends java.lang.Class<?>> clazzPrefixes,
java.lang.String[] options)
Generate the possible command-line option names by prefixing
each class name from
classPrefixes to options ,
separated by OPTION_SEPARATOR. |
protected java.lang.String |
formatStackTrace(java.lang.StackTraceElement[] stackTrace)
Format a list of
StackTraceElement s to be printed out as an error
message. |
protected java.lang.String |
fullMessageOf(java.lang.String messageKey,
java.lang.String defValue)
Returns the localized long message corresponding for this key, and
returns the defValue if no localized message is found.
|
boolean |
getLintOption(java.lang.String name)
Determines the value of the lint option with the given name.
|
boolean |
getLintOption(java.lang.String name,
boolean def)
Determines the value of the lint option with the given name.
|
java.util.Properties |
getMessages()
Provides a mapping of error keys to custom error messages.
|
java.lang.String |
getOption(java.lang.String name)
Determines the value of the option with the given name.
|
java.lang.String |
getOption(java.lang.String name,
java.lang.String def)
Determines the value of the lint option with the given name and
returns the default value if nothing is specified.
|
java.util.Map<java.lang.String,java.lang.String> |
getOptions()
Return all active options for this checker.
|
javax.annotation.processing.ProcessingEnvironment |
getProcessingEnvironment() |
protected java.util.Properties |
getProperties(java.lang.Class<?> cls,
java.lang.String filePath)
A helper function to parse a Properties file
|
protected java.util.Collection<java.lang.String> |
getStandardSuppressWarningsKeys()
Determine the standard set of suppress warning keys usable for any checker.
|
java.util.Set<java.lang.String> |
getSupportedAnnotationTypes()
Always returns a singleton set containing only "*".
|
java.util.Set<java.lang.String> |
getSupportedLintOptions()
Returns the lint options recognized by this checker.
|
java.util.Set<java.lang.String> |
getSupportedOptions()
Map the Checker Framework version of
SupportedOptions to
the standard annotation provided version
SupportedOptions . |
javax.lang.model.SourceVersion |
getSupportedSourceVersion() |
java.util.Collection<java.lang.String> |
getSuppressWarningsKeys() |
boolean |
hasOption(java.lang.String name)
Check whether the given option is provided.
|
void |
initChecker()
Initialize the checker.
|
void |
message(javax.tools.Diagnostic.Kind kind,
java.lang.Object source,
@CompilerMessageKey java.lang.String msgKey,
java.lang.Object... args)
Prints a message (error, warning, note, etc.) via JSR-269.
|
protected void |
printStats()
Print resource usage statistics
|
void |
report(Result r,
java.lang.Object src)
Reports a result.
|
protected void |
setLintOption(java.lang.String name,
boolean val)
Set the value of the lint option with the given name.
|
protected void |
setSupportedLintOptions(java.util.Set<java.lang.String> newlints)
Set the supported lint options.
|
protected boolean |
shouldAddShutdownHook()
Return true to indicate that method
shutdownHook() should be
added as a shutdownHook of the JVM. |
boolean |
shouldSkipDefs(com.sun.source.tree.ClassTree node)
Tests whether the class definition should not be checked because it
matches the
checker.skipDefs property. |
boolean |
shouldSkipDefs(com.sun.source.tree.ClassTree cls,
com.sun.source.tree.MethodTree meth)
Tests whether the method definition should not be checked because it
matches the
checker.skipDefs property. |
boolean |
shouldSkipUses(javax.lang.model.element.Element element)
Tests whether the class owner of the passed element is an unannotated
class and matches the pattern specified in the
checker.skipUses property. |
boolean |
shouldSkipUses(java.lang.String typeName)
Tests whether the class owner of the passed type matches
the pattern specified in the
checker.skipUses property. |
protected void |
shutdownHook()
Method that gets called exactly once at shutdown time of the JVM.
|
java.lang.String |
treeToFilePositionString(com.sun.source.tree.Tree tree,
com.sun.source.tree.CompilationUnitTree currentRoot,
javax.annotation.processing.ProcessingEnvironment processingEnv)
For the given tree, compute the source positions for that tree.
|
void |
typeProcess(javax.lang.model.element.TypeElement e,
com.sun.source.util.TreePath p)
Type-check the code with Java specifications and then runs the Checker
Rule Checking visitor on the processed source.
|
void |
typeProcessingStart()
A method to be called once before the first call to typeProcess.
|
init, process, typeProcessingOver
protected static final java.lang.String MSGS_FILE
protected java.util.Properties messages
protected javax.annotation.processing.Messager messager
protected com.sun.source.util.Trees trees
SourceVisitor
.protected com.sun.source.tree.CompilationUnitTree currentRoot
protected com.sun.source.util.TreePath currentPath
protected SourceVisitor<?,?> visitor
public static final java.lang.String DETAILS_SEPARATOR
public javax.annotation.processing.ProcessingEnvironment getProcessingEnvironment()
ProcessingEnvironment
that was supplied to this
checkerprotected abstract SourceVisitor<?,?> createSourceVisitor()
SourceVisitor
that the checker should use to scan
input source trees.SourceVisitor
to use to scan source treespublic java.util.Properties getMessages()
As a default, this implementation builds a Properties
out of
file messages.properties
. It accumulates all the properties files
in the Java class hierarchy from the checker up to SourceChecker
.
This permits subclasses to inherit default messages while being able to
override them.
Properties
that maps error keys to error message textpublic void errorAbort(java.lang.String msg)
errorAbort
in interface ErrorHandler
msg
- The error message to log.public void errorAbort(java.lang.String msg, java.lang.Throwable cause)
errorAbort
in interface ErrorHandler
public void typeProcessingStart()
Subclasses may override this method to do any initialization work. Type-checkers are not supposed to override this. Instead use initChecker. This allows us to handle CheckerError only here and doesn't require all overriding implementations to be aware of CheckerError.
typeProcessingStart
in class AbstractTypeProcessor
AbstractProcessor.init(ProcessingEnvironment)
,
initChecker()
public void initChecker()
AbstractProcessor.init(ProcessingEnvironment)
protected boolean shouldAddShutdownHook()
shutdownHook()
should be
added as a shutdownHook of the JVM.protected void shutdownHook()
protected void printStats()
public void typeProcess(javax.lang.model.element.TypeElement e, com.sun.source.util.TreePath p)
typeProcess
in class AbstractTypeProcessor
e
- element of the analyzed classp
- the tree path to the element, with the leaf being a
ClassTree
Processor.process(Set, RoundEnvironment)
protected java.lang.String formatStackTrace(java.lang.StackTraceElement[] stackTrace)
StackTraceElement
s to be printed out as an error
message.protected java.lang.String fullMessageOf(java.lang.String messageKey, java.lang.String defValue)
public void message(javax.tools.Diagnostic.Kind kind, java.lang.Object source, @CompilerMessageKey java.lang.String msgKey, java.lang.Object... args)
kind
- the type of message to printsource
- the object from which to obtain source position informationmsgKey
- the message key to printargs
- arguments for interpolation in the string corresponding to the
given message keyjava.lang.IllegalArgumentException
- if source
is neither a Tree
nor an
Element
Diagnostic
public java.lang.String treeToFilePositionString(com.sun.source.tree.Tree tree, com.sun.source.tree.CompilationUnitTree currentRoot, javax.annotation.processing.ProcessingEnvironment processingEnv)
tree
- Tree to locate within the current compilation unitcurrentRoot
- The current compilation unitprocessingEnv
- The current processing environmentpublic void report(Result r, java.lang.Object src)
r
- the result to reportsrc
- the position object associated with the resultpublic final boolean getLintOption(java.lang.String name)
name
- the name of the lint option to check forjava.lang.IllegalArgumentException
- if the option name is not recognized
via the SupportedLintOptions
annotation or the getSupportedLintOptions()
methodgetLintOption(String, boolean)
public final boolean getLintOption(java.lang.String name, boolean def)
name
- the name of the lint option to check fordef
- the default option value, returned if the option was not givendef
if it was not given at alljava.lang.IllegalArgumentException
- if the option name is not recognized
via the SupportedLintOptions
annotation or the getSupportedLintOptions()
methodgetLintOption(String)
,
getOption(String)
protected final void setLintOption(java.lang.String name, boolean val)
name
- the name of the lint option to setval
- the option valuejava.lang.IllegalArgumentException
- if the option name is not recognized
via the SupportedLintOptions
annotation or the getSupportedLintOptions()
methodgetLintOption(String)
,
getLintOption(String,boolean)
public java.util.Set<java.lang.String> getSupportedLintOptions()
getLintOption(java.lang.String)
.Set
of the lint options recognized by
this checkerprotected java.util.Set<java.lang.String> createSupportedLintOptions()
protected void setSupportedLintOptions(java.util.Set<java.lang.String> newlints)
protected void addOptions(java.util.Map<java.lang.String,java.lang.String> moreopts)
public final java.lang.String getOption(java.lang.String name)
getLintOption(String,boolean)
public java.util.Map<java.lang.String,java.lang.String> getOptions()
public final boolean hasOption(java.lang.String name)
getOption(String)
can still return null even
if hasOption is true: this happens e.g. for -Amyoptname
- The option name to checkpublic final java.lang.String getOption(java.lang.String name, java.lang.String def)
getOption(String)
,
getLintOption(String)
public java.util.Set<java.lang.String> getSupportedOptions()
SupportedOptions
to
the standard annotation provided version
SupportedOptions
.getSupportedOptions
in interface javax.annotation.processing.Processor
getSupportedOptions
in class javax.annotation.processing.AbstractProcessor
protected java.util.Collection<java.lang.String> expandCFOptions(java.util.List<? extends java.lang.Class<?>> clazzPrefixes, java.lang.String[] options)
classPrefixes
to options
,
separated by OPTION_SEPARATOR.clazzPrefixes
- The classes to prefixoptions
- The option namespublic final java.util.Set<java.lang.String> getSupportedAnnotationTypes()
SupportedAnnotationTypes
annotation, so the effect of returning "*"
is as if the checker were annotated by
@SupportedAnnotationTypes("*")
:
javac runs the checker on every
class mentioned on the javac command line. This method also checks
that subclasses do not contain a SupportedAnnotationTypes
annotation.
To specify the annotations that a checker recognizes as type qualifiers,
use the TypeQualifiers
annotation on the declaration of
subclasses of this class or override the
AnnotatedTypeFactory.getSupportedTypeQualifiers()
method.
getSupportedAnnotationTypes
in interface javax.annotation.processing.Processor
getSupportedAnnotationTypes
in class javax.annotation.processing.AbstractProcessor
java.lang.Error
- if a subclass is annotated with
SupportedAnnotationTypes
TypeQualifiers
public java.util.Collection<java.lang.String> getSuppressWarningsKeys()
SuppressWarningsKeys
protected final java.util.Collection<java.lang.String> getStandardSuppressWarningsKeys()
getSuppressWarningsKeys()
public final boolean shouldSkipUses(javax.lang.model.element.Element element)
checker.skipUses
property.element
- an elementpublic final boolean shouldSkipUses(java.lang.String typeName)
checker.skipUses
property.
In contrast to shouldSkipUses(Element)
this version
can also be used from primitive types, which don't have an element.typeName
- the fully-qualified name of a typepublic final boolean shouldSkipDefs(com.sun.source.tree.ClassTree node)
checker.skipDefs
property.node
- class to potentially skippublic final boolean shouldSkipDefs(com.sun.source.tree.ClassTree cls, com.sun.source.tree.MethodTree meth)
checker.skipDefs
property.
TODO: currently only uses the class definition. Refine pattern. Same for skipUses.cls
- class to potentially skipmeth
- method to potentially skipprotected java.util.Properties getProperties(java.lang.Class<?> cls, java.lang.String filePath)
cls
- the class whose location is the base of the file pathfilePath
- the name/path of the file to be readpublic final javax.lang.model.SourceVersion getSupportedSourceVersion()
getSupportedSourceVersion
in interface javax.annotation.processing.Processor
getSupportedSourceVersion
in class javax.annotation.processing.AbstractProcessor