checkers.source
Class SourceChecker

java.lang.Object
  extended by javax.annotation.processing.AbstractProcessor
      extended by 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:

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