Class BaseTypeChecker

    • Constructor Detail

      • BaseTypeChecker

        public BaseTypeChecker()
    • Method Detail

      • initChecker

        public void initChecker()
        Description copied from class: SourceChecker
        Initialize the checker.
        Overrides:
        initChecker in class SourceChecker
        See Also:
        AbstractProcessor.init(ProcessingEnvironment)
      • setRoot

        protected void setRoot​(com.sun.source.tree.CompilationUnitTree newRoot)
        Description copied from class: SourceChecker
        Invoked when the current compilation unit root changes.
        Overrides:
        setRoot in class SourceChecker
        Parameters:
        newRoot - the new compilation unit root
      • getImmediateSubcheckerClasses

        protected java.util.Set<java.lang.Class<? extends BaseTypeChecker>> getImmediateSubcheckerClasses()
        Returns the set of subchecker classes on which this checker depends. Returns an empty set if this checker does not depend on any others.

        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.

        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 nor do checkers verify that their dependencies are not circular. Make sure no circular dependencies are created when overriding this method. (In other words, if checker A depends on checker B, checker B cannot depend on checker A.)

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

        The BaseTypeChecker will not modify the set returned by this method, but clients that override the method do modify the set.

        Returns:
        the subchecker classes on which this checker depends; will be modified by callees in overriding methods
      • shouldResolveReflection

        public boolean shouldResolveReflection()
        Returns whether or not reflection should be resolved.
        Returns:
        true if reflection should be resolved
      • createSourceVisitor

        protected BaseTypeVisitor<?> createSourceVisitor()
        Returns the appropriate visitor that type-checks the compilation unit according to the type system rules.

        This implementation uses the checker naming convention to create the appropriate visitor. If no visitor is found, it returns an instance of BaseTypeVisitor. It reflectively invokes the constructor that accepts this checker and the compilation unit tree (in that order) as arguments.

        Subclasses have to override this method to create the appropriate visitor if they do not follow the checker naming convention.

        Specified by:
        createSourceVisitor in class SourceChecker
        Returns:
        the type-checking visitor
      • createSourceVisitorPublic

        public BaseTypeVisitor<?> createSourceVisitorPublic()
        A public variant of createSourceVisitor(). Only use this if you know what you are doing.
        Returns:
        the type-checking visitor
      • getRelatedClassName

        public static @ClassGetName java.lang.String getRelatedClassName​(java.lang.Class<?> checkerClass,
                                                                         java.lang.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 to replace "Checker" or "Subchecker" by
        Returns:
        the name of the related class
      • getSupportedLintOptions

        public java.util.Set<java.lang.String> getSupportedLintOptions()
        Specify supported lint options for all type-checkers.
        Overrides:
        getSupportedLintOptions in class SourceChecker
        Returns:
        an unmodifiable Set of the lint options recognized by this checker
      • invokeConstructorFor

        public static <T> @Nullable T invokeConstructorFor​(@ClassGetName java.lang.String name,
                                                           java.lang.Class<?>[] paramTypes,
                                                           java.lang.Object[] args)
        Invokes the constructor belonging to the class named by name having the given parameter types on the given arguments. Returns null if the class cannot be found. Otherwise, throws an exception if there is trouble with the constructor invocation.
        Type Parameters:
        T - the type to which the constructor belongs
        Parameters:
        name - the name of the class to which the constructor belongs
        paramTypes - the types of the constructor's parameters
        args - the arguments on which to invoke the constructor
        Returns:
        the result of the constructor invocation on args, or null if the class does not exist
      • getTypeFactory

        public GenericAnnotatedTypeFactory<?,​?,​?,​?> getTypeFactory()
        Return the type factory associated with this checker.
        Returns:
        the type factory associated with this checker
      • getSubchecker

        public <T extends BaseTypeChecker@Nullable T getSubchecker​(java.lang.Class<T> checkerClass)
        Returns the requested 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 subchecker or null if not found
      • getTypeFactoryOfSubcheckerOrNull

        public <T extends GenericAnnotatedTypeFactory<?,​?,​?,​?>> @Nullable T getTypeFactoryOfSubcheckerOrNull​(java.lang.Class<? extends BaseTypeChecker> subCheckerClass)
        Returns the type factory used by a subchecker. Returns null if no matching subchecker was found or if the type factory is null. The caller must know the exact checker class to request.

        Because the visitor state is copied, call this method each time a subfactory is needed rather than store the returned subfactory in a field.

        Type Parameters:
        T - the type of subCheckerClass's AnnotatedTypeFactory
        Parameters:
        subCheckerClass - the class of the subchecker
        Returns:
        the type factory of the requested subchecker or null if not found
      • getSubcheckers

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

        public void typeProcess​(javax.lang.model.element.TypeElement element,
                                com.sun.source.util.TreePath tree)
        Description copied from class: SourceChecker
        Type-check the code using this checker's visitor.
        Overrides:
        typeProcess in class SourceChecker
        Parameters:
        element - element of the analyzed class
        tree - the tree path to the element, with the leaf being a ClassTree
        See Also:
        Processor.process(Set, RoundEnvironment)
      • getSuppressWarningsPrefixesOfSubcheckers

        public java.util.Collection<java.lang.String> getSuppressWarningsPrefixesOfSubcheckers()
        Like SourceChecker.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
      • getUltimateParentChecker

        public BaseTypeChecker getUltimateParentChecker()
        Finds the ultimate parent checker of this checker. The ultimate parent checker is the checker that the user actually requested, i.e. the one with no parent. The ultimate parent might be this checker itself.
        Returns:
        the first checker in the parent checker chain with no parent checker of its own, i.e., the ultimate parent checker
      • warnUnneededSuppressions

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

        This implementation collects needed warning suppressions for all subcheckers.

        Overrides:
        warnUnneededSuppressions in class SourceChecker
      • printOrStoreMessage

        protected void printOrStoreMessage​(javax.tools.Diagnostic.Kind kind,
                                           java.lang.String message,
                                           com.sun.source.tree.Tree source,
                                           com.sun.source.tree.CompilationUnitTree root)
        If this is a compound checker or a subchecker of a compound checker, then the message is stored until all messages from all checkers for the compilation unit are issued.

        Otherwise, it prints the message.

        Overrides:
        printOrStoreMessage in class SourceChecker
        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
      • getOptionsNoSubcheckers

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

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

        public java.util.List<java.lang.String> getExtraStubFiles()
        Return a list of additional 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
      • processErrorMessageArg

        protected java.lang.Object processErrorMessageArg​(java.lang.Object arg)
        Description copied from class: SourceChecker
        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, SourceChecker.fullMessageOf(java.lang.String, java.lang.String) processes the message key itself but not the arguments, and tries suffixes.

        Overrides:
        processErrorMessageArg in class SourceChecker
        Parameters:
        arg - the argument
        Returns:
        the result after processing