public abstract class SourceChecker extends AbstractTypeProcessor
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.
Subclasses must implement the following methods:
getMessages()
(for type-qualifier specific error messages)
createSourceVisitor(CompilationUnitTree)
(for a custom SourceVisitor
)
createFactory(com.sun.source.tree.CompilationUnitTree)
(for a custom AnnotatedTypeFactory
)
getSuppressWarningsKey()
(for honoring
SuppressWarnings
annotations)
BaseTypeChecker
,
instead of this class. Only checkers which 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 |
---|---|
TreePath |
currentPath |
protected CompilationUnitTree |
currentRoot
The source tree that's being scanned.
|
static String |
DETAILS_SEPARATOR |
protected Messager |
messager
Used to report error messages and warnings via the compiler.
|
protected Properties |
messages
Maps error keys to localized/custom error messages.
|
protected Trees |
trees
Used as a helper for the
SourceVisitor . |
processingEnv
Constructor and Description |
---|
SourceChecker() |
Modifier and Type | Method and Description |
---|---|
AnnotatedTypeFactory |
createFactory(CompilationUnitTree root) |
protected abstract SourceVisitor<?,?> |
createSourceVisitor(CompilationUnitTree root)
Provides the
SourceVisitor that the checker should use to scan
input source trees. |
protected Set<String> |
createSupportedLintOptions()
Compute the set of supported lint options.
|
static void |
errorAbort(String msg)
Log an error message and abort processing.
|
static void |
errorAbort(String msg,
Throwable cause) |
protected String |
formatStackTrace(StackTraceElement[] stackTrace)
Format a list of
StackTraceElement s to be printed out as an error
message. |
protected String |
fullMessageOf(String messageKey,
String defValue)
Returns the localized long message corresponding for this key, and
returns the defValue if no localized message is found.
|
boolean |
getLintOption(String name)
Determines the value of the lint option with the given name.
|
boolean |
getLintOption(String name,
boolean def)
Determines the value of the lint option with the given name.
|
Properties |
getMessages()
Provides a mapping of error keys to custom error messages.
|
ProcessingEnvironment |
getProcessingEnvironment() |
protected Properties |
getProperties(Class<?> cls,
String filePath)
A helper function to parse a Properties file
|
Set<String> |
getSupportedAnnotationTypes()
Always returns a singleton set containing only "*".
|
Set<String> |
getSupportedLintOptions()
Returns the lint options recognized by this checker.
|
Set<String> |
getSupportedOptions() |
SourceVersion |
getSupportedSourceVersion() |
Collection<String> |
getSuppressWarningsKey() |
void |
initChecker()
Initialize the checker.
|
protected void |
message(Diagnostic.Kind kind,
Object source,
@CompilerMessageKey String msgKey,
Object... args)
Prints a message (error, warning, note, etc.) via JSR-269.
|
protected void |
printStats()
Print resource usage statistics
|
void |
report(Result r,
Object src)
Reports a result.
|
protected void |
setLintOption(String name,
boolean val)
Set the value of the lint option with the given name.
|
protected void |
setSupportedLintOptions(Set<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(ClassTree node)
Tests whether the class definition should not be checked because it
matches the
checker.skipDefs property. |
boolean |
shouldSkipDefs(ClassTree cls,
MethodTree meth)
Tests whether the method definition should not be checked because it
matches the
checker.skipDefs property. |
boolean |
shouldSkipUses(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. |
protected void |
shutdownHook()
Method that gets called exactly once at shutdown time of the JVM.
|
void |
typeProcess(TypeElement e,
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
getCompletions, isInitialized, toString
protected Properties messages
protected Messager messager
protected Trees trees
SourceVisitor
.protected CompilationUnitTree currentRoot
public TreePath currentPath
public static final String DETAILS_SEPARATOR
public ProcessingEnvironment getProcessingEnvironment()
ProcessingEnvironment
that was supplied to this
checkerpublic AnnotatedTypeFactory createFactory(CompilationUnitTree root)
root
- the AST root for the factoryAnnotatedTypeFactory
for use by typecheckersprotected abstract SourceVisitor<?,?> createSourceVisitor(CompilationUnitTree root)
SourceVisitor
that the checker should use to scan
input source trees.root
- the AST rootSourceVisitor
to use to scan source treespublic 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 static void errorAbort(String msg)
msg
- The error message to log.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()
protected boolean shouldAddShutdownHook()
shutdownHook()
should be
added as a shutdownHook of the JVM.protected void shutdownHook()
protected void printStats()
public void typeProcess(TypeElement e, 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 String formatStackTrace(StackTraceElement[] stackTrace)
StackTraceElement
s to be printed out as an error
message.protected String fullMessageOf(String messageKey, String defValue)
protected void message(Diagnostic.Kind kind, Object source, @CompilerMessageKey String msgKey, 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 keyIllegalArgumentException
- if source
is neither a Tree
nor an
Element
Diagnostic
public void report(Result r, Object src)
r
- the result to reportsrc
- the position object associated with the resultpublic final boolean getLintOption(String name)
name
- the name of the lint option to check forIllegalArgumentException
- if the option name is not recognized
via the SupportedLintOptions
annotation or the getSupportedLintOptions()
methodgetLintOption(String,boolean)
public final boolean getLintOption(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 allIllegalArgumentException
- if the option name is not recognized
via the SupportedLintOptions
annotation or the getSupportedLintOptions()
methodgetLintOption(String)
protected final void setLintOption(String name, boolean val)
name
- the name of the lint option to setval
- the option valueIllegalArgumentException
- if the option name is not recognized
via the SupportedLintOptions
annotation or the getSupportedLintOptions()
methodgetLintOption(String)
,
getLintOption(String,boolean)
public Set<String> getSupportedLintOptions()
getLintOption(java.lang.String)
.Set
of the lint options recognized by
this checkerprotected Set<String> createSupportedLintOptions()
protected void setSupportedLintOptions(Set<String> newlints)
public Set<String> getSupportedOptions()
getSupportedOptions
in interface Processor
getSupportedOptions
in class AbstractProcessor
public final Set<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
BaseTypeChecker.getSupportedTypeQualifiers()
method.
getSupportedAnnotationTypes
in interface Processor
getSupportedAnnotationTypes
in class AbstractProcessor
Error
- if a subclass is annotated with
SupportedAnnotationTypes
TypeQualifiers
,
getSupportedAnnotationTypes()
public Collection<String> getSuppressWarningsKey()
SuppressWarningsKey
public final boolean shouldSkipUses(Element element)
checker.skipUses
property.element
- an elementpublic final boolean shouldSkipDefs(ClassTree node)
checker.skipDefs
property.node
- class to potentially skippublic final boolean shouldSkipDefs(ClassTree cls, 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 Properties getProperties(Class<?> cls, String filePath)
cls
- the class whose location is the base of the file pathfilePath
- the name/path of the file to be readpublic final SourceVersion getSupportedSourceVersion()
getSupportedSourceVersion
in interface Processor
getSupportedSourceVersion
in class AbstractProcessor