checkers.source

Class SourceChecker

java.lang.Object

javax.annotation.processing.AbstractProcessor

checkers.source.AbstractTypeProcessor

checkers.source.SourceChecker

All Implemented Interfaces:

Processor

Direct Known Subclasses:

BaseTypeChecker, Locations

public abstract class SourceChecker
extends AbstractTypeProcessor

An abstract annotation processor designed for implementing a source-file checker for a JSR-308 conforming compiler plug-in. It provides an interface to 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)

Most type-checker plug-ins will want to extend 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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SourceChecker.CheckerError Exception type used only internally to abort processing.

Field Summary

Fields

Modifier and Type	Field and Description
@Nullable TreePath	currentPath
protected @Nullable CompilationUnitTree	currentRoot The source tree that's being scanned.
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.

Fields inherited from class javax.annotation.processing.AbstractProcessor

processingEnv

Constructor Summary

Constructors

Constructor and Description
SourceChecker()

Method Summary

Methods

Modifier and Type	Method and Description
AnnotatedTypeFactory	createFactory(@Nullable CompilationUnitTree root)
protected abstract SourceVisitor<?,?>	createSourceVisitor(@Nullable CompilationUnitTree root) Provides the SourceVisitor that the checker should use to scan input source trees.
static void	errorAbort(@ReadOnly String msg) Log an error message and abort processing.
static void	errorAbort(@ReadOnly String msg, Throwable cause)
protected @ReadOnly String	formatStackTrace(StackTraceElement[] stackTrace) Format a list of StackTraceElements to be printed out as an error message.
protected @ReadOnly String	fullMessageOf(@ReadOnly String messageKey, @ReadOnly String defValue) Returns the localized long message corresponding for this key, and returns the defValue if no localized message is found.
boolean	getLintOption(@ReadOnly String name) Determines the value of the lint option with the given name.
boolean	getLintOption(@ReadOnly 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, @ReadOnly String filePath) A helper function to parse a Properties file
Set<@ReadOnly String>	getSupportedAnnotationTypes() Always returns a singleton set containing only "*".
Set<@ReadOnly String>	getSupportedLintOptions() Returns the lint options recognized by this checker.
Set<@ReadOnly String>	getSupportedOptions()
SourceVersion	getSupportedSourceVersion()
Collection<@ReadOnly String>	getSuppressWarningsKey()
void	initChecker() Initialize the checker.
protected void	message(Diagnostic.Kind kind, @NonNull Object source, @ReadOnly String msgKey, Object... args) Prints a message (error, warning, note, etc.) via JSR-269.
void	report(Result r, @NonNull Object src) Reports a result.
boolean	shouldSkipDefs(@Nullable ClassTree node) Tests whether the class definition should not be checked because it matches the checker.skipDefs property.
boolean	shouldSkipDefs(@Nullable ClassTree cls, @Nullable MethodTree meth) Tests whether the method definition should not be checked because it matches the checker.skipDefs property.
boolean	shouldSkipUses(@Nullable 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.
void	typeProcess(TypeElement e, @Nullable 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.

Methods inherited from class checkers.source.AbstractTypeProcessor

init, process, typeProcessingOver

Methods inherited from class javax.annotation.processing.AbstractProcessor

getCompletions, isInitialized, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

messages

protected Properties messages

Maps error keys to localized/custom error messages.

messager

protected Messager messager

Used to report error messages and warnings via the compiler.

trees

protected Trees trees

Used as a helper for the SourceVisitor.

currentRoot

protected @Nullable CompilationUnitTree currentRoot

The source tree that's being scanned.

currentPath

public @Nullable TreePath currentPath

Constructor Detail

SourceChecker

public SourceChecker()

Method Detail

getProcessingEnvironment

public ProcessingEnvironment getProcessingEnvironment()

Returns:

the ProcessingEnvironment that was supplied to this checker

createFactory

public AnnotatedTypeFactory createFactory(@Nullable CompilationUnitTree root)

Parameters:

root - the AST root for the factory

Returns:

an AnnotatedTypeFactory for use by typecheckers

createSourceVisitor

protected abstract SourceVisitor<?,?> createSourceVisitor(@Nullable CompilationUnitTree root)

Provides the SourceVisitor that the checker should use to scan input source trees.

Parameters:

root - the AST root

Returns:

a SourceVisitor to use to scan source trees

getMessages

public Properties getMessages()

Provides a mapping of error keys to custom error messages.

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.

Returns:

a Properties that maps error keys to error message text

errorAbort

public static void errorAbort(@ReadOnly String msg)

Log an error message and abort processing. Call this method instead of raising an exception.

Parameters:

msg - The error message to log.

errorAbort

public static void errorAbort(@ReadOnly String msg,
              Throwable cause)

typeProcessingStart

public void typeProcessingStart()

A method to be called once before the first call to typeProcess.

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.

Overrides:

typeProcessingStart in class AbstractTypeProcessor

See Also:

AbstractProcessor.init(ProcessingEnvironment), SourceChecker#initChecker(ProcessingEnvironment)

initChecker

public void initChecker()

Initialize the checker.

See Also:

AbstractProcessor.init(ProcessingEnvironment)

typeProcess

public void typeProcess(TypeElement e,
               @Nullable TreePath p)

Type-check the code with Java specifications and then runs the Checker Rule Checking visitor on the processed source.

Specified by:

typeProcess in class AbstractTypeProcessor

Parameters:

e - element of the analyzed class

p - the tree path to the element, with the leaf being a ClassTree

See Also:

Processor.process(Set, RoundEnvironment)

formatStackTrace

protected @ReadOnly String formatStackTrace(StackTraceElement[] stackTrace)

Format a list of StackTraceElements to be printed out as an error message.

fullMessageOf

protected @ReadOnly String fullMessageOf(@ReadOnly String messageKey,
                             @ReadOnly String defValue)

Returns the localized long message corresponding for this key, and returns the defValue if no localized message is found.

message

protected void message(Diagnostic.Kind kind,
           @NonNull Object source,
           @ReadOnly String msgKey,
           Object... args)

Prints a message (error, warning, note, etc.) via JSR-269.

Parameters:

kind - the type of message to print

source - the object from which to obtain source position information

msgKey - the message key to print

args - arguments for interpolation in the string corresponding to the given message key

Throws:

IllegalArgumentException - if source is neither a Tree nor an Element

See Also:

Diagnostic

report

public void report(Result r,
          @NonNull Object src)

Reports a result. By default, it prints it to the screen via the compiler's internal messenger if the result is non-success; otherwise, the method returns with no side-effects.

Parameters:

r - the result to report

src - the position object associated with the result

getLintOption

public final boolean getLintOption(@ReadOnly String name)

Determines the value of the lint option with the given name. Just as javac uses "-Xlint:xxx" to enable and "-Xlint:-xxx" to disable option xxx, annotation-related lint options are enabled with "-Alint:xxx" and disabled with "-Alint:-xxx".

Parameters:

name - the name of the lint option to check for

Returns:

true if the lint option was given, false if it was not given or was given prepended with a "-"

Throws:

IllegalArgumentException - if the option name is not recognized via the SupportedLintOptions annotation or the getSupportedLintOptions() method

See Also:

getLintOption(String,boolean)

getLintOption

public final boolean getLintOption(@ReadOnly String name,
                    boolean def)

Determines the value of the lint option with the given name. Just as javac uses "-Xlint:xxx" to enable and "-Xlint:-xxx" to disable option xxx, annotation-related lint options are enabled with "-Alint=xxx" and disabled with "-Alint=-xxx".

Parameters:

name - the name of the lint option to check for

def - the default option value, returned if the option was not given

Returns:

true if the lint option was given, false if it was given prepended with a "-", or def if it was not given at all

Throws:

IllegalArgumentException - if the option name is not recognized via the SupportedLintOptions annotation or the getSupportedLintOptions() method

See Also:

getLintOption(String)

getSupportedLintOptions

public Set<@ReadOnly String> getSupportedLintOptions()

Returns the lint options recognized by this checker. Lint options are those which can be checked for via getLintOption(java.lang.String).

Returns:

an unmodifiable Set of the lint options recognized by this checker

getSupportedOptions

public Set<@ReadOnly String> getSupportedOptions()

Specified by:

getSupportedOptions in interface Processor

Overrides:

getSupportedOptions in class AbstractProcessor

getSupportedAnnotationTypes

public final Set<@ReadOnly String> getSupportedAnnotationTypes()

Always returns a singleton set containing only "*". This method returns the argument to the 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.

Specified by:

getSupportedAnnotationTypes in interface Processor

Overrides:

getSupportedAnnotationTypes in class AbstractProcessor

Throws:

Error - if a subclass is annotated with SupportedAnnotationTypes

See Also:

TypeQualifiers, getSupportedAnnotationTypes()

getSuppressWarningsKey

public Collection<@ReadOnly String> getSuppressWarningsKey()

Returns:

String keys that a checker honors for suppressing warnings and errors that it issues

See Also:

SuppressWarningsKey

shouldSkipUses

public final boolean shouldSkipUses(@Nullable 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.

Parameters:

element - an element

Returns:

true iff the enclosing class of element should be skipped

shouldSkipDefs

public final boolean shouldSkipDefs(@Nullable ClassTree node)

Tests whether the class definition should not be checked because it matches the checker.skipDefs property.

Parameters:

node - class to potentially skip

Returns:

true if checker should not test node

shouldSkipDefs

public final boolean shouldSkipDefs(@Nullable ClassTree cls,
                     @Nullable MethodTree meth)

Tests whether the method definition should not be checked because it matches the checker.skipDefs property. TODO: currently only uses the class definition. Refine pattern. Same for skipUses.

Parameters:

cls - class to potentially skip

meth - method to potentially skip

Returns:

true if checker should not test node

getProperties

protected Properties getProperties(Class<?> cls,
                       @ReadOnly String filePath)

A helper function to parse a Properties file

Parameters:

cls - the class whose location is the base of the file path

filePath - the name/path of the file to be read

Returns:

the properties

getSupportedSourceVersion

public final SourceVersion getSupportedSourceVersion()

Specified by:

getSupportedSourceVersion in interface Processor

Overrides:

getSupportedSourceVersion in class AbstractProcessor