io.github.lukehutch.fastclasspathscanner

Class FastClasspathScanner

java.lang.Object

io.github.lukehutch.fastclasspathscanner.FastClasspathScanner

public class FastClasspathScanner
extends Object

Uber-fast, ultra-lightweight Java classpath scanner. Scans the classpath by parsing the classfile binary format directly rather than by using reflection. (Reflection causes the classloader to load each class, which can take an order of magnitude more time than parsing the classfile directly.) See the accompanying README.md file for documentation.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	FastClasspathScanner.ClassMatcher An interface used for testing if a class matches specified criteria.

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	verbose If set to true, print info while scanning

Constructor Summary

Constructors

Constructor and Description
FastClasspathScanner(String... scanSpec) Constructs a FastClasspathScanner instance.

Method Summary

Modifier and Type	Method and Description
long	classpathContentsLastModifiedTime() Returns the maximum "last modified" timestamp in the classpath (in epoch millis), or zero if scan() has not yet been called (or if nothing was found on the classpath).
boolean	classpathContentsModifiedSinceScan() Returns true if the classpath contents have been changed since scan() was last called.
String	generateClassGraphDotFile(float sizeX, float sizeY) Generates a .dot file which can be fed into GraphViz for layout and visualization of the class graph.
List<String>	getNamesOfAllAnnotationClasses() Returns the sorted names of all annotation classes found in a whitelisted (and non-blacklisted) package during the scan.
List<String>	getNamesOfAllClasses() Returns the sorted names of all standard classes, interface classes and annotation classes found in a whitelisted (and non-blacklisted) package during the scan.
List<String>	getNamesOfAllInterfaceClasses() Returns the sorted names of all interface classes (interfaces) found in a whitelisted (and non-blacklisted) package during the scan.
List<String>	getNamesOfAllStandardClasses() Returns the sorted names of all standard classes found in a whitelisted (and non-blacklisted) package during the scan.
List<String>	getNamesOfAnnotationsOnClass(Class<?> classOrInterface) Return the names of all annotations and meta-annotations on the specified class or interface.
List<String>	getNamesOfAnnotationsOnClass(String classOrInterfaceName) Return the names of all annotations and meta-annotations on the specified class or interface.
List<String>	getNamesOfAnnotationsWithMetaAnnotation(Class<?> metaAnnotation) Return the names of all annotations that are annotated with the specified meta-annotation.
List<String>	getNamesOfAnnotationsWithMetaAnnotation(String metaAnnotationName) Return the names of all annotations that are annotated with the specified meta-annotation.
List<String>	getNamesOfClassesImplementing(Class<?> implementedInterface) Returns the names of classes on the classpath that implement the specified interface or a subinterface, or whose superclasses implement the specified interface or a sub-interface.
List<String>	getNamesOfClassesImplementing(String implementedInterfaceName) Returns the names of classes on the classpath that implement the specified interface or a subinterface, or whose superclasses implement the specified interface or a sub-interface.
List<String>	getNamesOfClassesImplementingAllOf(Class<?>... implementedInterfaces) Returns the names of classes on the classpath that implement (or have superclasses that implement) all of the specified interfaces or their subinterfaces.
List<String>	getNamesOfClassesImplementingAllOf(String... implementedInterfaceNames) Returns the names of classes on the classpath that implement (or have superclasses that implement) all of the specified interfaces or their subinterfaces.
List<String>	getNamesOfClassesWithAnnotation(Class<?> annotation) Returns the names of classes on the classpath that have the specified annotation.
List<String>	getNamesOfClassesWithAnnotation(String annotationName) Returns the names of classes on the classpath that have the specified annotation.
List<String>	getNamesOfClassesWithAnnotationsAllOf(Class<?>... annotations) Returns the names of classes on the classpath that have all of the specified annotations.
List<String>	getNamesOfClassesWithAnnotationsAllOf(String... annotationNames) Returns the names of classes on the classpath that have all of the specified annotations.
List<String>	getNamesOfClassesWithAnnotationsAnyOf(Class<?>... annotations) Returns the names of classes on the classpath that have any of the specified annotations.
List<String>	getNamesOfClassesWithAnnotationsAnyOf(String... annotationNames) Returns the names of classes on the classpath that have any of the specified annotations.
List<String>	getNamesOfClassesWithFieldOfType(Class<?> fieldType) Returns the names of classes that have a field of the given type.
List<String>	getNamesOfClassesWithFieldOfType(String fieldTypeName) Returns the names of classes that have a field of the given type.
List<String>	getNamesOfMetaAnnotationsOnAnnotation(Class<?> annotation) Return the names of all meta-annotations on the specified annotation.
List<String>	getNamesOfMetaAnnotationsOnAnnotation(String annotationName) Return the names of all meta-annotations on the specified annotation.
List<String>	getNamesOfSubclassesOf(Class<?> superclass) Returns the names of classes on the classpath that extend the specified superclass.
List<String>	getNamesOfSubclassesOf(String superclassName) Returns the names of classes on the classpath that extend the specified superclass.
List<String>	getNamesOfSubinterfacesOf(Class<?> superInterface) Returns the names of interfaces on the classpath that extend a given superinterface.
List<String>	getNamesOfSubinterfacesOf(String superInterfaceName) Returns the names of interfaces on the classpath that extend a given superinterface.
List<String>	getNamesOfSuperclassesOf(Class<?> subclass) Returns the names of classes on the classpath that are superclasses of the specified subclass.
List<String>	getNamesOfSuperclassesOf(String subclassName) Returns the names of classes on the classpath that are superclasses of the specified subclass.
List<String>	getNamesOfSuperinterfacesOf(Class<?> subInterface) Returns the names of interfaces on the classpath that are superinterfaces of a given subinterface.
List<String>	getNamesOfSuperinterfacesOf(String subinterfaceName) Returns the names of interfaces on the classpath that are superinterfaces of a given subinterface.
ClassGraphBuilder	getScanResults() Returns the ClassGraphBuilder created by calling .scan(), or throws RuntimeException if .scan() has not yet been called.
List<File>	getUniqueClasspathElements() Returns the list of all unique File objects representing directories or zip/jarfiles on the classpath, in classloader resolution order.
FastClasspathScanner	matchAllAnnotationClasses(ClassMatchProcessor classEnumerationMatchProcessor) Calls the provided ClassEnumerationMatchProcessor for all annotation classes (annotation definitions) found in whitelisted packages on the classpath.
FastClasspathScanner	matchAllClasses(ClassMatchProcessor classEnumerationMatchProcessor) Calls the provided ClassEnumerationMatchProcessor for all standard classes, interfaces and annotations found in whitelisted packages on the classpath.
FastClasspathScanner	matchAllInterfaceClasses(ClassMatchProcessor classEnumerationMatchProcessor) Calls the provided ClassEnumerationMatchProcessor for all interface classes (interface definitions) found in whitelisted packages on the classpath.
FastClasspathScanner	matchAllStandardClasses(ClassMatchProcessor classEnumerationMatchProcessor) Calls the provided ClassEnumerationMatchProcessor for all standard classes (i.e.
<T> FastClasspathScanner	matchClassesImplementing(Class<T> implementedInterface, InterfaceMatchProcessor<T> interfaceMatchProcessor) Calls the provided InterfaceMatchProcessor for classes on the classpath that implement the specified interface or a subinterface, or whose superclasses implement the specified interface or a sub-interface.
FastClasspathScanner	matchClassesWithAnnotation(Class<?> annotation, ClassAnnotationMatchProcessor classAnnotationMatchProcessor) Calls the provided ClassMatchProcessor if classes are found on the classpath that have the specified annotation.
<T> FastClasspathScanner	matchClassesWithFieldOfType(Class<T> fieldType, ClassMatchProcessor classMatchProcessor) Calls the provided ClassMatchProcessor for classes on the classpath that have a field of the given type.
FastClasspathScanner	matchFilenameExtension(String extensionToMatch, FileMatchContentsProcessor fileMatchContentsProcessor) Calls the given FileMatchProcessor if files are found on the classpath that have the given file extension.
FastClasspathScanner	matchFilenameExtension(String extensionToMatch, FileMatchContentsProcessorWithContext fileMatchContentsProcessorWithContext) Calls the given FileMatchProcessorWithContext if files are found on the classpath that have the given file extension.
FastClasspathScanner	matchFilenameExtension(String extensionToMatch, FileMatchProcessor fileMatchProcessor) Calls the given FileMatchProcessor if files are found on the classpath that have the given file extension.
FastClasspathScanner	matchFilenameExtension(String extensionToMatch, FileMatchProcessorWithContext fileMatchProcessorWithContext) Calls the given FileMatchProcessorWithContext if files are found on the classpath that have the given file extension.
FastClasspathScanner	matchFilenamePath(String relativePathToMatch, FileMatchContentsProcessor fileMatchContentsProcessor) Calls the given FileMatchContentsProcessor if files are found on the classpath that exactly match the given relative path.
FastClasspathScanner	matchFilenamePath(String relativePathToMatch, FileMatchContentsProcessorWithContext fileMatchContentsProcessorWithContext) Calls the given FileMatchContentsProcessorWithContext if files are found on the classpath that exactly match the given relative path.
FastClasspathScanner	matchFilenamePath(String relativePathToMatch, FileMatchProcessor fileMatchProcessor) Calls the given FileMatchProcessor if files are found on the classpath that exactly match the given relative path.
FastClasspathScanner	matchFilenamePath(String relativePathToMatch, FileMatchProcessorWithContext fileMatchProcessorWithContext) Calls the given FileMatchProcessorWithContext if files are found on the classpath that exactly match the given relative path.
FastClasspathScanner	matchFilenamePathLeaf(String pathLeafToMatch, FileMatchContentsProcessor fileMatchContentsProcessor) Calls the given FileMatchContentsProcessor if files are found on the classpath that exactly match the given path leafname.
FastClasspathScanner	matchFilenamePathLeaf(String pathLeafToMatch, FileMatchContentsProcessorWithContext fileMatchContentsProcessorWithContext) Calls the given FileMatchContentsProcessorWithContext if files are found on the classpath that exactly match the given path leafname.
FastClasspathScanner	matchFilenamePathLeaf(String pathLeafToMatch, FileMatchProcessor fileMatchProcessor) Calls the given FileMatchProcessor if files are found on the classpath that exactly match the given path leafname.
FastClasspathScanner	matchFilenamePathLeaf(String pathLeafToMatch, FileMatchProcessorWithContext fileMatchProcessorWithContext) Calls the given FileMatchProcessorWithContext if files are found on the classpath that exactly match the given path leafname.
FastClasspathScanner	matchFilenamePattern(String pathRegexp, FileMatchContentsProcessor fileMatchContentsProcessor) Calls the given FileMatchContentsProcessor if files are found on the classpath with the given regexp pattern in their path.
FastClasspathScanner	matchFilenamePattern(String pathRegexp, FileMatchContentsProcessorWithContext fileMatchContentsProcessorWithContext) Calls the given FileMatchContentsProcessorWithContext if files are found on the classpath with the given regexp pattern in their path.
FastClasspathScanner	matchFilenamePattern(String pathRegexp, FileMatchProcessor fileMatchProcessor) Calls the given FileMatchProcessor if files are found on the classpath with the given regexp pattern in their path.
FastClasspathScanner	matchFilenamePattern(String pathRegexp, FileMatchProcessorWithContext fileMatchProcessorWithContext) Calls the given FileMatchProcessorWithContext if files are found on the classpath with the given regexp pattern in their path.
FastClasspathScanner	matchStaticFinalFieldNames(HashSet<String> fullyQualifiedStaticFinalFieldNames, StaticFinalFieldMatchProcessor staticFinalFieldMatchProcessor) Calls the given StaticFinalFieldMatchProcessor if classes are found on the classpath that contain static final fields that match one of a set of fully-qualified field names, e.g.
FastClasspathScanner	matchStaticFinalFieldNames(String[] fullyQualifiedStaticFinalFieldNames, StaticFinalFieldMatchProcessor staticFinalFieldMatchProcessor) Calls the given StaticFinalFieldMatchProcessor if classes are found on the classpath that contain static final fields that match one of a list of fully-qualified field names, e.g.
FastClasspathScanner	matchStaticFinalFieldNames(String fullyQualifiedStaticFinalFieldName, StaticFinalFieldMatchProcessor staticFinalFieldMatchProcessor) Calls the given StaticFinalFieldMatchProcessor if classes are found on the classpath that contain static final fields that match a fully-qualified field name, e.g.
<T> FastClasspathScanner	matchSubclassesOf(Class<T> superclass, SubclassMatchProcessor<T> subclassMatchProcessor) Calls the provided SubclassMatchProcessor if classes are found on the classpath that extend the specified superclass.
<T> FastClasspathScanner	matchSubinterfacesOf(Class<T> superinterface, SubinterfaceMatchProcessor<T> subinterfaceMatchProcessor) Calls the provided SubinterfaceMatchProcessor if an interface that extends a given superinterface is found on the classpath.
FastClasspathScanner	overrideClasspath(String classpath) Override the automatically-detected classpath with a custom search path.
FastClasspathScanner	scan() Scans the classpath for matching files, and calls any match processors if a match is identified.
FastClasspathScanner	verbose() Switch on verbose mode (prints debug info to System.out).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

verbose

public static boolean verbose

If set to true, print info while scanning

Constructor Detail

FastClasspathScanner

public FastClasspathScanner(String... scanSpec)

Constructs a FastClasspathScanner instance. You can pass a scanning specification to the constructor to describe what should be scanned. This prevents irrelevant classpath entries from being unecessarily scanned, which can be time-consuming. (Note that calling the constructor does not start the scan, you must separately call .scan() to perform the actual scan.)

Parameters:

scanSpec - The constructor accepts a list of whitelisted package prefixes / jar names to scan, as well as blacklisted packages/jars not to scan, where blacklisted entries are prefixed with the '-' character. For example: new FastClasspathScanner("com.x"): limits scanning to the package com.x and its sub-packages in all jarfiles and all directory entries on the classpath. new FastClasspathScanner("com.x", "-com.x.y"): limits scanning to com.x and all sub-packages *except* com.x.y in all jars and directories on the classpath. new FastClasspathScanner("com.x", "-com.x.y", "jar:deploy.jar"): limits scanning to com.x and all its sub-packages except com.x.y, but only looks in jars named deploy.jar on the classpath. Note: 1. Whitelisting one or more jar entries prevents non-jar entries (directories) on the classpath from being scanned. 2. Only the leafname of a jarfile can be specified in a "jar:" or "-jar:" entry, so if there is a chance of conflict, make sure the jarfile's leaf name is unique. new FastClasspathScanner("com.x", "-jar:irrelevant.jar"): limits scanning to com.x and all sub-packages in all directories on the classpath, and in all jars except irrelevant.jar. (i.e. blacklisting a jarfile only excludes the specified jarfile, it doesn't prevent all directories from being scanned, as with whitelisting a jarfile.) new FastClasspathScanner("com.x", "jar:"): limits scanning to com.x and all sub-packages, but only looks in jarfiles on the classpath -- directories are not scanned. (i.e. "jar:" is a wildcard to indicate that all jars are whitelisted, and as in the example above, whitelisting jarfiles prevents non-jars (directories) from being scanned.) new FastClasspathScanner("com.x", "-jar:"): limits scanning to com.x and all sub-packages, but only looks in directories on the classpath -- jarfiles are not scanned. (i.e. "-jar:" is a wildcard to indicate that all jars are blacklisted.) new FastClasspathScanner(): If you don't specify any whitelisted package prefixes, all jarfiles and all directories on the classpath will be scanned. N.B. System, bootstrap and extension jarfiles (i.e. the JRE jarfiles) are never scanned.

Method Detail

overrideClasspath

public FastClasspathScanner overrideClasspath(String classpath)

Override the automatically-detected classpath with a custom search path.

getNamesOfAllClasses

public List<String> getNamesOfAllClasses()

Returns the sorted names of all standard classes, interface classes and annotation classes found in a whitelisted (and non-blacklisted) package during the scan.

getNamesOfAllStandardClasses

public List<String> getNamesOfAllStandardClasses()

Returns the sorted names of all standard classes found in a whitelisted (and non-blacklisted) package during the scan.

getNamesOfAllInterfaceClasses

public List<String> getNamesOfAllInterfaceClasses()

Returns the sorted names of all interface classes (interfaces) found in a whitelisted (and non-blacklisted) package during the scan.

getNamesOfAllAnnotationClasses

public List<String> getNamesOfAllAnnotationClasses()

Returns the sorted names of all annotation classes found in a whitelisted (and non-blacklisted) package during the scan.

matchAllClasses

public FastClasspathScanner matchAllClasses(ClassMatchProcessor classEnumerationMatchProcessor)

Calls the provided ClassEnumerationMatchProcessor for all standard classes, interfaces and annotations found in whitelisted packages on the classpath. Calls the class loader on each matching class (using Class.forName()) before calling the ClassEnumerationMatchProcessor.

Parameters:

classEnumerationMatchProcessor - the ClassEnumerationMatchProcessor to call when a match is found.

matchAllStandardClasses

public FastClasspathScanner matchAllStandardClasses(ClassMatchProcessor classEnumerationMatchProcessor)

Calls the provided ClassEnumerationMatchProcessor for all standard classes (i.e. non-interface, non-annotation classes) found in whitelisted packages on the classpath. Calls the class loader on each matching class (using Class.forName()) before calling the ClassEnumerationMatchProcessor.

Parameters:

classEnumerationMatchProcessor - the ClassEnumerationMatchProcessor to call when a match is found.

matchAllInterfaceClasses

public FastClasspathScanner matchAllInterfaceClasses(ClassMatchProcessor classEnumerationMatchProcessor)

Calls the provided ClassEnumerationMatchProcessor for all interface classes (interface definitions) found in whitelisted packages on the classpath. Calls the class loader on each matching interface class (using Class.forName()) before calling the ClassEnumerationMatchProcessor.

Parameters:

classEnumerationMatchProcessor - the ClassEnumerationMatchProcessor to call when a match is found.

matchAllAnnotationClasses

public FastClasspathScanner matchAllAnnotationClasses(ClassMatchProcessor classEnumerationMatchProcessor)

Calls the provided ClassEnumerationMatchProcessor for all annotation classes (annotation definitions) found in whitelisted packages on the classpath. Calls the class loader on each matching annotation class (using Class.forName()) before calling the ClassEnumerationMatchProcessor.

Parameters:

classEnumerationMatchProcessor - the ClassEnumerationMatchProcessor to call when a match is found.

matchSubclassesOf

public <T> FastClasspathScanner matchSubclassesOf(Class<T> superclass,
                                                  SubclassMatchProcessor<T> subclassMatchProcessor)

Calls the provided SubclassMatchProcessor if classes are found on the classpath that extend the specified superclass. Calls the class loader on each matching class (using Class.forName()) before calling the SubclassMatchProcessor. Does not call the classloader on non-matching classes or interfaces.

Parameters:

superclass - The superclass to match (i.e. the class that subclasses need to extend to match).

subclassMatchProcessor - the SubclassMatchProcessor to call when a match is found.

getNamesOfSubclassesOf

public List<String> getNamesOfSubclassesOf(Class<?> superclass)

Returns the names of classes on the classpath that extend the specified superclass. Should be called after scan(), and returns matching classes whether or not a SubclassMatchProcessor was added to the scanner before the call to scan(). Does not call the classloader on the matching classes, just returns their names.

Parameters:

superclass - The superclass to match (i.e. the class that subclasses need to extend to match).

Returns:

A list of the names of matching classes, or the empty list if none.

getNamesOfSubclassesOf

public List<String> getNamesOfSubclassesOf(String superclassName)

Returns the names of classes on the classpath that extend the specified superclass. Should be called after scan(), and returns matching classes whether or not a SubclassMatchProcessor was added to the scanner before the call to scan(). Does not call the classloader on the matching classes, just returns their names.

Parameters:

superclassName - The name of the superclass to match (i.e. the name of the class that subclasses need to extend).

Returns:

A list of the names of matching classes, or the empty list if none.

getNamesOfSuperclassesOf

public List<String> getNamesOfSuperclassesOf(Class<?> subclass)

Returns the names of classes on the classpath that are superclasses of the specified subclass. Should be called after scan(), and returns matching classes whether or not a SubclassMatchProcessor was added to the scanner before the call to scan(). Does not call the classloader on the matching classes, just returns their names.

Parameters:

subclass - The subclass to match (i.e. the class that needs to extend a superclass for the superclass to match).

Returns:

A list of the names of matching classes, or the empty list if none.

getNamesOfSuperclassesOf

public List<String> getNamesOfSuperclassesOf(String subclassName)

Returns the names of classes on the classpath that are superclasses of the specified subclass. Should be called after scan(), and returns matching classes whether or not a SubclassMatchProcessor was added to the scanner before the call to scan(). Does not call the classloader on the matching classes, just returns their names.

Parameters:

subclassName - The subclass to match (i.e. the class that needs to extend a superclass for the superclass to match).

Returns:

A list of the names of matching classes, or the empty list if none.

matchSubinterfacesOf

public <T> FastClasspathScanner matchSubinterfacesOf(Class<T> superinterface,
                                                     SubinterfaceMatchProcessor<T> subinterfaceMatchProcessor)

Calls the provided SubinterfaceMatchProcessor if an interface that extends a given superinterface is found on the classpath. Will call the class loader on each matching interface (using Class.forName()) before calling the SubinterfaceMatchProcessor. Does not call the classloader on non-matching classes or interfaces.

Parameters:

superinterface - The superinterface to match (i.e. the interface that subinterfaces need to extend to match).

subinterfaceMatchProcessor - the SubinterfaceMatchProcessor to call when a match is found.

getNamesOfSubinterfacesOf

public List<String> getNamesOfSubinterfacesOf(Class<?> superInterface)

Returns the names of interfaces on the classpath that extend a given superinterface. Should be called after scan(), and returns matching interfaces whether or not a SubinterfaceMatchProcessor was added to the scanner before the call to scan(). Does not call the classloader on the matching interfaces, just returns their names.

Parameters:

superInterface - The superinterface to match (i.e. the interface that subinterfaces need to extend to match).

Returns:

A list of the names of matching interfaces, or the empty list if none.

getNamesOfSubinterfacesOf

public List<String> getNamesOfSubinterfacesOf(String superInterfaceName)

Returns the names of interfaces on the classpath that extend a given superinterface. Should be called after scan(), and returns matching interfaces whether or not a SubinterfaceMatchProcessor was added to the scanner before the call to scan(). Does not call the classloader on the matching interfaces, just returns their names.

Parameters:

superInterfaceName - The name of the superinterface to match (i.e. the name of the interface that subinterfaces need to extend).

Returns:

A list of the names of matching interfaces, or the empty list if none.

getNamesOfSuperinterfacesOf

public List<String> getNamesOfSuperinterfacesOf(Class<?> subInterface)

Returns the names of interfaces on the classpath that are superinterfaces of a given subinterface. Should be called after scan(), and returns matching interfaces whether or not a SubinterfaceMatchProcessor was added to the scanner before the call to scan(). Does not call the classloader on the matching interfaces, just returns their names.

Parameters:

subInterface - The superinterface to match (i.e. the interface that subinterfaces need to extend to match).

Returns:

A list of the names of matching interfaces, or the empty list if none.

getNamesOfSuperinterfacesOf

public List<String> getNamesOfSuperinterfacesOf(String subinterfaceName)

Returns the names of interfaces on the classpath that are superinterfaces of a given subinterface. Should be called after scan(), and returns matching interfaces whether or not a SubinterfaceMatchProcessor was added to the scanner before the call to scan(). Does not call the classloader on the matching interfaces, just returns their

Parameters:

subinterfaceName - The name of the superinterface to match (i.e. the name of the interface that subinterfaces need to extend).

Returns:

A list of the names of matching interfaces, or the empty list if none.

matchClassesImplementing

public <T> FastClasspathScanner matchClassesImplementing(Class<T> implementedInterface,
                                                         InterfaceMatchProcessor<T> interfaceMatchProcessor)

Calls the provided InterfaceMatchProcessor for classes on the classpath that implement the specified interface or a subinterface, or whose superclasses implement the specified interface or a sub-interface. Will call the class loader on each matching interface (using Class.forName()) before calling the InterfaceMatchProcessor. Does not call the classloader on non-matching classes or interfaces.

Parameters:

implementedInterface - The interface that classes need to implement.

interfaceMatchProcessor - the ClassMatchProcessor to call when a match is found.

getNamesOfClassesImplementing

public List<String> getNamesOfClassesImplementing(Class<?> implementedInterface)

Returns the names of classes on the classpath that implement the specified interface or a subinterface, or whose superclasses implement the specified interface or a sub-interface. Should be called after scan(), and returns matching interfaces whether or not an InterfaceMatchProcessor was added to the scanner before the call to scan(). Does not call the classloader on the matching classes, just returns their names.

Parameters:

implementedInterface - The interface that classes need to implement to match.

Returns:

A list of the names of matching classes, or the empty list if none.

getNamesOfClassesImplementing

public List<String> getNamesOfClassesImplementing(String implementedInterfaceName)

Returns the names of classes on the classpath that implement the specified interface or a subinterface, or whose superclasses implement the specified interface or a sub-interface. Should be called after scan(), and returns matching interfaces whether or not an InterfaceMatchProcessor was added to the scanner before the call to scan(). Does not call the classloader on the matching classes, just returns their names.

Parameters:

implementedInterfaceName - The name of the interface that classes need to implement.

Returns:

A list of the names of matching classes, or the empty list if none.

getNamesOfClassesImplementingAllOf

public List<String> getNamesOfClassesImplementingAllOf(Class<?>... implementedInterfaces)

Returns the names of classes on the classpath that implement (or have superclasses that implement) all of the specified interfaces or their subinterfaces. Should be called after scan(), and returns matching interfaces whether or not an InterfaceMatchProcessor was added to the scanner before the call to scan(). Does not call the classloader on the matching classes, just returns their names.

Parameters:

implementedInterfaceNames - The name of the interfaces that classes need to implement.

Returns:

A list of the names of matching classes, or the empty list if none.

getNamesOfClassesImplementingAllOf

public List<String> getNamesOfClassesImplementingAllOf(String... implementedInterfaceNames)

Returns the names of classes on the classpath that implement (or have superclasses that implement) all of the specified interfaces or their subinterfaces. Should be called after scan(), and returns matching interfaces whether or not an InterfaceMatchProcessor was added to the scanner before the call to scan(). Does not call the classloader on the matching classes, just returns their names.

Parameters:

implementedInterfaceNames - The name of the interfaces that classes need to implement.

Returns:

A list of the names of matching classes, or the empty list if none.

matchClassesWithFieldOfType

public <T> FastClasspathScanner matchClassesWithFieldOfType(Class<T> fieldType,
                                                            ClassMatchProcessor classMatchProcessor)

Calls the provided ClassMatchProcessor for classes on the classpath that have a field of the given type. Matches classes that have fields of the given type, array fields with an element type of the given type, and fields of parameterized type that have a type parameter of the given type. (Does not call the classloader on non-matching classes.) The field type must be declared in a package that is whitelisted (and not blacklisted).

Parameters:

implementedInterface - The interface that classes need to implement.

classMatchProcessor - the ClassMatchProcessor to call when a match is found.

getNamesOfClassesWithFieldOfType

public List<String> getNamesOfClassesWithFieldOfType(String fieldTypeName)

Returns the names of classes that have a field of the given type. Returns classes that have fields of the named type itself, array fields with an element type that matches the named type, and fields of parameterized type that have a type parameter of the named type. The field type must be declared in a package that is whitelisted (and not blacklisted).

getNamesOfClassesWithFieldOfType

public List<String> getNamesOfClassesWithFieldOfType(Class<?> fieldType)

Returns the names of classes that have a field of the given type. Returns classes that have fields with the same type as the requested type, array fields with an element type that matches the requested type, and fields of parameterized type that have a type parameter of the requested type. The field type must be declared in a package that is whitelisted (and not blacklisted).

matchClassesWithAnnotation

public FastClasspathScanner matchClassesWithAnnotation(Class<?> annotation,
                                                       ClassAnnotationMatchProcessor classAnnotationMatchProcessor)

Calls the provided ClassMatchProcessor if classes are found on the classpath that have the specified annotation.

Parameters:

annotation - The class annotation to match.

classAnnotationMatchProcessor - the ClassAnnotationMatchProcessor to call when a match is found.

getNamesOfClassesWithAnnotation

public List<String> getNamesOfClassesWithAnnotation(Class<?> annotation)

Returns the names of classes on the classpath that have the specified annotation. Should be called after scan(), and returns matching classes whether or not a ClassAnnotationMatchProcessor was added to the scanner before the call to scan(). Does not call the classloader on the matching classes, just returns their names.

Parameters:

annotation - The class annotation.

Returns:

A list of the names of classes with the class annotation, or the empty list if none.

getNamesOfClassesWithAnnotation

public List<String> getNamesOfClassesWithAnnotation(String annotationName)

Returns the names of classes on the classpath that have the specified annotation. Should be called after scan(), and returns matching classes whether or not a ClassAnnotationMatchProcessor was added to the scanner before the call to scan(). Does not call the classloader on the matching classes, just returns their names.

Parameters:

annotationName - The name of the class annotation.

Returns:

A list of the names of classes that have the named annotation, or the empty list if none.

getNamesOfClassesWithAnnotationsAllOf

public List<String> getNamesOfClassesWithAnnotationsAllOf(Class<?>... annotations)

Returns the names of classes on the classpath that have all of the specified annotations. Should be called after scan(), and returns matching classes whether or not a ClassAnnotationMatchProcessor was added to the scanner before the call to scan(). Does not call the classloader on the matching classes, just returns their names.

Parameters:

annotations - The annotations.

Returns:

A list of the names of classes that have all of the annotations, or the empty list if none.

getNamesOfClassesWithAnnotationsAllOf

public List<String> getNamesOfClassesWithAnnotationsAllOf(String... annotationNames)

Returns the names of classes on the classpath that have all of the specified annotations. Should be called after scan(), and returns matching classes whether or not a ClassAnnotationMatchProcessor was added to the scanner before the call to scan(). Does not call the classloader on the matching classes, just returns their names.

Parameters:

annotationNames - The annotation names.

Returns:

A list of the names of classes that have all of the annotations, or the empty list if none.

getNamesOfClassesWithAnnotationsAnyOf

public List<String> getNamesOfClassesWithAnnotationsAnyOf(Class<?>... annotations)

Returns the names of classes on the classpath that have any of the specified annotations. Should be called after scan(), and returns matching classes whether or not a ClassAnnotationMatchProcessor was added to the scanner before the call to scan(). Does not call the classloader on the matching classes, just returns their names.

Parameters:

annotations - The annotations.

Returns:

A list of the names of classes that have one or more of the annotations, or the empty list if none.

getNamesOfClassesWithAnnotationsAnyOf

public List<String> getNamesOfClassesWithAnnotationsAnyOf(String... annotationNames)

Returns the names of classes on the classpath that have any of the specified annotations. Should be called after scan(), and returns matching classes whether or not a ClassAnnotationMatchProcessor was added to the scanner before the call to scan(). Does not call the classloader on the matching classes, just returns their names.

Parameters:

annotationNames - The annotation names.

Returns:

A list of the names of classes that have one or more of the annotations, or the empty list if none.

getNamesOfAnnotationsWithMetaAnnotation

public List<String> getNamesOfAnnotationsWithMetaAnnotation(Class<?> metaAnnotation)

Return the names of all annotations that are annotated with the specified meta-annotation.

Parameters:

metaAnnotation - The specified meta-annotation.

Returns:

A list of the names of annotations that are annotated with the specified meta annotation, or the empty list if none.

getNamesOfAnnotationsWithMetaAnnotation

public List<String> getNamesOfAnnotationsWithMetaAnnotation(String metaAnnotationName)

Return the names of all annotations that are annotated with the specified meta-annotation.

Parameters:

metaAnnotationName - The name of the specified meta-annotation.

Returns:

A list of the names of annotations that are annotated with the specified meta annotation, or the empty list if none.

getNamesOfAnnotationsOnClass

public List<String> getNamesOfAnnotationsOnClass(Class<?> classOrInterface)

Return the names of all annotations and meta-annotations on the specified class or interface.

Parameters:

classOrInterface - The class or interface.

Returns:

A list of the names of annotations and meta-annotations on the class, or the empty list if none.

getNamesOfAnnotationsOnClass

public List<String> getNamesOfAnnotationsOnClass(String classOrInterfaceName)

Return the names of all annotations and meta-annotations on the specified class or interface.

Parameters:

classOrInterfaceName - The name of the class or interface.

Returns:

A list of the names of annotations and meta-annotations on the class, or the empty list if none.

getNamesOfMetaAnnotationsOnAnnotation

public List<String> getNamesOfMetaAnnotationsOnAnnotation(Class<?> annotation)

Return the names of all meta-annotations on the specified annotation.

Parameters:

annotation - The specified annotation.

Returns:

A list of the names of meta-annotations on the specified annotation, or the empty list if none.

getNamesOfMetaAnnotationsOnAnnotation

public List<String> getNamesOfMetaAnnotationsOnAnnotation(String annotationName)

Return the names of all meta-annotations on the specified annotation.

Parameters:

annotationName - The name of the specified annotation.

Returns:

A list of the names of meta-annotations on the specified annotation, or the empty list if none.

matchStaticFinalFieldNames

public FastClasspathScanner matchStaticFinalFieldNames(HashSet<String> fullyQualifiedStaticFinalFieldNames,
                                                       StaticFinalFieldMatchProcessor staticFinalFieldMatchProcessor)

Calls the given StaticFinalFieldMatchProcessor if classes are found on the classpath that contain static final fields that match one of a set of fully-qualified field names, e.g. "com.package.ClassName.STATIC_FIELD_NAME". Field values are obtained from the constant pool in classfiles, *not* from a loaded class using reflection. This allows you to detect changes to the classpath and then run another scan that picks up the new values of selected static constants without reloading the class. (Class reloading is fraught with issues, see: http://tutorials.jenkov.com/java-reflection/dynamic-class-loading-reloading.html ) Note: Only static final fields with constant-valued literals are matched, not fields with initializer values that are the result of an expression or reference, except for cases where the compiler is able to simplify an expression into a single constant at compiletime, such as in the case of string concatenation. Note that the visibility of the fields is not checked; the value of the field in the classfile is returned whether or not it should be visible to the caller.

Parameters:

fullyQualifiedStaticFinalFieldNames - The set of fully-qualified static field names to match.

staticFinalFieldMatchProcessor - the StaticFinalFieldMatchProcessor to call when a match is found.

matchStaticFinalFieldNames

public FastClasspathScanner matchStaticFinalFieldNames(String fullyQualifiedStaticFinalFieldName,
                                                       StaticFinalFieldMatchProcessor staticFinalFieldMatchProcessor)

Calls the given StaticFinalFieldMatchProcessor if classes are found on the classpath that contain static final fields that match a fully-qualified field name, e.g. "com.package.ClassName.STATIC_FIELD_NAME". Field values are obtained from the constant pool in classfiles, *not* from a loaded class using reflection. This allows you to detect changes to the classpath and then run another scan that picks up the new values of selected static constants without reloading the class. (Class reloading is fraught with issues, see: http://tutorials.jenkov.com/java-reflection/dynamic-class-loading-reloading.html ) Note: Only static final fields with constant-valued literals are matched, not fields with initializer values that are the result of an expression or reference, except for cases where the compiler is able to simplify an expression into a single constant at compiletime, such as in the case of string concatenation. Note that the visibility of the fields is not checked; the value of the field in the classfile is returned whether or not it should be visible to the caller.

Parameters:

fullyQualifiedStaticFinalFieldName - The fully-qualified static field name to match

staticFinalFieldMatchProcessor - the StaticFinalFieldMatchProcessor to call when a match is found.

matchStaticFinalFieldNames

public FastClasspathScanner matchStaticFinalFieldNames(String[] fullyQualifiedStaticFinalFieldNames,
                                                       StaticFinalFieldMatchProcessor staticFinalFieldMatchProcessor)

Calls the given StaticFinalFieldMatchProcessor if classes are found on the classpath that contain static final fields that match one of a list of fully-qualified field names, e.g. "com.package.ClassName.STATIC_FIELD_NAME". Field values are obtained from the constant pool in classfiles, *not* from a loaded class using reflection. This allows you to detect changes to the classpath and then run another scan that picks up the new values of selected static constants without reloading the class. (Class reloading is fraught with issues, see: http://tutorials.jenkov.com/java-reflection/dynamic-class-loading-reloading.html ) Note: Only static final fields with constant-valued literals are matched, not fields with initializer values that are the result of an expression or reference, except for cases where the compiler is able to simplify an expression into a single constant at compiletime, such as in the case of string concatenation. Note that the visibility of the fields is not checked; the value of the field in the classfile is returned whether or not it should be visible to the caller.

Parameters:

fullyQualifiedStaticFinalFieldNames - The list of fully-qualified static field names to match.

staticFinalFieldMatchProcessor - the StaticFinalFieldMatchProcessor to call when a match is found.

matchFilenamePattern

public FastClasspathScanner matchFilenamePattern(String pathRegexp,
                                                 FileMatchProcessorWithContext fileMatchProcessorWithContext)

Calls the given FileMatchProcessorWithContext if files are found on the classpath with the given regexp pattern in their path.

Parameters:

pathRegexp - The regexp to match, e.g. "app/templates/.\*\.html"

fileMatchProcessorWithContext - The FileMatchProcessorWithContext to call when each match is found.

matchFilenamePattern

public FastClasspathScanner matchFilenamePattern(String pathRegexp,
                                                 FileMatchProcessor fileMatchProcessor)

Calls the given FileMatchProcessor if files are found on the classpath with the given regexp pattern in their path.

Parameters:

pathRegexp - The regexp to match, e.g. "app/templates/.\*\.html"

fileMatchProcessor - The FileMatchProcessor to call when each match is found.

matchFilenamePattern

public FastClasspathScanner matchFilenamePattern(String pathRegexp,
                                                 FileMatchContentsProcessorWithContext fileMatchContentsProcessorWithContext)

Calls the given FileMatchContentsProcessorWithContext if files are found on the classpath with the given regexp pattern in their path.

Parameters:

pathRegexp - The regexp to match, e.g. "app/templates/.\*\.html"

fileMatchContentsProcessorWithContext - The FileMatchContentsProcessorWithContext to call when each match is found.

matchFilenamePattern

public FastClasspathScanner matchFilenamePattern(String pathRegexp,
                                                 FileMatchContentsProcessor fileMatchContentsProcessor)

Calls the given FileMatchContentsProcessor if files are found on the classpath with the given regexp pattern in their path.

Parameters:

pathRegexp - The regexp to match, e.g. "app/templates/.\*\.html"

fileMatchContentsProcessor - The FileMatchContentsProcessor to call when each match is found.

matchFilenamePath

public FastClasspathScanner matchFilenamePath(String relativePathToMatch,
                                              FileMatchProcessorWithContext fileMatchProcessorWithContext)

Calls the given FileMatchProcessorWithContext if files are found on the classpath that exactly match the given relative path.

Parameters:

relativePathToMatch - The complete path to match relative to the classpath entry, e.g. "app/templates/WidgetTemplate.html"

fileMatchProcessorWithContext - The FileMatchProcessorWithContext to call when each match is found.

matchFilenamePath

public FastClasspathScanner matchFilenamePath(String relativePathToMatch,
                                              FileMatchProcessor fileMatchProcessor)

Calls the given FileMatchProcessor if files are found on the classpath that exactly match the given relative path.

Parameters:

relativePathToMatch - The complete path to match relative to the classpath entry, e.g. "app/templates/WidgetTemplate.html"

fileMatchProcessor - The FileMatchProcessor to call when each match is found.

matchFilenamePath

public FastClasspathScanner matchFilenamePath(String relativePathToMatch,
                                              FileMatchContentsProcessorWithContext fileMatchContentsProcessorWithContext)

Calls the given FileMatchContentsProcessorWithContext if files are found on the classpath that exactly match the given relative path.

Parameters:

relativePathToMatch - The complete path to match relative to the classpath entry, e.g. "app/templates/WidgetTemplate.html"

fileMatchContentsProcessorWithContext - The FileMatchContentsProcessorWithContext to call when each match is found.

matchFilenamePath

public FastClasspathScanner matchFilenamePath(String relativePathToMatch,
                                              FileMatchContentsProcessor fileMatchContentsProcessor)

Calls the given FileMatchContentsProcessor if files are found on the classpath that exactly match the given relative path.

Parameters:

relativePathToMatch - The complete path to match relative to the classpath entry, e.g. "app/templates/WidgetTemplate.html"

fileMatchContentsProcessor - The FileMatchContentsProcessor to call when each match is found.

matchFilenamePathLeaf

public FastClasspathScanner matchFilenamePathLeaf(String pathLeafToMatch,
                                                  FileMatchProcessorWithContext fileMatchProcessorWithContext)

Calls the given FileMatchProcessorWithContext if files are found on the classpath that exactly match the given path leafname.

Parameters:

pathLeafToMatch - The complete path leaf to match, e.g. "WidgetTemplate.html"

fileMatchProcessorWithContext - The FileMatchProcessorWithContext to call when each match is found.

matchFilenamePathLeaf

public FastClasspathScanner matchFilenamePathLeaf(String pathLeafToMatch,
                                                  FileMatchProcessor fileMatchProcessor)

Calls the given FileMatchProcessor if files are found on the classpath that exactly match the given path leafname.

Parameters:

pathLeafToMatch - The complete path leaf to match, e.g. "WidgetTemplate.html"

fileMatchProcessor - The FileMatchProcessor to call when each match is found.

matchFilenamePathLeaf

public FastClasspathScanner matchFilenamePathLeaf(String pathLeafToMatch,
                                                  FileMatchContentsProcessorWithContext fileMatchContentsProcessorWithContext)

Calls the given FileMatchContentsProcessorWithContext if files are found on the classpath that exactly match the given path leafname.

Parameters:

pathLeafToMatch - The complete path leaf to match, e.g. "WidgetTemplate.html"

fileMatchContentsProcessorWithContext - The FileMatchContentsProcessorWithContext to call when each match is found.

matchFilenamePathLeaf

public FastClasspathScanner matchFilenamePathLeaf(String pathLeafToMatch,
                                                  FileMatchContentsProcessor fileMatchContentsProcessor)

Calls the given FileMatchContentsProcessor if files are found on the classpath that exactly match the given path leafname.

Parameters:

pathLeafToMatch - The complete path leaf to match, e.g. "WidgetTemplate.html"

fileMatchContentsProcessor - The FileMatchContentsProcessor to call when each match is found.

matchFilenameExtension

public FastClasspathScanner matchFilenameExtension(String extensionToMatch,
                                                   FileMatchProcessorWithContext fileMatchProcessorWithContext)

Calls the given FileMatchProcessorWithContext if files are found on the classpath that have the given file extension.

Parameters:

extensionToMatch - The extension to match, e.g. "html" matches "WidgetTemplate.html" and "WIDGET.HTML".

fileMatchProcessorWithContext - The FileMatchProcessorWithContext to call when each match is found.

matchFilenameExtension

public FastClasspathScanner matchFilenameExtension(String extensionToMatch,
                                                   FileMatchProcessor fileMatchProcessor)

Calls the given FileMatchProcessor if files are found on the classpath that have the given file extension.

Parameters:

extensionToMatch - The extension to match, e.g. "html" matches "WidgetTemplate.html" and "WIDGET.HTML".

fileMatchProcessor - The FileMatchProcessor to call when each match is found.

matchFilenameExtension

public FastClasspathScanner matchFilenameExtension(String extensionToMatch,
                                                   FileMatchContentsProcessorWithContext fileMatchContentsProcessorWithContext)

Calls the given FileMatchProcessorWithContext if files are found on the classpath that have the given file extension.

Parameters:

extensionToMatch - The extension to match, e.g. "html" matches "WidgetTemplate.html".

fileMatchContentsProcessorWithContext - The FileMatchContentsProcessorWithContext to call when each match is found.

matchFilenameExtension

public FastClasspathScanner matchFilenameExtension(String extensionToMatch,
                                                   FileMatchContentsProcessor fileMatchContentsProcessor)

Calls the given FileMatchProcessor if files are found on the classpath that have the given file extension.

Parameters:

extensionToMatch - The extension to match, e.g. "html" matches "WidgetTemplate.html".

fileMatchContentsProcessor - The FileMatchContentsProcessor to call when each match is found.

getUniqueClasspathElements

public List<File> getUniqueClasspathElements()

Returns the list of all unique File objects representing directories or zip/jarfiles on the classpath, in classloader resolution order. Classpath elements that do not exist are not included in the list.

generateClassGraphDotFile

public String generateClassGraphDotFile(float sizeX,
                                        float sizeY)

Generates a .dot file which can be fed into GraphViz for layout and visualization of the class graph. The sizeX and sizeY parameters are the image output size to use (in inches) when GraphViz is asked to render the .dot file.

getScanResults

public ClassGraphBuilder getScanResults()

Returns the ClassGraphBuilder created by calling .scan(), or throws RuntimeException if .scan() has not yet been called.

scan

public FastClasspathScanner scan()

Scans the classpath for matching files, and calls any match processors if a match is identified. This method should be called after all required match processors have been added. This method should be called before any "getNamesOf" methods (e.g. getNamesOfSubclassesOf()).

classpathContentsModifiedSinceScan

public boolean classpathContentsModifiedSinceScan()

Returns true if the classpath contents have been changed since scan() was last called. Only considers classpath prefixes whitelisted in the call to the constructor. Returns true if scan() has not yet been run. Much faster than standard classpath scanning, because only timestamps are checked, and jarfiles don't have to be opened.

classpathContentsLastModifiedTime

public long classpathContentsLastModifiedTime()

Returns the maximum "last modified" timestamp in the classpath (in epoch millis), or zero if scan() has not yet been called (or if nothing was found on the classpath). The returned timestamp should be less than the current system time if the timestamps of files on the classpath and the system time are accurate. Therefore, if anything changes on the classpath, this value should increase.

verbose

public FastClasspathScanner verbose()

Switch on verbose mode (prints debug info to System.out).