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.

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... packagesToScan) Constructs a FastClasspathScanner instance.

Method Summary

Modifier and Type	Method and Description
void	addStaticFinalFieldProcessor(String className, String fieldName, StaticFinalFieldMatchProcessor staticFinalFieldMatchProcessor) Add a StaticFinalFieldMatchProcessor that should be called if a static final field with the given name is encountered in a class with the given fully-qualified classname while reading a classfile header.
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.
Set<String>	getNamesOfAllClasses() Returns the names of all classes and interfaces processed during the scan, i.e.
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>	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.
<T> Class<? extends T>	loadClass(String className) Call the classloader using Class.forName(className).
<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.
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, FileMatchProcessor fileMatchProcessor) Calls the given FileMatchProcessor 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, FileMatchProcessor fileMatchProcessor) Calls the given FileMatchProcessor 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, FileMatchProcessor fileMatchProcessor) Calls the given FileMatchProcessor 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, FileMatchProcessor fileMatchProcessor) Calls the given FileMatchProcessor 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	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... packagesToScan)

Constructs a FastClasspathScanner instance.

Parameters:

packagesToScan - the whitelist of package prefixes to scan, e.g. "com.xyz.widget", "com.xyz.gizmo". If no whitelisted packages are given (i.e. if the constructor is called with zero arguments), or a whitelisted package is "", then all packages on the classpath are whitelisted. If a package name is prefixed with "-", e.g. "-com.xyz.otherthing", then that package is blacklisted, rather than whitelisted. The final list of packages scanned is the set of whitelisted packages minus the set of blacklisted packages.

Method Detail

addStaticFinalFieldProcessor

public void addStaticFinalFieldProcessor(String className,
                                         String fieldName,
                                         StaticFinalFieldMatchProcessor staticFinalFieldMatchProcessor)

Add a StaticFinalFieldMatchProcessor that should be called if a static final field with the given name is encountered in a class with the given fully-qualified classname while reading a classfile header.

loadClass

public <T> Class<? extends T> loadClass(String className)

Call the classloader using Class.forName(className). Re-throws classloading exceptions as RuntimeException.

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. Will call 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.

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,
                                                 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,
                                                 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,
                                              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,
                                              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,
                                                  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,
                                                  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,
                                                   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".

fileMatchProcessor - The FileMatchProcessor 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.

getNamesOfAllClasses

public Set<String> getNamesOfAllClasses()

Returns the names of all classes and interfaces processed during the scan, i.e. all classes reachable after taking into account the package whitelist and blacklist criteria.

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).