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

@Default(value="checkers.nonnull.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)
• SourceChecker#getSourceVisitor (for a custom SourceVisitor)
• createFactory(com.sun.source.tree.CompilationUnitTree) (for a custom AnnotatedTypeFactory)
• getSuppressWarningsKey() (for honoring SuppressWarnings annotations)

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

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 "*", forcing all type checkers to run always (even on unannotated code), and explicitly checks that subclasses do not contain a SupportedAnnotationTypes annotation on their declarations.
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)
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.

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(javax.annotation.processing.ProcessingEnvironment)

process

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

Specified by:

process in interface Processor

Specified by:

process in class AbstractProcessor

See Also:

AbstractProcessor.process(java.util.Set, javax.annotation.processing.RoundEnvironment)

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 boolean getLintOption(String name)

Determines the value of the lint option with the given name. Lint options are provided in a similar manner to standard javac lint options: as a list of option names, or option names prepended with a "-", following the "-Alint=" javac switch. If the option name is present without a "-", it returns true; if the option name is present but prepended with a "-" or it is not present at all, this method returns false.

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 boolean getLintOption(String name,
                             boolean def)

Determines the value of the lint option with the given name. Lint options are provided in a similar manner to standard javac lint options: as a list of option names, or option names prepended with a "-", following the "-Alint=" javac switch. If the option name is present without a "-", this method returns true; if the option name is present but prepended with a "-", it returns false. If the option is not present at all, it returns the value of the def argument (the default option value).

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)

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 "*", forcing all type checkers to run always (even on unannotated code), and explicitly checks that subclasses do not contain a SupportedAnnotationTypes annotation on their declarations. 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()

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

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