checkers.source
Class SourceChecker

java.lang.Object
  javax.annotation.processing.AbstractProcessor
      checkers.source.SourceChecker

All Implemented Interfaces:

Processor

Direct Known Subclasses:

AnnotationsCounter, BaseTypeChecker, FactoryTestChecker, Locations, TreeDebug, TypeOutputtingChecker

@DefaultQualifier(value="checkers.nullness.quals.NonNull")
public abstract class SourceChecker
extends AbstractProcessor

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.

Field Summary

protected CompilationUnitTree	currentRoot The source tree that's being scanned.
protected ProcessingEnvironment	env Provides access to compiler helpers/internals.
protected com.sun.tools.javac.processing.JavacMessager	messager Used to report error messages and warnings via the compiler.
protected Properties	messages Maps error keys to localized/custom error messages.
protected Pattern	skipPattern A regular expression for classes that should be skipped.
protected Trees	trees Used as a helper for the SourceVisitor.

Fields inherited from class javax.annotation.processing.AbstractProcessor

processingEnv

Constructor Summary

SourceChecker()

Method Summary

protected boolean	attribute(Set<? extends TypeElement> elements) Attribute the trees associated with the provided elements.
AnnotatedTypeFactory	createFactory(CompilationUnitTree root)
protected abstract SourceVisitor<?,?>	createSourceVisitor(CompilationUnitTree root) Provides the SourceVisitor that the checker should use to scan input source trees.
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()
Pattern	getShouldSkip() Returns a regular expression pattern to specify java classes that are not annotated, and thus whose warnings and should be surpressed.
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()
protected String	getSuppressWarningsKey()
void	init(ProcessingEnvironment processingEnv)
protected void	message(Diagnostic.Kind kind, Object source, Object msgKey, Object... args) Prints a message (error, warning, note, etc.) via JSR-269.
boolean	process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) Type-check the code with Java specifications and then runs the Checker Rule Checking visitor on the processed source.
void	report(Result r, Object src) Reports a result.
boolean	shouldSkip(String className) Determines whether checking against members of the class with the given name should be performed.

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

Field Detail

env

protected ProcessingEnvironment env

Provides access to compiler helpers/internals.

messages

protected Properties messages

Maps error keys to localized/custom error messages.

messager

protected com.sun.tools.javac.processing.JavacMessager messager

Used to report error messages and warnings via the compiler.

trees

protected Trees trees

Used as a helper for the SourceVisitor.

currentRoot

protected CompilationUnitTree currentRoot

The source tree that's being scanned.

skipPattern

protected final Pattern skipPattern

A regular expression for classes that should be skipped.

Constructor Detail

SourceChecker

public SourceChecker()

Method Detail

getProcessingEnvironment

public ProcessingEnvironment getProcessingEnvironment()

Returns:

the ProcessingEnvironment that was supplied to this checker

createFactory

public AnnotatedTypeFactory createFactory(CompilationUnitTree root)

Parameters:

root - the AST root for the factory

Returns:

an AnnotatedTypeFactory for use by typecheckers

createSourceVisitor

protected abstract SourceVisitor<?,?> createSourceVisitor(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

init

public void init(ProcessingEnvironment processingEnv)

Specified by:

init in interface Processor

Overrides:

init in class AbstractProcessor

See Also:

AbstractProcessor.init(ProcessingEnvironment)

process

public boolean process(Set<? extends TypeElement> annotations,
                       RoundEnvironment roundEnv)

Type-check the code with Java specifications and then runs the Checker Rule Checking visitor on the processed source. The Processor is invoked in the annotation processing phase, before the code is type-checked by the compiler. This method ensures that only Java valid code is processed by the Rule Checking visitor.

Specified by:

process in interface Processor

Specified by:

process in class AbstractProcessor

See Also:

Processor.process(Set, RoundEnvironment)

attribute

protected boolean attribute(Set<? extends TypeElement> elements)

Attribute the trees associated with the provided elements. Assumes that all elements are of type TypeElement. The attribution phase involves two tasks, essential for the checkers: 1. type-checking the code, and issuing errors if the code does not adhere to Java specification. A processor should only run if the code is a valid code. 2. evaluating the type of each tree and creating the symbol table for the tree, i.e. resolves the identities (variables, methods, classes) referred to by tree identifiers.

Parameters:

elements -

Returns:

true iff if the code type-checks with Java Specification

message

protected void message(Diagnostic.Kind kind,
                       Object source,
                       Object 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,
                   Object src)

Reports a result. By default, it prints it to the screen via the compiler's internal messeger 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

shouldSkip

public boolean shouldSkip(String className)

Determines whether checking against members of the class with the given name should be performed. This method will return true only when the given class name matches the regular expression specified by the checkers.skipClasses property.

Parameters:

className - the fully qualified name of the class to check

Returns:

true if the members of the class named className should not be checked against

getLintOption

public final boolean getLintOption(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(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<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<String> getSupportedOptions()

Specified by:

getSupportedOptions in interface Processor

Overrides:

getSupportedOptions in class AbstractProcessor

getSupportedAnnotationTypes

public final Set<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

@Nullable
protected String getSuppressWarningsKey()

Returns:

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

See Also:

SuppressWarningsKey

getShouldSkip

public Pattern getShouldSkip()

Returns a regular expression pattern to specify java classes that are not annotated, and thus whose warnings and should be surpressed. It returns the pattern specified by the user, through the option checkers.skipClasses; otherwise it returns a pattern that can match no class.

Returns:

pattern of un-annotated classes that should be skipped

getSupportedSourceVersion

public SourceVersion getSupportedSourceVersion()

Specified by:

getSupportedSourceVersion in interface Processor

Overrides:

getSupportedSourceVersion in class AbstractProcessor