Class AnnotationClassLoader

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable
    Direct Known Subclasses:
    SubtypingAnnotationClassLoader, UnitsAnnotationClassLoader

    public class AnnotationClassLoader
    extends java.lang.Object
    implements java.io.Closeable
    This class assists the AnnotatedTypeFactory by reflectively looking up the list of annotation class names in each checker's qual directory, and then loading and returning it as a set of annotation classes. It can also look up and load annotation classes from external directories that are passed as arguments to checkers that have extension capabilities such as the Subtyping Checker, Fenum Checker, and Units Checker.

    To load annotations using this class, their directory structure and package structure must be identical.

    Only annotation classes that have the Target meta-annotation with the value of ElementType.TYPE_USE (and optionally ElementType.TYPE_PARAMETER) are loaded. If it has other ElementType values, it won't be loaded. Other annotation classes must be manually listed in a checker's annotated type factory by overriding AnnotatedTypeFactory.createSupportedTypeQualifiers().

    Checker writers may wish to subclass this class if they wish to implement some custom rules to filter or process loaded annotation classes, by providing an override implementation of isSupportedAnnotationClass(Class). See org.checkerframework.checker.units.UnitsAnnotationClassLoader for an example.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected BaseTypeChecker checker
      For issuing errors to the user.
      protected java.net.URLClassLoader classLoader
      The class loader used to load annotation classes.
      protected javax.annotation.processing.ProcessingEnvironment processingEnv
      Processing Env used to create an AnnotationBuilder, which is in turn used to build the annotation mirror from the loaded class.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void close()  
      java.util.Set<java.lang.Class<? extends java.lang.annotation.Annotation>> getBundledAnnotationClasses()
      Gets the set of annotation classes in the qual directory of a checker shipped with the Checker Framework.
      protected boolean hasWellDefinedTargetMetaAnnotation​(java.lang.Class<? extends java.lang.annotation.Annotation> annoClass)
      Checks to see whether a particular annotation class has the Target meta-annotation, and has the required ElementType values.
      protected boolean isSupportedAnnotationClass​(java.lang.Class<? extends java.lang.annotation.Annotation> annoClass)
      Checks to see whether a particular annotation class is supported.
      protected @Nullable java.lang.Class<? extends java.lang.annotation.Annotation> loadAnnotationClass​(@BinaryName java.lang.String className, boolean issueError)
      Loads the class indicated by the name, and checks to see if it is an annotation that is supported by a checker.
      protected java.util.Set<java.lang.Class<? extends java.lang.annotation.Annotation>> loadAnnotationClasses​(@Nullable java.util.Set<@BinaryName java.lang.String> annoNames)
      Loads a set of annotations indicated by their names.
      @Nullable java.lang.Class<? extends java.lang.annotation.Annotation> loadExternalAnnotationClass​(@BinaryName java.lang.String annoName)
      This method takes as input the canonical name of an external annotation class and loads and returns that class via the class loader.
      java.util.Set<java.lang.Class<? extends java.lang.annotation.Annotation>> loadExternalAnnotationClassesFromDirectory​(java.lang.String dirName)
      This method takes as input a fully qualified path to a directory, and loads and returns the set of all supported annotation classes from that directory.
      protected void printPaths()
      Debug Use: Displays all classpaths examined by the class loader.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • checker

        protected final BaseTypeChecker checker
        For issuing errors to the user.
      • processingEnv

        protected final javax.annotation.processing.ProcessingEnvironment processingEnv
        Processing Env used to create an AnnotationBuilder, which is in turn used to build the annotation mirror from the loaded class.
      • classLoader

        protected final java.net.URLClassLoader classLoader
        The class loader used to load annotation classes.
    • Constructor Detail

      • AnnotationClassLoader

        public AnnotationClassLoader​(BaseTypeChecker checker)
        Constructor for loading annotations defined for a checker.
        Parameters:
        checker - a BaseTypeChecker or its subclass
    • Method Detail

      • close

        public void close()
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
      • printPaths

        protected final void printPaths()
        Debug Use: Displays all classpaths examined by the class loader.
      • getBundledAnnotationClasses

        public final java.util.Set<java.lang.Class<? extends java.lang.annotation.Annotation>> getBundledAnnotationClasses()
        Gets the set of annotation classes in the qual directory of a checker shipped with the Checker Framework. Note that the returned set from this method is mutable. This method is intended to be called within createSupportedTypeQualifiers() (or its helper methods) to help define the set of supported qualifiers.
        Returns:
        a mutable set of the loaded bundled annotation classes
        See Also:
        AnnotatedTypeFactory.createSupportedTypeQualifiers()
      • loadExternalAnnotationClass

        public final @Nullable java.lang.Class<? extends java.lang.annotation.Annotation> loadExternalAnnotationClass​(@BinaryName java.lang.String annoName)
        This method takes as input the canonical name of an external annotation class and loads and returns that class via the class loader. This method returns null if the external annotation class was loaded successfully but was deemed not supported by a checker. Errors are issued if the external class is not an annotation, or if it could not be loaded successfully.
        Parameters:
        annoName - canonical name of an external annotation class, e.g. "myproject.qual.myannotation"
        Returns:
        the loaded annotation class, or null if it was not a supported annotation as decided by isSupportedAnnotationClass(Class)
      • loadExternalAnnotationClassesFromDirectory

        public final java.util.Set<java.lang.Class<? extends java.lang.annotation.Annotation>> loadExternalAnnotationClassesFromDirectory​(java.lang.String dirName)
        This method takes as input a fully qualified path to a directory, and loads and returns the set of all supported annotation classes from that directory.
        Parameters:
        dirName - absolute path to a directory containing annotation classes
        Returns:
        a set of annotation classes
      • loadAnnotationClass

        protected final @Nullable java.lang.Class<? extends java.lang.annotation.Annotation> loadAnnotationClass​(@BinaryName java.lang.String className,
                                                                                                                 boolean issueError)
        Loads the class indicated by the name, and checks to see if it is an annotation that is supported by a checker.
        Parameters:
        className - the name of the class, in binary name format
        issueError - set to true to issue a warning when a loaded annotation is not a type annotation. It is useful to set this to true if a given annotation must be a well-defined type annotation (eg for annotation class names given as command line arguments). It should be set to false if the annotation is a meta-annotation or non-type annotation.
        Returns:
        the loaded annotation class if it has a @Target meta-annotation with the required ElementType values, and is a supported annotation by a checker. If the annotation is not supported by a checker, null is returned.
      • loadAnnotationClasses

        protected final java.util.Set<java.lang.Class<? extends java.lang.annotation.Annotation>> loadAnnotationClasses​(@Nullable java.util.Set<@BinaryName java.lang.String> annoNames)
        Loads a set of annotations indicated by their names.
        Parameters:
        annoNames - a set of binary names for annotation classes
        Returns:
        a set of loaded annotation classes
        See Also:
        loadAnnotationClass(String, boolean)
      • hasWellDefinedTargetMetaAnnotation

        protected boolean hasWellDefinedTargetMetaAnnotation​(java.lang.Class<? extends java.lang.annotation.Annotation> annoClass)
        Checks to see whether a particular annotation class has the Target meta-annotation, and has the required ElementType values.

        A subclass may override this method to load annotations that are not intended to be annotated in source code. E.g.: SubtypingChecker overrides this method to load Unqualified.

        Parameters:
        annoClass - an annotation class
        Returns:
        true if the annotation is well defined, false if it isn't
      • isSupportedAnnotationClass

        protected boolean isSupportedAnnotationClass​(java.lang.Class<? extends java.lang.annotation.Annotation> annoClass)
        Checks to see whether a particular annotation class is supported.

        By default, all loaded annotations that pass the basic checks in loadAnnotationClass(String, boolean) are supported.

        Individual checkers can create a subclass of AnnotationClassLoader and override this method to indicate whether a particular annotation is supported.

        Parameters:
        annoClass - an annotation class
        Returns:
        true if the annotation is supported, false if it isn't