Package io.github.classgraph

Class ClassGraph

  • public class ClassGraph
extends java.lang.Object
    Uber-fast, ultra-lightweight Java classpath and module path scanner. Scans classfiles in the classpath and/or module path by parsing the classfile binary format directly rather than by using reflection.

    Documentation: https://github.com/classgraph/classgraph/wiki

    • Constructor Detail

      • ClassGraph

        public ClassGraph()
        Construct a ClassGraph instance.

    • Method Detail

      • getVersion

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

      • verbose

        public ClassGraph verbose()
        Switches on verbose logging to System.err.
        Returns:
        this (for method chaining).

      • verbose

        public ClassGraph verbose​(boolean verbose)
        Switches on verbose logging to System.err if verbose is true.
        Parameters:
        verbose - if true, enable verbose logging.
        Returns:
        this (for method chaining).

      • enableClassInfo

        public ClassGraph enableClassInfo()
        Enables the scanning of classfiles, producing ClassInfo objects in the ScanResult.
        Returns:
        this (for method chaining).

      • ignoreClassVisibility

        public ClassGraph ignoreClassVisibility()
        Causes class visibility to be ignored, enabling private, package-private and protected classes to be scanned. By default, only public classes are scanned. (Automatically calls enableClassInfo().)
        Returns:
        this (for method chaining).

      • enableMethodInfo

        public ClassGraph enableMethodInfo()
        Enables the saving of method info during the scan. This information can be obtained using ClassInfo.getMethodInfo() etc. By default, method info is not scanned. (Automatically calls enableClassInfo().)
        Returns:
        this (for method chaining).

      • ignoreMethodVisibility

        public ClassGraph ignoreMethodVisibility()
        Causes method visibility to be ignored, enabling private, package-private and protected methods to be scanned. By default, only public methods are scanned. (Automatically calls enableClassInfo() and enableMethodInfo().)
        Returns:
        this (for method chaining).

      • enableFieldInfo

        public ClassGraph enableFieldInfo()
        Enables the saving of field info during the scan. This information can be obtained using ClassInfo.getFieldInfo(). By default, field info is not scanned. (Automatically calls enableClassInfo().)
        Returns:
        this (for method chaining).

      • ignoreFieldVisibility

        public ClassGraph ignoreFieldVisibility()
        Causes field visibility to be ignored, enabling private, package-private and protected fields to be scanned. By default, only public fields are scanned. (Automatically calls enableClassInfo() and enableFieldInfo().)
        Returns:
        this (for method chaining).

      • enableStaticFinalFieldConstantInitializerValues

        public ClassGraph enableStaticFinalFieldConstantInitializerValues()
        Enables the saving of static final field constant initializer values. By default, constant initializer values are not scanned. Automatically calls enableClassInfo() and enableFieldInfo().
        Returns:
        this (for method chaining).

      • disableRuntimeInvisibleAnnotations

        public ClassGraph disableRuntimeInvisibleAnnotations()
        Causes only runtime visible annotations to be scanned (causes runtime invisible annotations to be ignored). (Automatically calls enableClassInfo().)
        Returns:
        this (for method chaining).

      • disableJarScanning

        public ClassGraph disableJarScanning()
        Disables the scanning of jarfiles.
        Returns:
        this (for method chaining).

      • disableNestedJarScanning

        public ClassGraph disableNestedJarScanning()
        Disables the scanning of nested jarfiles (jarfiles within jarfiles).
        Returns:
        this (for method chaining).

      • disableDirScanning

        public ClassGraph disableDirScanning()
        Disables the scanning of directories.
        Returns:
        this (for method chaining).

      • disableModuleScanning

        public ClassGraph disableModuleScanning()
        Disables the scanning of modules.
        Returns:
        this (for method chaining).

      • enableExternalClasses

        public ClassGraph enableExternalClasses()
        Causes ClassGraph to return 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. (Automatically calls enableClassInfo().)
        Returns:
        this (for method chaining).

      • initializeLoadedClasses

        public ClassGraph initializeLoadedClasses()
        Causes classes loaded using ClassInfo.loadClass() to be are initialized after class loading (the default is to not initialize classes).
        Returns:
        this (for method chaining).

      • removeTemporaryFilesAfterScan

        public ClassGraph removeTemporaryFilesAfterScan()
        Remove temporary files, including nested jarfiles (jarfiles within jarfiles, which have to be extracted during scanning in order to be read) from their temporary directory as soon as the scan has completed. The default is for temporary files to be removed by the ScanResult finalizer, or on JVM exit.
        Returns:
        this (for method chaining).

      • overrideClasspath

        public ClassGraph overrideClasspath​(java.lang.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. Also causes modules not to be scanned.

        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 ClassGraph overrideClasspath​(java.lang.Iterable<?> overrideClasspathElements)
        Override the automatically-detected classpath with a custom path. Causes system ClassLoaders and the java.class.path system property to be ignored. Also causes modules not to be scanned.

        Works for Iterables of any 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).

      • overrideClasspath

        public ClassGraph overrideClasspath​(java.lang.Object... overrideClasspathElements)
        Override the automatically-detected classpath with a custom path. Causes system ClassLoaders and the java.class.path system property to be ignored. Also causes modules not to be scanned.

        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 ClassGraph filterClasspathElements​(ClassGraph.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 ClassGraph addClassLoader​(java.lang.ClassLoader classLoader)
        Add a ClassLoader to the list of ClassLoaders to scan.

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

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

      • overrideClassLoaders

        public ClassGraph overrideClassLoaders​(java.lang.ClassLoader... overrideClassLoaders)
        Completely override (and ignore) system ClassLoaders and the java.class.path system property. Also causes modules not to be scanned. Note that you may want to use this together with ignoreParentClassLoaders() to extract classpath URLs from only the classloaders you specified in the parameter to `overrideClassLoaders`, and not their parent classloaders.

        This call is ignored if overrideClasspath(String) is called.

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

      • ignoreParentClassLoaders

        public ClassGraph ignoreParentClassLoaders()
        Ignore parent classloaders (i.e. only obtain paths to scan from classloaders that are not the parent of another classloader).
        Returns:
        this (for method chaining).

      • addModuleLayer

        public ClassGraph addModuleLayer​(java.lang.Object moduleLayer)
        Add a ModuleLayer to the list of ModuleLayers to scan. Use this method if you define your own ModuleLayer, but the scanning code is not running within that custom ModuleLayer.

        This call is ignored if it is called before overrideModuleLayers(Object...).

        Parameters:
        moduleLayer - The additional ModuleLayer to scan. (The parameter is of type Object for backwards compatibility with JDK 7 and JDK 8, but the argument should be of type ModuleLayer.)
        Returns:
        this (for method chaining).

      • overrideModuleLayers

        public ClassGraph overrideModuleLayers​(java.lang.Object... overrideModuleLayers)
        Completely override (and ignore) the visible ModuleLayers, and instead scan the requested ModuleLayers.

        This call is ignored if overrideClasspath() is called.

        Parameters:
        overrideModuleLayers - The ModuleLayers to scan instead of the automatically-detected ModuleLayers. (The parameter is of type Object[] for backwards compatibility with JDK 7 and JDK 8, but the argument should be of type ModuleLayer[].)
        Returns:
        this (for method chaining).

      • ignoreParentModuleLayers

        public ClassGraph ignoreParentModuleLayers()
        Ignore parent module layers (i.e. only scan module layers that are not the parent of another module layer).
        Returns:
        this (for method chaining).

      • whitelistPackages

        public ClassGraph whitelistPackages​(java.lang.String... packageNames)
        Scan one or more specific packages and their sub-packages.

        N.B. Automatically calls enableClassInfo() -- call whitelistPaths(String...) instead if you only need to scan resources.

        Parameters:
        packageNames - The fully-qualified names of packages to scan (using '.' as a separator). May include a glob wildcard ('*').
        Returns:
        this (for method chaining).

      • whitelistPaths

        public ClassGraph whitelistPaths​(java.lang.String... paths)
        Scan one or more specific paths, and their sub-directories or nested paths.
        Parameters:
        paths - The paths to scan, relative to the package root of the classpath element (with '/' as a separator). May include a glob wildcard ('*').
        Returns:
        this (for method chaining).

      • whitelistPackagesNonRecursive

        public ClassGraph whitelistPackagesNonRecursive​(java.lang.String... packageNames)
        Scan one or more specific packages, without recursively scanning sub-packages unless they are themselves whitelisted.

        N.B. Automatically calls enableClassInfo() -- call whitelistPathsNonRecursive(String...) instead if you only need to scan resources.

        This may be particularly useful for scanning the package root ("") without recursively scanning everything in the jar, dir or module.

        Parameters:
        packageNames - The fully-qualified names of packages to scan (with '.' as a separator). May not include a glob wildcard ('*').
        Returns:
        this (for method chaining).

      • whitelistPathsNonRecursive

        public ClassGraph whitelistPathsNonRecursive​(java.lang.String... paths)
        Scan one or more specific paths, without recursively scanning sub-directories or nested paths unless they are themselves whitelisted.

        This may be particularly useful for scanning the package root ("") without recursively scanning everything in the jar, dir or module.

        Parameters:
        paths - The paths to scan, relative to the package root of the classpath element (with '/' as a separator). May not include a glob wildcard ('*').
        Returns:
        this (for method chaining).

      • blacklistPackages

        public ClassGraph blacklistPackages​(java.lang.String... packageNames)
        Prevent the scanning of one or more specific packages and their sub-packages.

        N.B. Automatically calls enableClassInfo() -- call blacklistPaths(String...) instead if you only need to scan resources.

        Parameters:
        packageNames - The fully-qualified names of packages to blacklist (with '.' as a separator). May include a glob wildcard ('*').
        Returns:
        this (for method chaining).

      • blacklistPaths

        public ClassGraph blacklistPaths​(java.lang.String... paths)
        Prevent the scanning of one or more specific paths and their sub-directories / nested paths.
        Parameters:
        paths - The paths to blacklist (with '/' as a separator). May include a glob wildcard ('*').
        Returns:
        this (for method chaining).

      • whitelistClasses

        public ClassGraph whitelistClasses​(java.lang.String... classNames)
        Scan one or more specific classes, without scanning other classes in the same package unless the package is itself whitelisted.

        N.B. Automatically calls enableClassInfo().

        Parameters:
        classNames - The fully-qualified names of classes to scan (using '.' as a separator). May not include a glob wildcard ('*').
        Returns:
        this (for method chaining).

      • blacklistClasses

        public ClassGraph blacklistClasses​(java.lang.String... classNames)
        Specifically blacklist one or more specific classes, preventing them from being scanned even if they are in a whitelisted package.

        N.B. Automatically calls enableClassInfo().

        Parameters:
        classNames - The fully-qualified names of classes to blacklist (using '.' as a separator). May not include a glob wildcard ('*').
        Returns:
        this (for method chaining).

      • whitelistJars

        public ClassGraph whitelistJars​(java.lang.String... jarLeafNames)
        Whitelist one or more jars. This will cause only the whitelisted jars to be scanned.
        Parameters:
        jarLeafNames - The leafnames of the jars that should be scanned (e.g. "mylib.jar"). May contain a wildcard glob ("mylib-*.jar").
        Returns:
        this (for method chaining).

      • blacklistJars

        public ClassGraph blacklistJars​(java.lang.String... jarLeafNames)
        Blacklist one or more jars, preventing them from being scanned.
        Parameters:
        jarLeafNames - The leafnames of the jars that should be scanned (e.g. "badlib.jar"). May contain a wildcard glob ("badlib-*.jar").
        Returns:
        this (for method chaining).

      • whitelistLibOrExtJars

        public ClassGraph whitelistLibOrExtJars​(java.lang.String... jarLeafNames)
        Whitelist one or more jars in a JRE/JDK "lib/" or "ext/" directory (these directories are not scanned unless enableSystemJarsAndModules() is called, by association with the JRE/JDK).
        Parameters:
        jarLeafNames - The leafnames of the lib/ext jar(s) that should be scanned (e.g. "mylib.jar"). May contain a wildcard glob ('*'). Note that if you call this method with no parameters, all JRE/JDK "lib/" or "ext/" jars will be whitelisted.
        Returns:
        this (for method chaining).

      • blacklistLibOrExtJars

        public ClassGraph blacklistLibOrExtJars​(java.lang.String... jarLeafNames)
        Blacklist one or more jars in a JRE/JDK "lib/" or "ext/" directory, preventing them from being scanned.
        Parameters:
        jarLeafNames - The leafnames of the lib/ext jar(s) that should not be scanned (e.g. "jre/lib/badlib.jar"). May contain a wildcard glob ('*'). If you call this method with no parameters, all JRE/JDK "lib/" or "ext/" jars will be blacklisted.
        Returns:
        this (for method chaining).

      • whitelistModules

        public ClassGraph whitelistModules​(java.lang.String... moduleNames)
        Whitelist one or more modules to scan.
        Parameters:
        moduleNames - The names of the modules that should be scanned. May contain a wildcard glob ('*').
        Returns:
        this (for method chaining).

      • blacklistModules

        public ClassGraph blacklistModules​(java.lang.String... moduleNames)
        Blacklist one or more modules, preventing them from being scanned.
        Parameters:
        moduleNames - The names of the modules that should not be scanned. May contain a wildcard glob ('*').
        Returns:
        this (for method chaining).

      • whitelistClasspathElementsContainingResourcePath

        public ClassGraph whitelistClasspathElementsContainingResourcePath​(java.lang.String... resourcePaths)
        Whitelist classpath elements based on resource paths. Only classpath elements that contain resources with paths matching the whitelist will be scanned.
        Parameters:
        resourcePaths - The resource paths, any of which must be present in a classpath element for the classpath element to be scanned. May contain a wildcard glob ('*').
        Returns:
        this (for method chaining).

      • blacklistClasspathElementsContainingResourcePath

        public ClassGraph blacklistClasspathElementsContainingResourcePath​(java.lang.String... resourcePaths)
        Blacklist classpath elements based on resource paths. Classpath elements that contain resources with paths matching the blacklist will not be scanned.
        Parameters:
        resourcePaths - The resource paths which cause a classpath not to be scanned if any are present in a classpath element for the classpath element. May contain a wildcard glob ('*').
        Returns:
        this (for method chaining).

      • enableRemoteJarScanning

        public ClassGraph enableRemoteJarScanning()
        Enable classpath elements to be fetched from remote http/https URLs to local temporary files and scanned. This option is disabled by default, as this may present a security vulnerability, since classes from downloaded jars can be subsequently loaded using ClassInfo.loadClass(java.lang.Class<T>, boolean).
        Returns:
        this (for method chaining).

      • enableSystemJarsAndModules

        public ClassGraph enableSystemJarsAndModules()
        Enables the scanning of system packages ("java.*", "javax.*", "javafx.*", "jdk.*", "oracle.*", "sun.*") -- these are not scanned by default for speed.

        N.B. Automatically calls enableClassInfo().

        Returns:
        this (for method chaining).

      • enableRealtimeLogging

        public ClassGraph enableRealtimeLogging()
        Enables logging by calling verbose(), and then sets the logger to "realtime logging mode", where log entries are written out immediately to stderr, rather than only after the scan has completed. Can help to identify problems where scanning is stuck in a loop, or where one scanning step is taking much longer than it should, etc.
        Returns:
        this (for method chaining).

      • scanAsync

        public void scanAsync​(java.util.concurrent.ExecutorService executorService,
                      int numParallelTasks,
                      ClassGraph.ScanResultProcessor scanResultProcessor,
                      ClassGraph.FailureHandler failureHandler)
        Asynchronously scans the classpath, calling a ClassGraph.ScanResultProcessor callback on success or a ClassGraph.FailureHandler callback on failure.
        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 ClassGraph.ScanResultProcessor callback to run on successful scan.
        failureHandler - A ClassGraph.FailureHandler callback to run on failed scan. This is passed any Throwable thrown during the scan.

      • scanAsync

        public java.util.concurrent.Future<ScanResult> scanAsync​(java.util.concurrent.ExecutorService executorService,
                                                         int numParallelTasks)
        Asynchronously scans the classpath for matching files, returning a Future<ScanResult>. You should assign the wrapped ScanResult in a try-with-resources statement, or manually close it when you are finished with it.
        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<ScanResult>, that when resolved using get() yields a new ScanResult object representing the result of the scan.

      • scan

        public ScanResult scan​(java.util.concurrent.ExecutorService executorService,
                       int numParallelTasks)
        Scans the classpath using the requested ExecutorService and the requested degree of parallelism, blocking until the scan is complete. You should assign the returned ScanResult in a try-with-resources statement, or manually close it when you are finished with it.
        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(int).)
        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 ScanResult object representing the result of the scan.
        Throws:
        ClassGraphException - if any of the worker threads throws an uncaught exception, or the scan was interrupted.

      • scan

        public ScanResult scan​(int numThreads)
        Scans the classpath with the requested number of threads, blocking until the scan is complete. You should assign the returned ScanResult in a try-with-resources statement, or manually close it when you are finished with it.
        Parameters:
        numThreads - The number of worker threads to start up.
        Returns:
        a ScanResult object representing the result of the scan.
        Throws:
        ClassGraphException - if any of the worker threads throws an uncaught exception, or the scan was interrupted.

      • scan

        public ScanResult scan()
        Scans the classpath, blocking until the scan is complete. You should assign the returned ScanResult in a try-with-resources statement, or manually close it when you are finished with it.
        Returns:
        a ScanResult object representing the result of the scan.
        Throws:
        ClassGraphException - if any of the worker threads throws an uncaught exception, or the scan was interrupted.

      • getClasspathFiles

        public java.util.List<java.io.File> getClasspathFiles()
        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 as a file or directory are not included in the returned list.
        Returns:
        a List<File> consisting of the unique directories and jarfiles on the classpath, in classpath resolution order.
        Throws:
        ClassGraphException - if any of the worker threads throws an uncaught exception, or the scan was interrupted.

      • getClasspath

        public java.lang.String getClasspath()
        Returns the list of all unique File objects representing directories or zip/jarfiles on the classpath, in classloader resolution order, in the form of a classpath path string. Classpath elements that do not exist as a file or directory are not included in the returned list. Note that the returned string contains only base files, and does not include package roots or nested jars within jars, since the path separator (':') conflicts with the URL scheme separator character (also ':') on Linux and Mac OS X. Call getClasspathURIs() to get the full URIs for classpath elements and modules.
        Returns:
        a classpath path string consisting of the unique directories and jarfiles on the classpath, in classpath resolution order.
        Throws:
        ClassGraphException - if any of the worker threads throws an uncaught exception, or the scan was interrupted.

      • getClasspathURIs

        public java.util.List<java.net.URI> getClasspathURIs()
        Returns the ordered list of all unique URI objects representing directory/jar classpath elements and modules. Classpath elements representing jarfiles or directories that do not exist are not included in the returned list.
        Returns:
        the unique classpath elements and modules, as a list of URI objects.
        Throws:
        ClassGraphException - if any of the worker threads throws an uncaught exception, or the scan was interrupted.

      • getClasspathURLs

        public java.util.List<java.net.URL> getClasspathURLs()
        Returns the ordered list of all unique URL objects representing directory/jar classpath elements and modules. Classpath elements representing jarfiles or directories that do not exist, as well as modules with unknown (null) location or with jrt: location URI scheme, are not included in the returned list.
        Returns:
        the unique classpath elements and modules, as a list of URL objects.
        Throws:
        ClassGraphException - if any of the worker threads throws an uncaught exception, or the scan was interrupted.

      • getModules

        public java.util.List<ModuleRef> getModules()
        Returns ModuleRef references for all the visible modules.
        Returns:
        a list of ModuleRef references for all the visible modules.
        Throws:
        ClassGraphException - if any of the worker threads throws an uncaught exception, or the scan was interrupted.