Package io.github.lukehutch.fastclasspathscanner

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

    Documentation:

    https://github.com/lukehutch/fast-classpath-scanner/wiki

    • Constructor Detail

      • FastClasspathScanner

        public FastClasspathScanner​(String... scanSpec)
        Construct a FastClasspathScanner instance. You can pass a scanning specification to the constructor to describe what should be scanned -- see the docs for info:

        https://github.com/lukehutch/fast-classpath-scanner/wiki/2.-Constructor

        The scanSpec, if non-empty, 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. See https://github.com/lukehutch/fast-classpath-scanner/wiki/2.-Constructor for info.

    • Method Detail

      • getVersion

        public static final String getVersion()
        Get the version number of FastClasspathScanner.
        Returns:
        the FastClasspathScanner version, or "unknown" if it could not be determined.

      • verbose

        public FastClasspathScanner verbose​(boolean verbose)
        Switches on verbose mode for debugging purposes if verbose == true. Call immediately after calling the constructor if you want full log output. Prints debug info to System.err.
        Parameters:
        verbose - Whether or not to give verbose output.
        Returns:
        this (for method chaining).

      • verbose

        public FastClasspathScanner verbose()
        Switches on verbose mode for debugging purposes. Call immediately after calling the constructor if you want full log output. Prints debug info to System.err.
        Returns:
        this (for method chaining).

      • ignoreFieldVisibility

        public FastClasspathScanner ignoreFieldVisibility​(boolean ignoreFieldVisibility)
        If ignoreFieldVisibility is true, causes FastClasspathScanner to ignore field visibility, enabling it to see private, package-private and protected fields. This affects finding classes with fields of a given type, as well as matching static final fields with constant initializers, and saving FieldInfo for the class. If false, fields must be public to be indexed/matched.
        Parameters:
        ignoreFieldVisibility - Whether or not to ignore the field visibility modifier.
        Returns:
        this (for method chaining).

      • ignoreFieldVisibility

        public FastClasspathScanner ignoreFieldVisibility()
        This method causes FastClasspathScanner to ignore field visibility, enabling it to see private, package-private and protected fields. This affects finding classes with fields of a given type, as well as matching static final fields with constant initializers, and saving FieldInfo for the class. If false, fields must be public to be indexed/matched.
        Returns:
        this (for method chaining).

      • ignoreMethodVisibility

        public FastClasspathScanner ignoreMethodVisibility​(boolean ignoreMethodVisibility)
        If ignoreMethodVisibility is true, causes FastClasspathScanner to ignore method visibility, enabling it to see private, package-private and protected methods. This affects finding classes that have methods with a given annotation, and also the saving of MethodInfo for the class. If false, methods must be public for the containing classes to be indexed/matched.
        Parameters:
        ignoreMethodVisibility - Whether or not to ignore the method visibility modifier.
        Returns:
        this (for method chaining).

      • ignoreMethodVisibility

        public FastClasspathScanner ignoreMethodVisibility()
        This method causes FastClasspathScanner to ignore method visibility, enabling it to see private, package-private and protected methods. This affects finding classes that have methods with a given annotation, and also the saving of MethodInfo for the class. If false, methods must be public for the containing classes to be indexed/matched.
        Returns:
        this (for method chaining).

      • enableMethodAnnotationIndexing

        public FastClasspathScanner enableMethodAnnotationIndexing​(boolean enableMethodAnnotationIndexing)
        If enableMethodAnnotationIndexing is true, enables method annotation indexing, which allows you to call ScanResult#getNamesOfClassesWithMethodAnnotation(annotation). (If you add a method annotation match processor, this method is called for you.) Method annotation indexing is disabled by default, because it is expensive in terms of time, and it is not needed for most uses of FastClasspathScanner.
        Parameters:
        enableMethodAnnotationIndexing - Whether or not to enable method annotation indexing.
        Returns:
        this (for method chaining).

      • enableMethodAnnotationIndexing

        public FastClasspathScanner enableMethodAnnotationIndexing()
        Enables method annotation indexing, which allows you to call ScanResult#getNamesOfClassesWithMethodAnnotation(annotation). (If you add a method annotation match processor, this method is called for you.) Method annotation indexing is disabled by default, because it is expensive in terms of time, and it is not needed for most uses of FastClasspathScanner.
        Returns:
        this (for method chaining).

      • enableFieldAnnotationIndexing

        public FastClasspathScanner enableFieldAnnotationIndexing​(boolean enableFieldAnnotationIndexing)
        If enableFieldAnnotationIndexing is true, enables field annotation indexing, which allows you to call ScanResult#getNamesOfClassesWithFieldAnnotation(annotation). (If you add a method annotation match processor, this method is called for you.) Method annotation indexing is disabled by default, because it is expensive in terms of time, and it is not needed for most uses of FastClasspathScanner.
        Parameters:
        enableFieldAnnotationIndexing - Whether to enable field annotation indexing.
        Returns:
        this (for method chaining).

      • enableFieldAnnotationIndexing

        public FastClasspathScanner enableFieldAnnotationIndexing()
        Enables field annotation indexing, which allows you to call ScanResult#getNamesOfClassesWithFieldAnnotation(annotation). (If you add a method annotation match processor, this method is called for you.) Method annotation indexing is disabled by default, because it is expensive in terms of time, and it is not needed for most uses of FastClasspathScanner.
        Returns:
        this (for method chaining).

      • enableFieldInfo

        public FastClasspathScanner enableFieldInfo​(boolean enableFieldInfo)
        If enableFieldInfo is 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, because enabling this option will cause the scan to take somewhat longer and potentially consume a lot more memory.
        Parameters:
        enableFieldInfo - If true, save field info while scanning. (Default false.)
        Returns:
        this (for method chaining).

      • enableFieldInfo

        public FastClasspathScanner enableFieldInfo()
        Enables the saving of field info during the scan. This information can be obtained using ClassInfo#getFieldInfo(). By default, field info is not saved, because enabling this option will cause the scan to take somewhat longer and potentially consume a lot more memory.
        Returns:
        this (for method chaining).

      • enableMethodInfo

        public FastClasspathScanner enableMethodInfo​(boolean enableMethodInfo)
        If enableMethodInfo is 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, because enabling this option will cause the scan to take somewhat longer and potentially consume a lot more memory.
        Parameters:
        enableMethodInfo - If true, save method info while scanning. (Default false.)
        Returns:
        this (for method chaining).

      • enableMethodInfo

        public FastClasspathScanner enableMethodInfo()
        Enables the saving of method info during the scan. This information can be obtained using ClassInfo#getMethodInfo(). By default, method info is not saved, because enabling this option will cause the scan to take somewhat longer and potentially consume a lot more memory.
        Returns:
        this (for method chaining).

      • alwaysScanClasspathElementRoot

        public FastClasspathScanner alwaysScanClasspathElementRoot​(boolean alwaysScanClasspathElementRoot)
        Allows you to scan default packages (with package name "") without scanning sub-packages unless they are whitelisted. This is needed because if you add the package name "" to the whitelist, that package and all sub-packages will be scanned, which means everything will be scanned. This method makes it possible to whitelist just the toplevel (default) package but not its sub-packages.
        Parameters:
        alwaysScanClasspathElementRoot - If true, always scan the classpath element root, regardless of the whitelist or blacklist.
        Returns:
        this (for method chaining).

      • alwaysScanClasspathElementRoot

        public FastClasspathScanner alwaysScanClasspathElementRoot()
        Allows you to scan default packages (with package name "") without scanning sub-packages unless they are whitelisted. This is needed because if you add the package name "" to the whitelist, that package and all sub-packages will be scanned, which means everything will be scanned. This method makes it possible to whitelist just the toplevel (default) package but not its sub-packages.
        Returns:
        this (for method chaining).

      • strictWhitelist

        @Deprecated
public FastClasspathScanner strictWhitelist​(boolean strictWhitelist)
        Deprecated.
        If strictWhitelist is true, switches FastClasspathScanner to strict mode, which disallows searching/matching based on blacklisted classes, and removes "external" classes from result lists returned by ScanSpec#get...() methods. (External classes are classes outside of whitelisted packages that are directly referred to by classes within whitelisted packages as a superclass, implemented interface or annotation.)

        Deprecated (and now has no effect) -- non-strict mode is now the default (as of version 3.0.2). Use enableExternalClasses() to disable strict mode.

        See the following for info on external classes, and strict mode vs. non-strict mode:

        https://github.com/lukehutch/fast-classpath-scanner/wiki/2.-Constructor#external-classes

        Parameters:
        strictWhitelist - Whether or not to switch to strict mode.
        Returns:
        this (for method chaining).

      • strictWhitelist

        @Deprecated
public FastClasspathScanner strictWhitelist()
        Deprecated.
        Switches FastClasspathScanner to strict mode, which disallows searching/matching based on blacklisted classes, and removes "external" classes from result lists returned by ScanSpec#get...() methods. (External classes are classes outside of whitelisted packages that are directly referred to by classes within whitelisted packages as a superclass, implemented interface or annotation.)

        Deprecated (and now has no effect)-- non-strict mode is the default (as of version 3.0.2). Use enableExternalClasses() to disable strict mode.

        See the following for info on external classes, and strict mode vs. non-strict mode:

        https://github.com/lukehutch/fast-classpath-scanner/wiki/2.-Constructor#external-classes

        Returns:
        this (for method chaining).

      • enableExternalClasses

        public FastClasspathScanner enableExternalClasses​(boolean enableExternalClasses)
        Causes FastClasspathScanner to return matching classes that are not in the whitelisted packages, but that are directly referred to by classes within whitelisted packages as a superclass, implemented interface or annotation.

        See the following for info on external classes, and strict mode vs. non-strict mode:

        https://github.com/lukehutch/fast-classpath-scanner/wiki/2.-Constructor#external-classes

        Returns:
        this (for method chaining).

      • enableExternalClasses

        public FastClasspathScanner enableExternalClasses()
        Causes FastClasspathScanner to return matching classes that are not in the whitelisted packages, but that are directly referred to by classes within whitelisted packages as a superclass, implemented interface or annotation.

        See the following for info on external classes, and strict mode vs. non-strict mode:

        https://github.com/lukehutch/fast-classpath-scanner/wiki/2.-Constructor#external-classes

        Returns:
        this (for method chaining).

      • initializeLoadedClasses

        public FastClasspathScanner initializeLoadedClasses​(boolean initializeLoadedClasses)
        If initializeLoadedClasses is 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).
        Parameters:
        initializeLoadedClasses - Whether or not to initialize classes before passing class references to MatchProcessors. (The default value is false.)
        Returns:
        this (for method chaining).

      • removeTemporaryFilesAfterScan

        public FastClasspathScanner removeTemporaryFilesAfterScan​(boolean removeTemporaryFilesAfterScan)
        If true, nested jarfiles (jarfiles within jarfiles, which have to be extracted during scanning in order to be read) are removed from their temporary directory as soon as the scan has completed. If false (the default), temporary files removed by the ScanResult finalizer, or on JVM exit.
        Parameters:
        removeTemporaryFilesAfterScan - Whether or not to remove temporary files after scanning. (The default value is true.)
        Returns:
        this (for method chaining).

      • disableRecursiveScanning

        public FastClasspathScanner disableRecursiveScanning()
        Disable recursive scanning. Causes only toplevel entries within each whitelisted package to be scanned, i.e. sub-packages of whitelisted packages will not be scanned. If no whitelisted packages were provided to the constructor, then only the toplevel directory within each classpath element will be scanned.
        Returns:
        this (for method chaining).

      • disableRecursiveScanning

        public FastClasspathScanner disableRecursiveScanning​(boolean disableRecursiveScanning)
        If true, disable recursive scanning. Causes only toplevel entries within each whitelisted package to be scanned, i.e. sub-packages of whitelisted packages will not be scanned. If no whitelisted packages were provided to the constructor, then only the toplevel directory within each classpath element will be scanned. If false (the default), whitelisted paths and their subdirectories will be scanned.
        Parameters:
        disableRecursiveScanning - Whether or not to disable recursive scanning. (The default value is false.)
        Returns:
        this (for method chaining).

      • stripZipSFXHeaders

        public FastClasspathScanner stripZipSFXHeaders()
        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).
        Returns:
        this (for method chaining).

      • createClassLoaderForMatchingClasses

        public FastClasspathScanner 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.
        Returns:
        this (for method chaining).

      • registerClassLoaderHandler

        public FastClasspathScanner registerClassLoaderHandler​(Class<? extends ClassLoaderHandler> classLoaderHandlerClass)
        Register an extra ClassLoaderHandler. Needed if FastClasspathScanner doesn't know how to extract classpath entries from your runtime environment's ClassLoader. See:

        https://github.com/lukehutch/fast-classpath-scanner/wiki/4.-Working-with-nonstandard-ClassLoaders

        Parameters:
        classLoaderHandlerClass - The ClassLoaderHandler class to register.
        Returns:
        this (for method chaining).

      • overrideClasspath

        public FastClasspathScanner overrideClasspath​(String overrideClasspath)
        Override the automatically-detected classpath with a custom path, with path elements separated by File.pathSeparatorChar. Causes system ClassLoaders and the java.class.path system property to be ignored.

        If this method is called, nothing but the provided classpath will be scanned, i.e. this causes ClassLoaders to be ignored, as well as the java.class.path system property.

        Parameters:
        overrideClasspath - The custom classpath to use for scanning, with path elements separated by File.pathSeparatorChar.
        Returns:
        this (for method chaining).

      • overrideClasspath

        public FastClasspathScanner overrideClasspath​(Iterable<?> overrideClasspathElements)
        Override the automatically-detected classpath with a custom path. Causes system ClassLoaders and the java.class.path system property to be ignored. Works for Iterables of any type whose toString() method resolves to a classpath element string, e.g. String, File or Path.

        If this method is called, nothing but the provided classpath will be scanned, i.e. this causes ClassLoaders to be ignored, as well as the java.class.path system property.

        Parameters:
        overrideClasspathElements - The custom classpath to use for scanning, with path elements separated by File.pathSeparatorChar.
        Returns:
        this (for method chaining).

      • overrideClasspath

        public FastClasspathScanner overrideClasspath​(Object... overrideClasspathElements)
        Override the automatically-detected classpath with a custom path. Causes system ClassLoaders and the java.class.path system property to be ignored. Works for arrays of any member type whose toString() method resolves to a classpath element string, e.g. String, File or Path.
        Parameters:
        overrideClasspathElements - The custom classpath to use for scanning, with path elements separated by File.pathSeparatorChar.
        Returns:
        this (for method chaining).

      • filterClasspathElements

        public FastClasspathScanner 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 filter function to use. This function should return true if the classpath element path should be scanned, and false if not.
        Returns:
        this (for method chaining).

      • addClassLoader

        public FastClasspathScanner addClassLoader​(ClassLoader classLoader)
        Add a ClassLoader to the list of ClassLoaders to scan.

        This call is ignored if overrideClasspath() is also called, or if this method is called before overrideClassLoaders().

        This call is ignored if overrideClasspath() is called.

        Parameters:
        classLoader - The additional ClassLoader to scan.
        Returns:
        this (for method chaining).

      • overrideClassLoaders

        public FastClasspathScanner overrideClassLoaders​(ClassLoader... overrideClassLoaders)
        Completely override (and ignore) system ClassLoaders and the java.class.path system property.

        This call is ignored if overrideClasspath() is called.

        Parameters:
        overrideClassLoaders - The ClassLoaders to scan instead of the automatically-detected ClassLoaders.
        Returns:
        this (for method chaining).

      • ignoreParentClassLoaders

        public FastClasspathScanner ignoreParentClassLoaders​(boolean ignoreParentClassLoaders)
        Ignore parent classloaders (i.e. only obtain paths to scan from classloader(s), do not also fetch paths from parent classloader(s)).

        This call is ignored if overrideClasspath() is called.

        Parameters:
        ignoreParentClassLoaders - If true, do not fetch paths from parent classloaders.
        Returns:
        this (for method chaining).

      • ignoreParentClassLoaders

        public FastClasspathScanner ignoreParentClassLoaders()
        Ignore parent classloaders (i.e. only obtain paths to scan from classloader(s), do not also fetch paths from parent classloader(s)).

        This call is ignored if overrideClasspath() is called.

        Returns:
        this (for method chaining).

      • suppressMatchProcessorExceptions

        public FastClasspathScanner suppressMatchProcessorExceptions()
        Causes exceptions thrown inside MatchProcessors to not be re-thrown, wrapped in a MatchProcessorException, at the end of a synchronous scan. Instead, any thrown exceptions can be fetched using ScanResult.getMatchProcessorExceptions().
        Returns:
        this (for method chaining).

      • suppressMatchProcessorExceptions

        public FastClasspathScanner suppressMatchProcessorExceptions​(boolean suppressMatchProcessorExceptions)
        If suppressMatchProcessorExceptions is true, exceptions thrown inside MatchProcessors are not re-thrown wrapped in a MatchProcessorException at the end of a synchronous scan, and any thrown exceptions can be fetched using ScanResult.getMatchProcessorExceptions(). If suppressMatchProcessorExceptions is false, at the end of a synchronous scan, if ScanResult.getMatchProcessorExceptions() returns a non-empty list, MatchProcessorException is thrown to the caller.
        Parameters:
        suppressMatchProcessorExceptions - Whether to suppress MatchProcessorExceptions.
        Returns:
        this (for method chaining).

      • findBestClassLoader

        @Deprecated
public ClassLoader[] findBestClassLoader()
        Deprecated.
        Find the classloader or classloaders most likely to represent the order that classloaders are used to resolve classes in the current context. Uses the technique described by Vladimir Roubtsov.

        Generally this will return exactly one ClassLoader, but if it returns more than one, the classloaders are listed in the order they should be called in until one of them is able to load the named class. If you can call only one ClassLoader, use the first element of the list.

        If you have overridden the ClassLoader(s), then the override ClassLoader(s) will be returned instead.

        Deprecated, since classloaders may need to be generated dynamically for loading classes from Spring-Boot jars and similar (#209).

        Returns:
        A list of one or more ClassLoaders, out of the system ClassLoader, the current classloader, or the context classloader (or the override ClassLoaders, if ClassLoaders have been overridden).

      • matchAllClasses

        public FastClasspathScanner 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.
        Returns:
        this (for method chaining).

      • matchAllStandardClasses

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

      • matchAllInterfaceClasses

        public FastClasspathScanner matchAllInterfaceClasses​(ClassMatchProcessor interfaceClassMatchProcessor)
        Calls the provided ClassMatchProcessor for all interface classes (interface definitions) found in whitelisted packages on the classpath.
        Parameters:
        interfaceClassMatchProcessor - the ClassMatchProcessor to call when a match is found.
        Returns:
        this (for method chaining).

      • matchAllAnnotationClasses

        public FastClasspathScanner matchAllAnnotationClasses​(ClassMatchProcessor annotationClassMatchProcessor)
        Calls the provided ClassMatchProcessor for all annotation classes (annotation definitions) found in whitelisted packages on the classpath.
        Parameters:
        annotationClassMatchProcessor - the ClassMatchProcessor to call when a match is found.
        Returns:
        this (for method chaining).

      • 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.
        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.
        Returns:
        this (for method chaining).

      • 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.
        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.
        Returns:
        this (for method chaining).

      • matchClassesImplementing

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

      • matchClassesWithAnnotation

        public FastClasspathScanner 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.
        Returns:
        this (for method chaining).

      • matchClassesWithMethodAnnotation

        public FastClasspathScanner 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.

        Calls enableMethodAnnotationIndexing() for you.

        Parameters:
        annotation - The method annotation to match.
        methodAnnotationMatchProcessor - the MethodAnnotationMatchProcessor to call when a match is found.
        Returns:
        this (for method chaining).

      • matchClassesWithFieldAnnotation

        public FastClasspathScanner 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.

        Calls enableFieldAnnotationIndexing() for you.

        Parameters:
        annotation - The field annotation to match.
        fieldAnnotationMatchProcessor - the FieldAnnotationMatchProcessor to call when a match is found.
        Returns:
        this (for method chaining).

      • setAnnotationVisibility

        public FastClasspathScanner setAnnotationVisibility​(RetentionPolicy annotationVisibility)
        Set annotation visibility (to match the annotation retention policy).
        Parameters:
        annotationVisibility - The annotation visibility: RetentionPolicy.RUNTIME matches only runtime-visible annotations. The default value, RetentionPolicy.CLASS, matches all annotations (both runtime-visible and runtime-invisible). RetentionPolicy.SOURCE will cause an IllegalArgumentException to be thrown, since SOURCE-annotated annotations are not retained in classfiles.
        Returns:
        this (for method chaining).

      • matchStaticFinalFieldNames

        public FastClasspathScanner 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.
        Returns:
        this (for method chaining).

      • 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 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.
        Returns:
        this (for method chaining).

      • 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 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.
        Returns:
        this (for method chaining).

      • matchFilenamePattern

        public FastClasspathScanner matchFilenamePattern​(String pathRegexp,
                                                 FilenameMatchProcessor filenameMatchProcessor)
        Calls the given FilenameMatchProcessor 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"
        filenameMatchProcessor - The FilenameMatchProcessor to call when each match is found.
        Returns:
        this (for method chaining).

      • 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.
        Returns:
        this (for method chaining).

      • 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.
        Returns:
        this (for method chaining).

      • 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.
        Returns:
        this (for method chaining).

      • 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.
        Returns:
        this (for method chaining).

      • matchFilenamePath

        public FastClasspathScanner matchFilenamePath​(String relativePathToMatch,
                                              FilenameMatchProcessor filenameMatchProcessor)
        Calls the given FilenameMatchProcessor 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"
        filenameMatchProcessor - The FilenameMatchProcessor to call when each match is found.
        Returns:
        this (for method chaining).

      • 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.
        Returns:
        this (for method chaining).

      • 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.
        Returns:
        this (for method chaining).

      • 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.
        Returns:
        this (for method chaining).

      • 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.
        Returns:
        this (for method chaining).

      • matchFilenamePathLeaf

        public FastClasspathScanner matchFilenamePathLeaf​(String pathLeafToMatch,
                                                  FilenameMatchProcessor filenameMatchProcessor)
        Calls the given FilenameMatchProcessor 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"
        filenameMatchProcessor - The FilenameMatchProcessor to call when each match is found.
        Returns:
        this (for method chaining).

      • 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.
        Returns:
        this (for method chaining).

      • 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.
        Returns:
        this (for method chaining).

      • 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.
        Returns:
        this (for method chaining).

      • 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.
        Returns:
        this (for method chaining).

      • matchFilenameExtension

        public FastClasspathScanner matchFilenameExtension​(String extensionToMatch,
                                                   FilenameMatchProcessor filenameMatchProcessor)
        Calls the given FilenameMatchProcessor 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".
        filenameMatchProcessor - The FilenameMatchProcessor to call when each match is found.
        Returns:
        this (for method chaining).

      • 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.
        Returns:
        this (for method chaining).

      • 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.
        Returns:
        this (for method chaining).

      • 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.
        Returns:
        this (for method chaining).

      • 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.
        Returns:
        this (for method chaining).

      • scanAsync

        public void scanAsync​(ExecutorService executorService,
                      int numParallelTasks,
                      ScanResultProcessor scanResultProcessor,
                      FailureHandler failureHandler)
        Asynchronously scans the classpath for matching files, and if runAsynchronously is true, also calls any MatchProcessors if a match is identified.
        Parameters:
        executorService - A custom ExecutorService to use for scheduling worker tasks.
        numParallelTasks - The number of parallel tasks to break the work into during the most CPU-intensive stage of classpath scanning. Ideally the ExecutorService will have at least this many threads available.
        scanResultProcessor - A callback to run on successful scan. Passed the ScanResult after asynchronous scanning has completed and MatchProcessors have been run. (If null, throws IllegalArgumentException.)
        failureHandler - A callback to run on failed scan. Passed any Throwable thrown during the scan. (If null, throws IllegalArgumentException.)

      • scanAsync

        public Future<ScanResult> scanAsync​(ExecutorService executorService,
                                    int numParallelTasks)
        Asynchronously scans the classpath for matching files, and calls any MatchProcessors if a match is identified. Returns a Future object immediately after starting the scan. To block on scan completion, get the result of the returned Future. Uses the provided ExecutorService, and divides the work according to the requested degree of parallelism. This method should be called after all required MatchProcessors have been added.

        Note on thread safety: MatchProcessors are all run on a separate thread from the thread that calls this method (although the MatchProcessors are all run on one thread). You will need to add your own synchronization logic if MatchProcessors interact with the main thread. See the following for more info:

        https://github.com/lukehutch/fast-classpath-scanner/wiki/1.-Usage#multithreading-issues

        Parameters:
        executorService - A custom ExecutorService to use for scheduling worker tasks.
        numParallelTasks - The number of parallel tasks to break the work into during the most CPU-intensive stage of classpath scanning. Ideally the ExecutorService will have at least this many threads available.
        Returns:
        a Future object, that when resolved using get() yields a new ScanResult object. This ScanResult object contains info about the class graph within whitelisted packages encountered during the scan. Calling get() on this Future object throws InterruptedException if the scanning is interrupted before it completes, or throws ExecutionException if something goes wrong during scanning. If ExecutionException is thrown, and the cause is a MatchProcessorException, then either classloading failed for some class, or a MatchProcessor threw an exception.

      • scan

        public ScanResult scan​(ExecutorService executorService,
                       int numParallelTasks)
        Scans the classpath for matching files, and calls any MatchProcessors if a match is identified. Uses the provided ExecutorService, and divides the work according to the requested degree of parallelism. Blocks and waits for the scan to complete before returning a ScanResult. This method should be called after all required MatchProcessors have been added.
        Parameters:
        executorService - A custom ExecutorService to use for scheduling worker tasks. This ExecutorService should start tasks in FIFO order to avoid a deadlock during scan, i.e. be sure to construct the ExecutorService with a LinkedBlockingQueue as its task queue. (This is the default for Executors.newFixedThreadPool().)
        numParallelTasks - The number of parallel tasks to break the work into during the most CPU-intensive stage of classpath scanning. Ideally the ExecutorService will have at least this many threads available.
        Returns:
        a new ScanResult object, containing info about the class graph within whitelisted packages encountered during the scan.
        Throws:
        MatchProcessorException - if classloading fails for any of the classes matched by a MatchProcessor, or if a MatchProcessor throws an exception. If suppressMatchProcessorExceptions() is called before scan(), then MatchProcessorException will not be thrown at the end of scanning, and instead, any exceptions that were thrown by MatchProcessors can be fetched using ScanResult.getMatchProcessorExceptions().
        ScanInterruptedException - if any of the worker threads are interrupted during the scan. If you care about thread interruption, you should catch this exception. If you don't plan to interrupt the scan, you probably don't need to catch this.
        RuntimeException - if any of the worker threads throws an uncaught exception. (Should not happen, this would indicate a bug in FastClasspathScanner.)

      • scan

        public ScanResult scan​(int numThreads)
        Scans the classpath for matching files, and calls any MatchProcessors if a match is identified. Temporarily starts up a new fixed thread pool for scanning, with the requested number of threads. Blocks and waits for the scan to complete before returning a ScanResult. This method should be called after all required MatchProcessors have been added.
        Parameters:
        numThreads - The number of worker threads to start up.
        Returns:
        a new ScanResult object, containing info about the class graph within whitelisted packages encountered during the scan.
        Throws:
        MatchProcessorException - if classloading fails for any of the classes matched by a MatchProcessor, or if a MatchProcessor throws an exception. If suppressMatchProcessorExceptions() is called before scan(), then MatchProcessorException will not be thrown at the end of scanning, and instead, any exceptions that were thrown by MatchProcessors can be fetched using ScanResult.getMatchProcessorExceptions().
        ScanInterruptedException - if any of the worker threads are interrupted during the scan (shouldn't happen under normal circumstances).
        RuntimeException - if any of the worker threads throws an uncaught exception. (Should not happen, this would indicate a bug in FastClasspathScanner.)

      • scan

        public ScanResult scan()
        Scans the classpath for matching files, and calls any MatchProcessors if a match is identified. Temporarily starts up a new fixed thread pool for scanning, with the default number of threads. Blocks and waits for the scan to complete before returning a ScanResult. This method should be called after all required MatchProcessors have been added.
        Returns:
        a new ScanResult object, containing info about the class graph within whitelisted packages encountered during the scan.
        Throws:
        MatchProcessorException - if classloading fails for any of the classes matched by a MatchProcessor, or if a MatchProcessor throws an exception. If suppressMatchProcessorExceptions() is called before scan(), then MatchProcessorException will not be thrown at the end of scanning, and instead, any exceptions that were thrown by MatchProcessors can be fetched using ScanResult.getMatchProcessorExceptions().
        ScanInterruptedException - if any of the worker threads are interrupted during the scan (shouldn't happen under normal circumstances).
        RuntimeException - if any of the worker threads throws an uncaught exception. (Should not happen, this would indicate a bug in FastClasspathScanner.)

      • getUniqueClasspathElementsAsync

        public Future<List<File>> getUniqueClasspathElementsAsync​(ExecutorService executorService,
                                                          int numParallelTasks)
        Asynchronously 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.

        See the following for info on thread safety:

        https://github.com/lukehutch/fast-classpath-scanner/wiki/1.-Usage#multithreading-issues

        Note that if there are nested jarfiles on the classpath, e.g. file:///path/to/jar1.jar!/path/to/jar2.jar, then both FastClasspathScanner#scanAsync() and FastClasspathScanner#getUniqueClasspathElementsAsync() will cause jar2.jar to be extracted to a temporary file, however FastClasspathScanner#getUniqueClasspathElementsAsync() will not remove this temporary file after the scan (so that the file is still accessible to the caller -- each of the File objects in the returned list of classpath elements should exist). These extracted temporary files are marked for deletion on JVM exit, however.

        Parameters:
        executorService - A custom ExecutorService to use for scheduling worker tasks.
        numParallelTasks - The number of parallel tasks to break the work into during the most CPU-intensive stage of classpath scanning. Ideally the ExecutorService will have at least this many threads available.
        Returns:
        a Future<List<File>>, that when resolved with get() returns a list of the unique directories and jarfiles on the classpath, in classpath resolution order. You can call cancel(true) on this Future if you want to interrupt the process (although the result is typically returned quickly).

      • getUniqueClasspathElements

        public List<File> getUniqueClasspathElements​(ExecutorService executorService,
                                             int numParallelTasks)
        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. Blocks until the result can be returned, when all classpath elements have been found and tested to see if they exist in the filesystem.

        Note that if there are nested jarfiles on the classpath, e.g. file:///path/to/jar1.jar!/path/to/jar2.jar, then both FastClasspathScanner#scan() and FastClasspathScanner#getUniqueClasspathElements() will cause jar2.jar to be extracted to a temporary file, however FastClasspathScanner#getUniqueClasspathElements() will not remove this temporary file after the scan (so that the file is still accessible to the caller -- each of the File objects in the returned list of classpath elements should exist). These extracted temporary files are marked for deletion on JVM exit, however.

        Parameters:
        executorService - A custom ExecutorService to use for scheduling worker tasks.
        numParallelTasks - The number of parallel tasks to break the work into during the most CPU-intensive stage of classpath scanning. Ideally the ExecutorService will have at least this many threads available.
        Returns:
        a List<File> consisting of the unique directories and jarfiles on the classpath, in classpath resolution order.
        Throws:
        ScanInterruptedException - if any of the worker threads are interrupted during the scan. If you care about thread interruption, you should catch this exception. If you don't plan to interrupt the scan, you probably don't need to catch this.

      • 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. Blocks until the result can be returned, when all classpath elements have been found and tested to see if they exist in the filesystem.

        Note that if there are nested jarfiles on the classpath, e.g. file:///path/to/jar1.jar!/path/to/jar2.jar, then both FastClasspathScanner#scan() and FastClasspathScanner#getUniqueClasspathElements() will cause jar2.jar to be extracted to a temporary file, however FastClasspathScanner#getUniqueClasspathElements() will not remove this temporary file after the scan (so that the file is still accessible to the caller -- each of the File objects in the returned list of classpath elements should exist). These extracted temporary files are marked for deletion on JVM exit, however.

        Returns:
        a List<File> consisting of the unique directories and jarfiles on the classpath, in classpath resolution order.
        Throws:
        ScanInterruptedException - if any of the worker threads are interrupted during the scan (shouldn't happen under normal circumstances).

      • getUniqueClasspathElementsAsPathStr

        public String getUniqueClasspathElementsAsPathStr()
        Returns all unique directories or zip/jarfiles on the classpath, in classloader resolution order, as a classpath string, delineated with the standard path separator character. Classpath elements that do not exist are not included in the path. Blocks until the result can be returned, when all classpath elements have been found and tested to see if they exist in the filesystem.

        Note that if there are nested jarfiles on the classpath, e.g. file:///path/to/jar1.jar!/path/to/jar2.jar, then both FastClasspathScanner#scan() and FastClasspathScanner#getUniqueClasspathElements() will cause jar2.jar to be extracted to a temporary file, however FastClasspathScanner#getUniqueClasspathElements() will not remove this temporary file after the scan (so that the file is still accessible to the caller -- each of the File objects in the returned list of classpath elements should exist). These extracted temporary files are marked for deletion on JVM exit, however.

        Returns:
        a the unique directories and jarfiles on the classpath, in classpath resolution order, as a path string.
        Throws:
        ScanInterruptedException - if any of the worker threads are interrupted during the scan (shouldn't happen under normal circumstances).

      • getUniqueClasspathElementURLsAsync

        public Future<List<URL>> getUniqueClasspathElementURLsAsync​(ExecutorService executorService,
                                                            int numParallelTasks)
        Asynchronously returns the list of all unique URLs representing directories or zip/jarfiles on the classpath, in classloader resolution order. Classpath elements that do not exist are not included in the list.

        See the following for info on thread safety:

        https://github.com/lukehutch/fast-classpath-scanner/wiki/1.-Usage#multithreading-issues

        Note that if there are nested jarfiles on the classpath, e.g. file:///path/to/jar1.jar!/path/to/jar2.jar, then both FastClasspathScanner#scanAsync() and FastClasspathScanner#getUniqueClasspathElementsAsync() will cause jar2.jar to be extracted to a temporary file, however FastClasspathScanner#getUniqueClasspathElementURLsAsync() will not remove this temporary file after the scan (so that the file is still accessible to the caller -- each of the File objects in the returned list of classpath elements should exist). These extracted temporary files are marked for deletion on JVM exit, however.

        Parameters:
        executorService - A custom ExecutorService to use for scheduling worker tasks.
        numParallelTasks - The number of parallel tasks to break the work into during the most CPU-intensive stage of classpath scanning. Ideally the ExecutorService will have at least this many threads available.
        Returns:
        a Future<List<URL>>, that when resolved with get() returns a list of URLs for the unique directories and jarfiles on the classpath, in classpath resolution order. You can call cancel(true) on this Future if you want to interrupt the process (although the result is typically returned quickly).

      • getUniqueClasspathElementURLs

        public List<URL> getUniqueClasspathElementURLs​(ExecutorService executorService,
                                               int numParallelTasks)
        Returns the list of all unique URL 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. Blocks until the result can be returned, when all classpath elements have been found and tested to see if they exist in the filesystem.

        Note that if there are nested jarfiles on the classpath, e.g. file:///path/to/jar1.jar!/path/to/jar2.jar, then both FastClasspathScanner#scan() and FastClasspathScanner#getUniqueClasspathElements() will cause jar2.jar to be extracted to a temporary file, however FastClasspathScanner#getUniqueClasspathElementURLs() will not remove this temporary file after the scan (so that the file is still accessible to the caller -- each of the File objects in the returned list of classpath elements should exist). These extracted temporary files are marked for deletion on JVM exit, however.

        Parameters:
        executorService - A custom ExecutorService to use for scheduling worker tasks.
        numParallelTasks - The number of parallel tasks to break the work into during the most CPU-intensive stage of classpath scanning. Ideally the ExecutorService will have at least this many threads available.
        Returns:
        a List<URL> consisting of the unique directories and jarfiles on the classpath, in classpath resolution order.
        Throws:
        ScanInterruptedException - if any of the worker threads are interrupted during the scan. If you care about thread interruption, you should catch this exception. If you don't plan to interrupt the scan, you probably don't need to catch this.

      • getUniqueClasspathElementURLs

        public List<URL> getUniqueClasspathElementURLs()
        Returns the list of all unique URL 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. Blocks until the result can be returned, when all classpath elements have been found and tested to see if they exist in the filesystem.

        Note that if there are nested jarfiles on the classpath, e.g. file:///path/to/jar1.jar!/path/to/jar2.jar, then both FastClasspathScanner#scan() and FastClasspathScanner#getUniqueClasspathElements() will cause jar2.jar to be extracted to a temporary file, however FastClasspathScanner#getUniqueClasspathElementURLs() will not remove this temporary file after the scan (so that the file is still accessible to the caller -- each of the File objects in the returned list of classpath elements should exist). These extracted temporary files are marked for deletion on JVM exit, however.

        Returns:
        a List<URL> consisting of the unique directories and jarfiles on the classpath, in classpath resolution order.
        Throws:
        ScanInterruptedException - if any of the worker threads are interrupted during the scan (shouldn't happen under normal circumstances).