Package org.checkerframework.framework.source

Class SourceChecker

java.lang.Object
javax.annotation.processing.AbstractProcessor
org.checkerframework.javacutil.AbstractTypeProcessor
org.checkerframework.framework.source.SourceChecker
All Implemented Interfaces:
Processor, OptionConfiguration
Direct Known Subclasses:
AggregateChecker, AnnotationStatistics, BaseTypeChecker, JavaCodeStatistics
@SupportedOptions({"suppressWarnings","skipUses","onlyUses","skipDefs","onlyDefs","skipFiles","onlyFiles","skipDirs","assumeSideEffectFree","assumeDeterministic","assumePure","assumePureGetters","assumeAssertionsAreEnabled","assumeAssertionsAreDisabled","warns","checkPurityAnnotations","invariantArrays","checkCastElementType","useConservativeDefaultsForUncheckedCode","concurrentSemantics","warnRedundantAnnotations","ignoreRawTypeArguments","lint","suggestPureMethods","resolveReflection","infer","inferOutputOriginal","showSuppressWarningsStrings","warnUnneededSuppressions","warnUnneededSuppressionsExceptions","requirePrefixInWarningSuppressions","showPrefixInWarningMessages","ignoreInvalidAnnotationLocations","stubs","ajava","stubWarnIfNotFound","stubNoWarnIfNotFound","stubWarnIfNotFoundIgnoresClasses","stubWarnIfOverwritesBytecode","stubWarnIfRedundantWithBytecode","stubWarnNote","mergeStubsWithSource","version","printGitProperties","printAllQualifiers","printVerboseGenerics","noPrintErrorStack","noWarnMemoryConstraints","nomsgtext","exceptionLineSeparator","detailedmsgtext","ignorejdkastub","permitMissingJdk","nocheckjdk","parseAllJdk","stubDebug","filenames","showchecks","dumpOnErrors","cfgviz","flowdotdir","verbosecfg","atfCacheSize","atfDoNotCache","lspTypeInfo","resourceStats","ajavaChecks","convertTypeArgInferenceCrashToWarning"}) public abstract class SourceChecker extends AbstractTypeProcessor implements OptionConfiguration
An abstract annotation processor designed for implementing a source-file checker as an annotation processor (a 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.

Most type-checker plug-ins should extend BaseTypeChecker, instead of this class. Only checkers that require annotated types but not subtype checking (e.g. for testing purposes) should extend this. Non-type checkers (e.g. for enforcing coding styles) may extend AbstractProcessor (or even this class).

  • Field Details

    • SUPPRESS_ALL_MESSAGE_KEY

      public static final String SUPPRESS_ALL_MESSAGE_KEY
      The message key that will suppress all warnings (it matches any message key).
      See Also:

    • SUPPRESS_ALL_PREFIX

      public static final String SUPPRESS_ALL_PREFIX
      The SuppressWarnings prefix that will suppress warnings for all checkers.
      See Also:

    • UNNEEDED_SUPPRESSION_KEY

      public static final @CompilerMessageKey String UNNEEDED_SUPPRESSION_KEY
      The message key emitted when an unused warning suppression is found.
      See Also:

    • MSGS_FILE

      protected static final String MSGS_FILE
      File name of the localized messages.
      See Also:

    • messagesProperties

      protected Properties messagesProperties
      Maps error keys to localized/custom error messages. Do not use directly; call fullMessageOf(java.lang.String, java.lang.String) or processErrorMessageArg(java.lang.Object). Is set in initChecker().

    • messager

      protected Messager messager
      Used to report error messages and warnings via the compiler. Is set in typeProcessingStart().

    • elements

      protected Elements elements
      Element utilities.

    • trees

      protected Trees trees
      Tree utilities; used as a helper for the SourceVisitor.

    • types

      protected Types types
      Type utilities.

    • currentRoot

      protected @MonotonicNonNull @InternedDistinct CompilationUnitTree currentRoot
      The source tree that is being scanned. Is set in setRoot(com.sun.source.tree.CompilationUnitTree).

    • visitor

      protected SourceVisitor<?,?> visitor
      The visitor to use.

    • suppressWarningsPrefixesOfSubcheckers

      protected @MonotonicNonNull Collection<String> suppressWarningsPrefixesOfSubcheckers
      The list of suppress warnings prefixes supported by this checker or any of its subcheckers (including indirect subcheckers). Do not access this field directly; instead, use getSuppressWarningsPrefixesOfSubcheckers().

    • messageStore

      protected @MonotonicNonNull TreeSet<SourceChecker.CheckerMessage> messageStore
      Stores all messages issued by this checker and its subcheckers for the current compilation unit. The messages are printed after all checkers have processed the current compilation unit. The purpose is to sort messages, grouping together all messages about a particular line of code.

      If this checker has no subcheckers and is not a subchecker for any other checker, then messageStore is null and messages will be printed as they are issued by this checker.

    • useAllcheckersPrefix

      protected boolean useAllcheckersPrefix
      If true, use the "allcheckers:" warning string prefix.

      Checkers that never issue any error messages should set this to false. That prevents -AwarnUnneededSuppressions from issuing warnings about @SuppressWarnings("allcheckers:...").

    • activeOptions

      protected @MonotonicNonNull Map<String,String> activeOptions
      The active options for this checker. This is a processed version of ProcessingEnvironment.getOptions(): If the option is of the form "-ACheckerName_key=value" and the current checker class, or one of its superclasses, is named "CheckerName", then add key → value. If the option is of the form "-ACheckerName_key=value" and the current checker class, and none of its superclasses, is named "CheckerName", then do not add key → value. If the option is of the form "-Akey=value", then add key → value.

      Both the simple and the canonical name of the checker can be used. Superclasses of the current checker are also considered.

    • supportedOptions

      protected @MonotonicNonNull Set<String> supportedOptions
      Supported options for this checker. This is the set of all possible options that could be passed to this checker. By contrast, activeOptions is a map for options that were passed for this run of the checker.

    • OPTION_SEPARATOR

      protected static final String OPTION_SEPARATOR
      The string that separates the checker name from the option name in a "-A" command-line argument. This string may only consist of valid Java identifier part characters, because it will be used within the key of an option.
      See Also:

    • parentChecker

      protected @Nullable SourceChecker parentChecker
      The checker that called this one, whether that be a BaseTypeChecker (used as a compound checker) or an AggregateChecker. Null if this is the checker that calls all others. Note that in the case of a compound checker, the compound checker is the parent, not the checker that was run prior to this one by the compound checker.

    • upstreamCheckerNames

      protected @MonotonicNonNull List<@FullyQualifiedName String> upstreamCheckerNames
      List of upstream checker names. Includes the current checker.

    • subcheckers

      protected @MonotonicNonNull List<SourceChecker> subcheckers
      The full list of subcheckers that need to be run prior to this one, in the order they need to be run. This list will only be non-empty for the one checker that runs all other subcheckers. Do not read this field directly. Instead, retrieve it via getSubcheckers().

      This field will be null until getSubcheckers is called. getSubcheckers sets this field to an immutable list which is empty for all but the ultimate parent checker.

    • immediateSubcheckers

      protected @MonotonicNonNull List<SourceChecker> immediateSubcheckers
      The list of subcheckers that are direct dependencies of this checker. This list will be non-empty for any checker that has at least one subchecker.

    • treePathCacher

      protected TreePathCacher treePathCacher
      TreePathCacher to share between subcheckers. Initialized either in getTreePathCacher() or instantiateSubcheckers(Map).

    • javacErrored

      protected boolean javacErrored
      If true, javac failed to compile the code or a previously-run annotation processor issued an error.

    • DETAILS_SEPARATOR

      public static final String DETAILS_SEPARATOR
      Separates parts of a "detailed message", to permit easier parsing.
      See Also:

    • elementsWithSuppressedWarnings

      protected final Set<Element> elementsWithSuppressedWarnings
      Elements with a @SuppressWarnings that actually suppressed a warning for this checker.

  • Constructor Details

    • SourceChecker

      protected SourceChecker()
      Creates a source checker.

  • Method Details

    • init

      public final void init(ProcessingEnvironment env)
      Description copied from class: AbstractTypeProcessor

      Register a TaskListener that will get called after FLOW.

      Specified by:
      init in interface Processor
      Overrides:
      init in class AbstractTypeProcessor

    • getProcessingEnvironment

      public ProcessingEnvironment getProcessingEnvironment()
      Returns the ProcessingEnvironment that was supplied to this checker.
      Returns:
      the ProcessingEnvironment that was supplied to this checker

    • setParentChecker

      protected void setParentChecker(SourceChecker parentChecker)
      Set the parent checker of the current checker.

    • getParentChecker

      public @Nullable SourceChecker getParentChecker()
      Returns the immediate parent checker of the current checker.
      Returns:
      the immediate parent checker of the current checker, or null if there is none

    • setRoot

      public void setRoot(CompilationUnitTree newRoot)
      Invoked when the current compilation unit root changes.
      Parameters:
      newRoot - the new compilation unit root

    • getUpstreamCheckerNames

      public List<@FullyQualifiedName String> getUpstreamCheckerNames()
      Returns a list containing this checker name and all checkers it is a part of (that is, checkers that called it).
      Returns:
      a list containing this checker name and all checkers it is a part of (that is, checkers that called it)

    • getOptionConfiguration

      public OptionConfiguration getOptionConfiguration()
      Returns the OptionConfiguration associated with this.
      Returns:
      the OptionConfiguration associated with this

    • getElementUtils

      public Elements getElementUtils()
      Returns the element utilities associated with this.
      Returns:
      the element utilities associated with this

    • getTypeUtils

      public Types getTypeUtils()
      Returns the type utilities associated with this.
      Returns:
      the type utilities associated with this

    • getTreeUtils

      public Trees getTreeUtils()
      Returns the tree utilities associated with this.
      Returns:
      the tree utilities associated with this

    • getVisitor

      public SourceVisitor<?,?> getVisitor()
      Returns the SourceVisitor associated with this.
      Returns:
      the SourceVisitor associated with this

    • getOptionsNoSubcheckers

      public Map<String,String> getOptionsNoSubcheckers()
      Like getOptions(), but only includes options passed to this checker. Does not include those passed only to subcheckers.
      Returns:
      the active options for this checker, not including those passed only to subcheckers

    • hasOptionNoSubcheckers

      public final boolean hasOptionNoSubcheckers(String name)
      Like hasOption(java.lang.String), but checks whether the given option is passed to this checker. Does not consider options only passed to subcheckers.
      Parameters:
      name - the name of the option to check
      Returns:
      true if the option name was passed to this checker, false otherwise

    • getExtraStubFiles

      public List<String> getExtraStubFiles()
      Return a list of stub files to be treated as if they had been written in a @StubFiles annotation.
      Returns:
      stub files to be treated as if they had been written in a @StubFiles annotation

    • createSourceVisitor

      protected abstract SourceVisitor<?,?> createSourceVisitor()
      Provides the SourceVisitor that the checker should use to scan input source trees.
      Returns:
      a SourceVisitor to use to scan source trees

    • getAnnotationProvider

      public AnnotationProvider getAnnotationProvider()
      Returns the AnnotationProvider (the type factory) associated with this.
      Returns:
      the AnnotationProvider (the type factory) associated with this

    • getMessagesProperties

      public Properties getMessagesProperties()
      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

    • 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 override initChecker. This allows us to handle BugInCF only here and doesn't require all overriding implementations to be aware of BugInCF.

      Overrides:
      typeProcessingStart in class AbstractTypeProcessor
      See Also:

    • typeProcessingOver

      public void typeProcessingOver()
      Description copied from class: AbstractTypeProcessor
      A method to be called once all the classes are processed.

      Subclasses may override this method to do any aggregate analysis (e.g. generate report, persistence) or resource deallocation.

      Method AbstractTypeProcessor.getCompilerLog() can be used to access the number of compiler errors.

      Overrides:
      typeProcessingOver in class AbstractTypeProcessor

    • initChecker

      public void initChecker()
      Initialize the checker.
      See Also:

    • getSubchecker

      public <T extends SourceChecker> @Nullable T getSubchecker(Class<T> checkerClass)
      Returns the requested (immediate) subchecker. A checker of a given class can only be run once, so this returns the only such checker, or null if none was found. The caller must know the exact checker class to request.
      Type Parameters:
      T - the class of the subchecker to return
      Parameters:
      checkerClass - the class of the subchecker to return
      Returns:
      the requested (immediate) subchecker or null if not found

    • instantiateSubcheckers

      protected List<SourceChecker> instantiateSubcheckers(Map<Class<? extends SourceChecker>,SourceChecker> alreadyInitializedSubcheckerMap)
      Computes the unmodifiable list of immediate subcheckers of this checker, in the order the checkers need to be run.

      Modifies the alreadyInitializedSubcheckerMap parameter by adding all recursively newly instantiated subcheckers' class objects and instances. It is necessary to use a map that preserves the order in which entries were inserted, such as LinkedHashMap or ArrayMap.

      Parameters:
      alreadyInitializedSubcheckerMap - subcheckers that have already been instantiated. Is modified by this method. Its point is to ensure that if two checkers A and B both depend on checker C, then checker C is instantiated and run only once, not twice.
      Returns:
      the unmodifiable list of immediate subcheckers of this checker

    • getSubcheckers

      public List<SourceChecker> getSubcheckers()
      Get the list of all subcheckers (if any). This list is only non-empty for the one checker that runs all other subcheckers. These are recursively instantiated via instantiateSubcheckers() the first time this method is called if field subcheckers is null. Assumes all checkers run on the same thread.
      Returns:
      the list of all subcheckers (if any)

    • getTreePathCacher

      public TreePathCacher getTreePathCacher()
      Get the shared TreePathCacher instance.
      Returns:
      the shared TreePathCacher instance.

    • typeProcess

      public void typeProcess(TypeElement e, TreePath p)
      Type-check the code using this checker's visitor.
      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:

    • reportError

      public void reportError(@Nullable Object source, @CompilerMessageKey String messageKey, Object... args)
      Reports an error. By default, prints it to the screen via the compiler's internal messager.
      Parameters:
      source - the source position information; may be an Element, a Tree, or null
      messageKey - the message key
      args - arguments for interpolation in the string corresponding to the given message key

    • reportWarning

      public void reportWarning(@Nullable Object source, @CompilerMessageKey String messageKey, Object... args)
      Reports a warning. By default, prints it to the screen via the compiler's internal messager.
      Parameters:
      source - the source position information; may be an Element, a Tree, or null
      messageKey - the message key
      args - arguments for interpolation in the string corresponding to the given message key

    • report

      public void report(@Nullable Object source, DiagMessage d)
      Reports a diagnostic message. By default, prints it to the screen via the compiler's internal messager.

      It is rare to use this method. Most clients should use reportError(java.lang.Object, java.lang.String, java.lang.Object...) or reportWarning(java.lang.Object, java.lang.String, java.lang.Object...).

      Parameters:
      source - the source position information; may be an Element, a Tree, or null
      d - the diagnostic message

    • message

      @FormatMethod public void message(Diagnostic.Kind kind, String msg, Object... args)
      Print a non-localized message using the javac messager. This is preferable to using System.out or System.err, but should only be used for exceptional cases that don't happen in correct usage. Localized messages should be raised using reportError(java.lang.Object, java.lang.String, java.lang.Object...), reportWarning(java.lang.Object, java.lang.String, java.lang.Object...), etc.
      Parameters:
      kind - the kind of message to print
      msg - the message text
      args - optional arguments to substitute in the message
      See Also:

    • message

      public void message(Diagnostic.Kind kind, String msg)
      Print a non-localized message using the javac messager. This is preferable to using System.out or System.err, but should only be used for exceptional cases that don't happen in correct usage. Localized messages should be raised using reportError(java.lang.Object, java.lang.String, java.lang.Object...), reportWarning(java.lang.Object, java.lang.String, java.lang.Object...), etc.
      Parameters:
      kind - the kind of message to print
      msg - the message text
      See Also:

    • getSuppressWarningsPrefixesOfSubcheckers

      public Collection<String> getSuppressWarningsPrefixesOfSubcheckers()
      Like getSuppressWarningsPrefixes(), but includes all prefixes supported by this checker or any of its subcheckers. Does not guarantee that the result is in any particular order. The result is immutable.
      Returns:
      the suppress warnings prefixes supported by this checker or any of its subcheckers

    • printOrStoreMessage

      protected void printOrStoreMessage(Diagnostic.Kind kind, String message, Tree source, CompilationUnitTree root)
      Do not call this method. Call reportError(java.lang.Object, java.lang.String, java.lang.Object...) or reportWarning(java.lang.Object, java.lang.String, java.lang.Object...) instead.

      This method exists so that the BaseTypeChecker can override it. For compound checkers, it stores all messages and sorts them by location before outputting them.

      Parameters:
      kind - the kind of message to print
      message - the message text
      source - the source code position of the diagnostic message
      root - the compilation unit

    • printOrStoreMessage

      protected void printOrStoreMessage(Diagnostic.Kind kind, String message, Tree source, CompilationUnitTree root, StackTraceElement[] trace)
      Do not call this method. Call reportError(java.lang.Object, java.lang.String, java.lang.Object...) or reportWarning(java.lang.Object, java.lang.String, java.lang.Object...) instead.

      This method exists so that the BaseTypeChecker can override it. For compound checkers, it stores all messages and sorts them by location before outputting them.

      Parameters:
      kind - the kind of message to print
      message - the message text
      source - the source code position of the diagnostic message
      root - the compilation unit
      trace - the stack trace where the checker encountered an error. It is printed when the dumpOnErrors option is enabled.

    • fullMessageOf

      protected String fullMessageOf(String messageKey, String defaultValue)
      Returns the localized long message corresponding to this key. If not found, tries suffixes of this key, stripping off dot-separated prefixes. If still not found, returns defaultValue.
      Parameters:
      messageKey - a message key
      defaultValue - a default value to use if messageKey is not a message key
      Returns:
      the localized long message corresponding to this key or a suffix, or defaultValue

    • processErrorMessageArg

      protected Object processErrorMessageArg(Object arg)
      Process an argument to an error message before it is passed to String.format.

      This implementation expands the argument if it is exactly a message key.

      By contrast, fullMessageOf(java.lang.String, java.lang.String) processes the message key itself but not the arguments, and tries suffixes.

      Parameters:
      arg - the argument
      Returns:
      the result after processing

    • 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

      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:

    • setLintOption

      protected final void setLintOption(String name, boolean val)
      Set 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". This method can be used by subclasses to enforce having certain lint options enabled/disabled.
      Parameters:
      name - the name of the lint option to set
      val - the option value
      Throws:
      IllegalArgumentException - if the option name is not recognized via the SupportedLintOptions annotation or the getSupportedLintOptions() method
      See Also:

    • getImmediateSubcheckerClasses

      protected Set<Class<? extends SourceChecker>> getImmediateSubcheckerClasses()
      Returns the set of subchecker classes on which this checker depends. ("Depends" means the checkers that are subcheckers of the current checker rather than a subchecker of some other checker.) Returns an empty set if this checker does not depend on any others.

      If this checker should run multiple independent checkers and not contain a type system, then subclass AggregateChecker.

      Subclasses should override this method to specify subcheckers. If they do so, they should call the super implementation of this method and add dependencies to the returned set so that checkers required for reflection resolution are included if reflection resolution is requested.

      If a checker should be added or not based on a command line option, use getOptionsNoSubcheckers() or hasOptionNoSubcheckers(String) to avoid recursively calling this method.

      Each subchecker of this checker may also depend on other checkers. If this checker and one of its subcheckers both depend on a third checker, that checker will only be instantiated once.

      Though each checker is run on a whole compilation unit before the next checker is run, error and warning messages are collected and sorted based on the location in the source file before being printed. (See printOrStoreMessage(Diagnostic.Kind, String, Tree, CompilationUnitTree).)

      WARNING: Circular dependencies are not supported. (In other words, if checker A depends on checker B, checker B cannot depend on checker A.) The Checker Framework does not check for circularity. Make sure no circular dependencies are created when overriding this method.

      This method is protected so it can be overridden, but it should only be called internally by SourceChecker.

      Returns:
      the subchecker classes on which this checker depends; will be modified by callees

    • shouldResolveReflection

      public boolean shouldResolveReflection()
      Returns true if reflection should be resolved.
      Returns:
      true if reflection should be resolved

    • getRelatedClassName

      public static @ClassGetName String getRelatedClassName(Class<?> checkerClass, String replacement)
      Returns the name of a class related to a given one, by replacing "Checker" or "Subchecker" by replacement.
      Parameters:
      checkerClass - the checker class
      replacement - the string that replaces "Checker" or "Subchecker"
      Returns:
      the name of the related class

    • 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

    • createSupportedLintOptions

      protected Set<String> createSupportedLintOptions()
      Compute the set of supported lint options for this checker and its subcheckers.
      Returns:
      the set of supported lint options for this checker and its subcheckers

    • getOptions

      public Map<String,String> getOptions()
      Description copied from interface: OptionConfiguration
      Return all active options for this checker.
      Specified by:
      getOptions in interface OptionConfiguration
      Returns:
      all active options for this checker

    • hasOption

      public final boolean hasOption(String name)
      Description copied from interface: OptionConfiguration
      Check whether the given option is provided.

      Note that OptionConfiguration.getOption(java.lang.String) can still return null even if hasOption returns true: this happens e.g. for -Amyopt

      Specified by:
      hasOption in interface OptionConfiguration
      Parameters:
      name - the name of the option to check
      Returns:
      true if the option name was provided, false otherwise

    • getOption

      public final String getOption(String name)
      Determines the value of the option with the given name.

      Note that getOption can still return null even if OptionConfiguration.hasOption(java.lang.String) returns true: this happens e.g. for -Amyopt

      Specified by:
      getOption in interface OptionConfiguration
      Parameters:
      name - the name of the option to check
      Returns:
      the value of the option with the given name
      See Also:

    • getOption

      public final String getOption(String name, String defaultValue)
      Determines the boolean value of the option with the given name. Returns defaultValue if the option is not set.
      Specified by:
      getOption in interface OptionConfiguration
      Parameters:
      name - the name of the option to check
      defaultValue - the default value to return if the option is not set
      Returns:
      the value of the option with the given name, or defaultValue
      See Also:

    • getBooleanOption

      public final boolean getBooleanOption(String name)
      Determines the boolean value of the option with the given name. Returns false if the option is not set.
      Specified by:
      getBooleanOption in interface OptionConfiguration
      Parameters:
      name - the name of the option to check
      Returns:
      the boolean value of the option
      See Also:

    • getBooleanOption

      public final boolean getBooleanOption(String name, boolean defaultValue)
      Determines the boolean value of the option with the given name. Returns the given default value if the option is not set.
      Specified by:
      getBooleanOption in interface OptionConfiguration
      Parameters:
      name - the name of the option to check
      defaultValue - the default value to use if the option is not set
      Returns:
      the boolean value of the option
      See Also:

    • getStringsOption

      public final List<String> getStringsOption(String name, char separator, List<String> defaultValue)
      Determines the string list value of the option with the given name. The option's value is split on the given separator. Returns the given default value if the option is not set.
      Specified by:
      getStringsOption in interface OptionConfiguration
      Parameters:
      name - the name of the option to check
      separator - the separator for list elements
      defaultValue - the default value to use if the option is not set
      Returns:
      the list of options
      See Also:

    • getStringsOption

      public final List<String> getStringsOption(String name, String separator, List<String> defaultValue)
      Determines the string list value of the option with the given name. The option's value is split on the given separator. Returns the given default value if the option is not set.
      Specified by:
      getStringsOption in interface OptionConfiguration
      Parameters:
      name - the name of the option to check
      separator - the separator for list elements
      defaultValue - the default value to use if the option is not set
      Returns:
      the list of options
      See Also:

    • printStoredMessages

      protected void printStoredMessages(CompilationUnitTree unit)
      Prints error messages for this checker and all subcheckers such that the errors are ordered by line and column number and then by checker. (See SourceChecker.CheckerMessage.compareTo(CheckerMessage) for more precise order.)
      Parameters:
      unit - current compilation unit

    • getSupportedOptions

      public Set<String> getSupportedOptions()
      Description copied from interface: OptionConfiguration
      Map the Checker Framework version of SupportedOptions to the standard annotation provided version SupportedOptions.
      Specified by:
      getSupportedOptions in interface OptionConfiguration
      Specified by:
      getSupportedOptions in interface Processor
      Overrides:
      getSupportedOptions in class AbstractProcessor
      Returns:
      the supported options

    • expandCFOptions

      protected Collection<String> expandCFOptions(List<? extends Class<?>> clazzPrefixes, String[] options)
      Generate the possible command-line option names by prefixing each class name from classPrefixes to options, separated by OPTION_SEPARATOR.
      Parameters:
      clazzPrefixes - the classes to prefix
      options - the option names
      Returns:
      the possible combinations that should be supported

    • getSupportedAnnotationTypes

      public final Set<String> getSupportedAnnotationTypes()
      Overrides the default implementation to always return a singleton set containing only "*".

      javac uses this list to determine which classes process; javac only runs an annotation processor on classes that contain at least one of the mentioned annotations. Thus, 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, see AnnotatedTypeFactory.createSupportedTypeQualifiers().

      Specified by:
      getSupportedAnnotationTypes in interface Processor
      Overrides:
      getSupportedAnnotationTypes in class AbstractProcessor
      Throws:
      Error - if a subclass is annotated with SupportedAnnotationTypes

    • warnUnneededSuppressions

      protected void warnUnneededSuppressions()
      Issues a warning about any @SuppressWarnings that didn't suppress a warning, but starts with this checker name or "allcheckers".

    • warnUnneededSuppressions

      protected void warnUnneededSuppressions(Set<Element> elementsSuppress, Set<String> prefixes, Set<String> allErrorKeys)
      Issues a warning about any @SuppressWarnings string that didn't suppress a warning, but starts with one of the given prefixes (checker names). Does nothing if the string doesn't start with a checker name.
      Parameters:
      elementsSuppress - elements with a @SuppressWarnings that actually suppressed a warning
      prefixes - the SuppressWarnings prefixes that suppress all warnings from this checker
      allErrorKeys - all error keys that can be issued by this checker

    • shouldSuppressWarnings

      public boolean shouldSuppressWarnings(Tree tree, String errKey)
      Returns true if all the warnings pertaining to a given tree should be suppressed. Returns true if the tree is within the scope of a @SuppressWarnings annotation, one of whose values suppresses the checker's warning. Also, returns true if the errKey matches a string in -AsuppressWarnings.
      Parameters:
      tree - the tree that might be a source of a warning
      errKey - the error key the checker is emitting
      Returns:
      true if no warning should be emitted for the given tree because it is contained by a declaration with an appropriately-valued @SuppressWarnings annotation; false otherwise

    • shouldSuppressWarnings

      public boolean shouldSuppressWarnings(@Nullable TreePath path, String errKey)
      Returns true if all the warnings pertaining to a given tree path should be suppressed. Returns true if the path is within the scope of a @SuppressWarnings annotation, one of whose values suppresses the checker's warning.
      Parameters:
      path - the TreePath that might be a source of, or related to, a warning
      errKey - the error key the checker is emitting
      Returns:
      true if no warning should be emitted for the given path because it is contained by a declaration with an appropriately-valued @SuppressWarnings annotation; false otherwise

    • useConservativeDefault

      public boolean useConservativeDefault(String kindOfCode)
      Should conservative defaults be used for the kind of unchecked code indicated by the parameter?
      Parameters:
      kindOfCode - source or bytecode
      Returns:
      whether conservative defaults should be used

    • shouldSuppressWarnings

      public boolean shouldSuppressWarnings(@Nullable Element elt, String errKey)
      Returns true if all the warnings pertaining to a given element should be suppressed. Returns true if the element is within the scope of a @SuppressWarnings annotation, one of whose values suppresses all the checker's warnings.
      Parameters:
      elt - the Element that might be a source of, or related to, a warning
      errKey - the error key the checker is emitting
      Returns:
      true if no warning should be emitted for the given Element because it is contained by a declaration with an appropriately-valued @SuppressWarnings annotation; false otherwise

    • messageKeyMatches

      protected boolean messageKeyMatches(String messageKey, String messageKeyInSuppressWarningsString)
      Does the given messageKey match a messageKey that appears in a SuppressWarnings? Subclasses should override this method if they need additional logic to compare message keys.
      Parameters:
      messageKey - the message key of the error that is being emitted, without any "checker:" prefix
      messageKeyInSuppressWarningsString - the message key in a @SuppressWarnings annotation
      Returns:
      true if the arguments match

    • getSuppressWarningsPrefixes

      public NavigableSet<String> getSuppressWarningsPrefixes()
      Returns a modifiable set of lower-case strings that are prefixes for SuppressWarnings strings.

      The collection must not be empty and must not contain only SUPPRESS_ALL_PREFIX.

      Returns:
      non-empty modifiable set of lower-case prefixes for SuppressWarnings strings

    • getStandardSuppressWarningsPrefixes

      protected final NavigableSet<String> getStandardSuppressWarningsPrefixes()
      Returns a sorted set of SuppressWarnings prefixes read from the SuppressWarningsPrefix meta-annotation on the checker class. Or if no SuppressWarningsPrefix is used, the checker name is used. SUPPRESS_ALL_PREFIX is also added, at the end, unless useAllcheckersPrefix is false.
      Returns:
      a sorted set of SuppressWarnings prefixes

    • 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

    • shouldSkipUses

      public boolean shouldSkipUses(@FullyQualifiedName String typeName)
      Tests whether the class owner of the passed type matches the pattern specified in the checker.skipUses property. In contrast to shouldSkipUses(Element) this version can also be used from primitive types, which don't have an element.

      Checkers that require their annotations not to be checked on certain JDK classes may override this method to skip them. They shall call super.shouldSkipUses(typeName) to also skip the classes matching the pattern.

      Parameters:
      typeName - the fully-qualified name of a type
      Returns:
      true iff the enclosing class of element should be skipped

    • shouldSkipDefs

      public final boolean shouldSkipDefs(ClassTree tree)
      Tests whether the class definition should not be checked because it matches the checker.skipDefs property.
      Parameters:
      tree - class to potentially skip
      Returns:
      true if checker should not type-check tree

    • shouldSkipDefs

      public boolean shouldSkipDefs(MethodTree tree)
      Tests whether the method definition should not be checked because it matches the checker.skipDefs property.
      Parameters:
      tree - method to potentially skip
      Returns:
      true if checker should not type-check tree

    • shouldSkipDefs

      public final boolean shouldSkipDefs(ClassTree cls, 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 type-check meth

    • shouldSkipFiles

      public final boolean shouldSkipFiles(ClassTree tree)
      Tests whether the enclosing file path of the passed tree matches the pattern specified in the checker.skipFiles property.
      Parameters:
      tree - a tree
      Returns:
      true iff the enclosing directory of the tree should be skipped

    • shouldAddShutdownHook

      protected boolean shouldAddShutdownHook()
      Return true to indicate that method shutdownHook() should be added as a shutdownHook of the JVM.
      Returns:
      true to add shutdownHook() as a shutdown hook of the JVM

    • shutdownHook

      protected void shutdownHook()
      Method that gets called exactly once at shutdown time of the JVM. Checkers can override this method to customize the behavior.

      If you override this, you must also override shouldAddShutdownHook() to return true.

    • printStats

      protected void printStats()
      Print resource usage statistics.

    • getProperties

      protected Properties getProperties(Class<?> cls, String filePath, boolean permitNonExisting)
      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
      permitNonExisting - if true, return an empty Properties if the file does not exist or cannot be parsed; if false, issue an error
      Returns:
      the properties

    • getSupportedSourceVersion

      public final SourceVersion getSupportedSourceVersion()
      Specified by:
      getSupportedSourceVersion in interface Processor
      Overrides:
      getSupportedSourceVersion in class AbstractProcessor

    • getPathToCompilationUnit

      public TreePath getPathToCompilationUnit()
      Return the path to the current compilation unit.
      Returns:
      path to the current compilation unit

    • getSubCheckerIndex

      protected int getSubCheckerIndex()
      Index of this checker in getSubcheckers() (when getSubcheckers() is called on the ultimate ancestor), or the size of getSubcheckers() if this is the ancestor checker.
      Returns:
      index of this checker in the ultimate ancestor's getSubcheckers(), or the size of getSubcheckers() if this is the ancestor checker