Package org.checkerframework.framework.type

Class AnnotationClassLoader

java.lang.Object
org.checkerframework.framework.type.AnnotationClassLoader
All Implemented Interfaces:
Closeable, AutoCloseable
Direct Known Subclasses:
SubtypingAnnotationClassLoader, UnitsAnnotationClassLoader
public class AnnotationClassLoader extends Object implements 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 Details

    • checker

      protected final BaseTypeChecker checker
      For issuing errors to the user.

    • processingEnv

      protected final 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 URLClassLoader classLoader
      The class loader used to load annotation classes.

  • Constructor Details

    • AnnotationClassLoader

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

  • Method Details

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable

    • printPaths

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

    • getBundledAnnotationClasses

      public final Set<Class<? extends 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:

    • loadExternalAnnotationClass

      public final @Nullable Class<? extends Annotation> loadExternalAnnotationClass(@BinaryName 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 Set<Class<? extends Annotation>> loadExternalAnnotationClassesFromDirectory(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 Class<? extends Annotation> loadAnnotationClass(@BinaryName 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 Set<Class<? extends Annotation>> loadAnnotationClasses(@Nullable Set<@BinaryName 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:

    • hasWellDefinedTargetMetaAnnotation

      protected boolean hasWellDefinedTargetMetaAnnotation(Class<? extends 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(Class<? extends 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