Class AnnotationClassLoader
- java.lang.Object
-
- org.checkerframework.framework.type.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 theAnnotatedTypeFactory
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 ofElementType.TYPE_USE
(and optionallyElementType.TYPE_PARAMETER
) are loaded. If it has otherElementType
values, it won't be loaded. Other annotation classes must be manually listed in a checker's annotated type factory by overridingAnnotatedTypeFactory.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)
. Seeorg.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 anAnnotationBuilder
, which is in turn used to build the annotation mirror from the loaded class.
-
Constructor Summary
Constructors Constructor Description AnnotationClassLoader(BaseTypeChecker checker)
Constructor for loading annotations defined for a checker.
-
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 theTarget
meta-annotation, and has the requiredElementType
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.
-
-
-
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 anAnnotationBuilder
, 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
- aBaseTypeChecker
or its subclass
-
-
Method Detail
-
close
public void close()
- Specified by:
close
in interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.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 withincreateSupportedTypeQualifiers()
(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 formatissueError
- 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 theTarget
meta-annotation, and has the requiredElementType
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 loadUnqualified
.- 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
-
-