Package io.github.lukehutch.fastclasspathscanner.scanner

Class ScanSpec

  • public class ScanSpec
extends Object
    Parses the scanning specification that was passed to the FastClasspathScanner constructor, and finds all ClassLoaders. Also defines core MatchProcessor matching logic.

    • Field Detail

      • whitelistedPathPrefixes

        public List<String> whitelistedPathPrefixes
        Whitelisted package paths with "/" appended, or the empty list if all packages are whitelisted. These packages and any subpackages will be scanned.

      • whitelistedPathsNonRecursive

        public List<String> whitelistedPathsNonRecursive
        Whitelisted package paths with "/" appended, or the empty list if all packages are whitelisted. These packages will be scanned, but subpackages will not be scanned unless they are whitelisted.

      • blacklistedPathPrefixes

        public transient List<String> blacklistedPathPrefixes
        Blacklisted package paths with "/" appended. Neither these packages nor any subpackages will be scanned.

      • blacklistedPackagePrefixes

        public List<String> blacklistedPackagePrefixes
        Blacklisted package names with "." appended. Neither these packages nor any subpackages will be scanned.

      • specificallyWhitelistedClassRelativePaths

        public Set<String> specificallyWhitelistedClassRelativePaths
        Whitelisted class names, or the empty list if none.

      • specificallyWhitelistedClassParentRelativePaths

        public transient Set<String> specificallyWhitelistedClassParentRelativePaths
        Path prefixes of whitelisted classes, or the empty list if none.

      • specificallyBlacklistedClassRelativePaths

        public Set<String> specificallyBlacklistedClassRelativePaths
        Blacklisted class relative paths.

      • specificallyBlacklistedClassNames

        public Set<String> specificallyBlacklistedClassNames
        Blacklisted class names.

      • whitelistedJars

        public Set<String> whitelistedJars
        Whitelisted jarfile names. (Leaf filename only.)

      • whitelistedLibOrExtJarPaths

        public Set<String> whitelistedLibOrExtJarPaths
        Complete paths of whitelisted jars to scan in the JDK/JRE "lib/" or "ext/" directory.

      • blacklistedLibOrExtJarPaths

        public Set<String> blacklistedLibOrExtJarPaths
        Complete paths of blacklisted in the JDK/JRE "lib/" or "ext/" directory.

      • blacklistedJars

        public Set<String> blacklistedJars
        Blacklisted jarfile names. (Leaf filename only.)

      • whitelistedModules

        public Set<String> whitelistedModules
        Names of whitelisted modules.

      • blacklistedModules

        public Set<String> blacklistedModules
        Names of blacklisted modules.

      • whitelistedJarPatterns

        public transient List<Pattern> whitelistedJarPatterns
        Whitelisted jarfile names containing a glob('*') character, converted to a regexp. (Leaf filename only.)

      • blacklistedJarPatterns

        public transient List<Pattern> blacklistedJarPatterns
        Blacklisted jarfile names containing a glob('*') character, converted to a regexp. (Leaf filename only.)

      • scanJars

        public boolean scanJars
        True if jarfiles on the classpath should be scanned.

      • scanDirs

        public boolean scanDirs
        True if directories on the classpath should be scanned.

      • enableMethodAnnotationIndexing

        public boolean enableMethodAnnotationIndexing
        If true, index method annotations.

      • enableFieldAnnotationIndexing

        public boolean enableFieldAnnotationIndexing
        If true, index field annotations.

      • enableFieldInfo

        public boolean enableFieldInfo
        If true, enables the saving of field info during the scan. This information can be obtained using ClassInfo#getFieldInfo(). By default, field info is not saved for efficiency.

      • enableMethodInfo

        public boolean enableMethodInfo
        If true, enables the saving of method info during the scan. This information can be obtained using ClassInfo#getMethodInfo(). By default, method info is not saved for efficiency.

      • enableExternalClasses

        public boolean enableExternalClasses
        If true, allow external classes (classes outside of whitelisted packages) to be returned in the ScanResult, if they are directly referred to by a whitelisted class, as a superclass, implemented interface or annotation. Disabled by default.

      • blacklistSystemJarsOrModules

        public boolean blacklistSystemJarsOrModules
        True if JRE system jarfiles (rt.jar etc.) should not be scanned. By default, these are not scanned. This can be overridden by including "!!" in the scan spec. Disabling this blacklisting will increase the time or memory required to scan the classpath.

      • ignoreFieldVisibility

        public boolean ignoreFieldVisibility
        If true, ignore field visibility (affects finding classes with fields of a given type, and matching of static final fields with constant initializers). If false, fields must be public to be indexed/matched.

      • ignoreMethodVisibility

        public boolean ignoreMethodVisibility
        If true, ignore method visibility (affects finding methods with annotations of a given type). If false, methods must be public to be indexed/matched.

      • annotationVisibility

        public RetentionPolicy annotationVisibility
        Annotation retention visibility: RetentionPolicy.CLASS matches all annotations (both RuntimeVisible and RuntimeInvisible); RetentionPolicy.RUNTIME matches only RuntimeVisible annotations.

      • disableRecursiveScanning

        public boolean disableRecursiveScanning
        Whether to disable recursive scanning (enabled by default). If set to false, only toplevel entries within each whitelisted package will be scanned, i.e. sub-packages of whitelisted packages will not be scanned. If no whitelisted packages were provided to the FastClasspathScanner constructor, then only the toplevel directory within each classpath element will be scanned.

      • suppressMatchProcessorExceptions

        public boolean suppressMatchProcessorExceptions
        If true, exceptions thrown inside MatchProcessors are not re-thrown wrapped in a MatchProcessorException at the end of the scan, and the exceptions can be fetched using ScanResult.getMatchProcessorExceptions(). If false, at the end of a scan, if ScanResult.getMatchProcessorExceptions() returns a non-empty list, MatchProcessorException is thrown to the caller.

      • addedClassLoaders

        public transient List<ClassLoader> addedClassLoaders
        If non-null, specified manually-added classloaders that should be searched after the context classloader(s).

      • overrideClassLoaders

        public transient List<ClassLoader> overrideClassLoaders
        If non-null, all ClassLoaders have been overriden. In particular, this causes FastClasspathScanner to ignore the java.class.path system property.

      • overrideClasspath

        public String overrideClasspath
        If non-null, specifies a classpath to override the default one.

      • initializeLoadedClasses

        public transient boolean initializeLoadedClasses
        If true, classes loaded with Class.forName() are initialized before passing class references to MatchProcessors. If false (the default), matched classes are loaded but not initialized before passing class references to MatchProcessors (meaning classes are instead initialized lazily on first usage of the class).

      • removeTemporaryFilesAfterScan

        public transient boolean removeTemporaryFilesAfterScan
        If true, nested jarfiles (jarfiles within jarfiles) that are extracted during scanning are removed from their temporary directory (e.g. /tmp/FastClasspathScanner-8JX2u4w) after the scan has completed. If false, temporary files are removed by the ScanResult finalizer, or on JVM exit.

      • ignoreParentClassLoaders

        public transient boolean ignoreParentClassLoaders
        If true, do not fetch paths from parent classloaders.

      • stripSFXHeader

        public transient boolean stripSFXHeader
        If true, manually strip the self extracting executable header from zipfiles (i.e. anything before the magic marker "PK", e.g. a Bash script added by Spring-Boot). Slightly increases scanning time, since zipfiles have to be opened twice (once as a byte stream, to check if there is an SFX header, then once as a ZipFile, for decompression). Should only be needed in rare cases, where you are dealing with jarfiles with prepended (ZipSFX) headers, where your JVM does not already automatically skip forward to the first "PK" marker (Oracle JVM on Linux does this automatically).

      • createClassLoaderForMatchingClasses

        public transient boolean createClassLoaderForMatchingClasses
        If this method is called, a new URLClassLoader is created for all classes found on the classpath that match whitelist criteria. This may be needed if you get a ClassNotFoundException, UnsatisfiedLinkError, NoClassDefFoundError, etc., due to trying to load classes that depend upon each other but that are loaded by different ClassLoaders in the classpath.

    • Constructor Detail

      • ScanSpec

        public ScanSpec​(String[] scanSpecFields,
                LogNode log)
        Parses the scanning specification that was passed to the FastClasspathScanner constructor, and finds all ClassLoaders.
        Parameters:
        scanSpecFields - The scan spec fields, passed into the FastClasspathScanner constructor.
        log - The log.

    • Method Detail

      • getClassNameToStaticFinalFieldsToMatch

        public MultiMapKeyToSet<String,String> getClassNameToStaticFinalFieldsToMatch()
        Get the map from class name to static final fields to match.
        Returns:
        The map from class name to static final fields to match.

      • registerClassLoaderHandler

        public void registerClassLoaderHandler​(Class<? extends ClassLoaderHandler> classLoaderHandler)
        Register an extra ClassLoaderHandler.
        Parameters:
        classLoaderHandler - The class of the ClassLoaderHandler that can handle those ClassLoaders.

      • overrideClasspath

        public void overrideClasspath​(String overrideClasspath)
        Override the automatically-detected classpath with a custom search path. You can specify multiple elements, separated by File.pathSeparatorChar. If this method is called, nothing but the provided classpath will be scanned, i.e. causes ClassLoaders to be ignored, as well as the java.class.path system property.
        Parameters:
        overrideClasspath - The classpath to scan.

      • filterClasspathElements

        public void filterClasspathElements​(FastClasspathScanner.ClasspathElementFilter classpathElementFilter)
        Add a classpath element filter. The provided ClasspathElementFilter should return true if the path string passed to it is a path you want to scan.
        Parameters:
        classpathElementFilter - The classpath element filter to apply to all discovered classpath elements, to decide which should be scanned.

      • addClassLoader

        public void addClassLoader​(ClassLoader classLoader)
        Add a ClassLoader to the list of ClassLoaders to scan. (This only works if overrideClasspath() is not called.)
        Parameters:
        classLoader - The classloader to add.

      • overrideClassLoaders

        public void overrideClassLoaders​(ClassLoader... overrideClassLoaders)
        Completely override the list of ClassLoaders to scan. (This only works if overrideClasspath() is not called.) Causes the java.class.path system property to be ignored.
        Parameters:
        overrideClassLoaders - The classloaders to override the default context classloaders with.

      • hasMatchProcessors

        public boolean hasMatchProcessors()
        Return true if any MatchProcessors have been added.
        Returns:
        True if any MatchProcessors have been added.

      • callMatchProcessors

        public void callMatchProcessors​(ScanResult scanResult)
        Run the MatchProcessors after a scan has completed.
        Parameters:
        scanResult - The ScanResult.

      • matchAllClasses

        public void matchAllClasses​(ClassMatchProcessor classMatchProcessor)
        Calls the provided ClassMatchProcessor for all standard classes, interfaces and annotations found in whitelisted packages on the classpath.
        Parameters:
        classMatchProcessor - the ClassMatchProcessor to call when a match is found.

      • matchAllStandardClasses

        public void matchAllStandardClasses​(ClassMatchProcessor classMatchProcessor)
        Calls the provided ClassMatchProcessor for all standard classes (i.e. non-interface, non-annotation classes) found in whitelisted packages on the classpath.
        Parameters:
        classMatchProcessor - the ClassMatchProcessor to call when a match is found.

      • matchAllInterfaceClasses

        public void matchAllInterfaceClasses​(ClassMatchProcessor classMatchProcessor)
        Calls the provided ClassMatchProcessor for all interface classes (interface definitions) found in whitelisted packages on the classpath.
        Parameters:
        classMatchProcessor - the ClassMatchProcessor to call when a match is found.

      • matchAllAnnotationClasses

        public void matchAllAnnotationClasses​(ClassMatchProcessor classMatchProcessor)
        Calls the provided ClassMatchProcessor for all annotation classes (annotation definitions) found in whitelisted packages on the classpath.
        Parameters:
        classMatchProcessor - the ClassMatchProcessor to call when a match is found.

      • matchSubclassesOf

        public <T> void matchSubclassesOf​(Class<T> superclass,
                                  SubclassMatchProcessor<T> subclassMatchProcessor)
        Calls the provided SubclassMatchProcessor if classes are found on the classpath that extend the specified superclass.
        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.

      • matchSubinterfacesOf

        public <T> void matchSubinterfacesOf​(Class<T> superinterface,
                                     SubinterfaceMatchProcessor<T> subinterfaceMatchProcessor)
        Calls the provided SubinterfaceMatchProcessor if an interface that extends a given superinterface is found on the classpath.
        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.

      • matchClassesImplementing

        public <T> void matchClassesImplementing​(Class<T> implementedInterface,
                                         ImplementingClassMatchProcessor<T> implementingClassMatchProcessor)
        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.
        Parameters:
        implementedInterface - The interface that classes need to implement.
        implementingClassMatchProcessor - the ClassMatchProcessor to call when a match is found.

      • matchClassesWithAnnotation

        public void matchClassesWithAnnotation​(Class<?> annotation,
                                       ClassAnnotationMatchProcessor classAnnotationMatchProcessor)
        Calls the provided ClassAnnotationMatchProcessor 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.

      • matchClassesWithMethodAnnotation

        public void matchClassesWithMethodAnnotation​(Class<? extends Annotation> annotation,
                                             MethodAnnotationMatchProcessor methodAnnotationMatchProcessor)
        Calls the provided MethodAnnotationMatchProcessor if classes are found on the classpath that have one or more methods with the specified annotation.
        Parameters:
        annotation - The method annotation to match.
        methodAnnotationMatchProcessor - the MethodAnnotationMatchProcessor to call when a match is found.

      • matchClassesWithFieldAnnotation

        public void matchClassesWithFieldAnnotation​(Class<? extends Annotation> annotation,
                                            FieldAnnotationMatchProcessor fieldAnnotationMatchProcessor)
        Calls the provided FieldAnnotationMatchProcessor if classes are found on the classpath that have one or more fields with the specified annotation.
        Parameters:
        annotation - The method annotation to match.
        fieldAnnotationMatchProcessor - the FieldAnnotationMatchProcessor to call when a match is found.

      • matchStaticFinalFieldNames

        public void matchStaticFinalFieldNames​(Set<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 if ignoreFieldVisibility() was called before scan().

        Parameters:
        fullyQualifiedStaticFinalFieldNames - The set of fully-qualified static field names to match.
        staticFinalFieldMatchProcessor - the StaticFinalFieldMatchProcessor to call when a match is found.

      • matchStaticFinalFieldNames

        public void 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 if ignoreFieldVisibility() was called before scan().

        Parameters:
        fullyQualifiedStaticFinalFieldName - The fully-qualified static field name to match
        staticFinalFieldMatchProcessor - the StaticFinalFieldMatchProcessor to call when a match is found.

      • matchStaticFinalFieldNames

        public void 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 if ignoreFieldVisibility() was called before scan().

        Parameters:
        fullyQualifiedStaticFinalFieldNames - The list of fully-qualified static field names to match.
        staticFinalFieldMatchProcessor - the StaticFinalFieldMatchProcessor to call when a match is found.

      • matchFilenamePattern

        public void matchFilenamePattern​(String pathRegexp,
                                 FileMatchProcessorAny 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.

      • matchFilenamePath

        public void matchFilenamePath​(String relativePathToMatch,
                              FileMatchProcessorAny 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.

      • matchFilenamePathLeaf

        public void matchFilenamePathLeaf​(String pathLeafToMatch,
                                  FileMatchProcessorAny 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.

      • matchFilenameExtension

        public void matchFilenameExtension​(String extensionToMatch,
                                   FileMatchProcessorAny 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.