Package io.github.classgraph

Class ScanResult

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable
    public final class ScanResult
extends java.lang.Object
implements java.io.Closeable, java.lang.AutoCloseable
    The result of a scan.

    • Method Detail

      • getClasspathFiles

        public java.util.List<java.io.File> getClasspathFiles()
        Returns the list of File objects for unique classpath elements (directories or jarfiles), in classloader resolution order.
        Returns:
        The unique classpath elements.

      • getClasspath

        public java.lang.String getClasspath()
        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.
        Returns:
        a the unique directories and jarfiles on the classpath, in classpath resolution order, as a path string.

      • getClasspathURLs

        public java.util.List<java.net.URL> getClasspathURLs()
        Returns the list of unique classpath element paths as URLs, in classloader resolution order.
        Returns:
        The unique classpath element URLs.

      • getModules

        public java.util.List<ModuleRef> getModules()
        Returns:
        ModuleRef references for all the visible modules.

      • getAllResources

        public ResourceList getAllResources()
        Returns:
        A list of all resources (including classfiles and non-classfiles) found in whitelisted packages.

      • getResourcesWithPath

        public ResourceList getResourcesWithPath​(java.lang.String resourcePath)
        Parameters:
        resourcePath - A complete resource path, relative to the classpath entry package root.
        Returns:
        A list of all resources found in whitelisted packages that have the given path, relative to the package root of the classpath element. May match several resources, up to one per classpath element.

      • getResourcesWithPathIgnoringWhitelist

        public ResourceList getResourcesWithPathIgnoringWhitelist​(java.lang.String resourcePath)
        Parameters:
        resourcePath - A complete resource path, relative to the classpath entry package root.
        Returns:
        A list of all resources found in any classpath element, whether in whitelisted packages or not, that have the given path, relative to the package root of the classpath element. (Resources will not be returned if their path is blacklisted.) May match several resources, up to one per classpath element.

      • getResourcesWithLeafName

        public ResourceList getResourcesWithLeafName​(java.lang.String leafName)
        Parameters:
        leafName - A resource leaf filename.
        Returns:
        A list of all resources found in whitelisted packages that have the requested leafname.

      • getResourcesWithExtension

        public ResourceList getResourcesWithExtension​(java.lang.String extension)
        Parameters:
        extension - A filename extension, e.g. "xml" to match all resources ending in ".xml".
        Returns:
        A list of all resources found in whitelisted packages that have the requested filename extension.

      • getResourcesMatchingPattern

        public ResourceList getResourcesMatchingPattern​(java.util.regex.Pattern pattern)
        Parameters:
        pattern - A pattern to match Resource paths with.
        Returns:
        A list of all resources found in whitelisted packages that have a path matching the requested pattern.

      • getModuleInfo

        public ModuleInfo getModuleInfo​(java.lang.String moduleName)
        Get the ModuleInfo object for the named module, or null if no module of the requested name was found during the scan.
        Parameters:
        moduleName - The module name.
        Returns:
        The ModuleInfo object for the named module, or null if the module was not found.

      • getModuleInfo

        public ModuleInfoList getModuleInfo()
        Get all modules found during the scan.
        Returns:
        A list of all modules found during the scan, or the empty list if none.

      • getPackageInfo

        public PackageInfo getPackageInfo​(java.lang.String packageName)
        Get the PackageInfo object for the named package, or null if no package of the requested name was found during the scan.
        Parameters:
        packageName - The package name.
        Returns:
        The PackageInfo object for the named package, or null if the package was not found.

      • getPackageInfo

        public PackageInfoList getPackageInfo()
        Get all packages found during the scan.
        Returns:
        A list of all packages found during the scan, or the empty list if none.

      • getClassInfo

        public ClassInfo getClassInfo​(java.lang.String className)
        Get the ClassInfo object for the named class, or null if no class of the requested name was found in a whitelisted/non-blacklisted package during the scan.
        Parameters:
        className - The class name.
        Returns:
        The ClassInfo object for the named class, or null if the class was not found.

      • getAllClasses

        public ClassInfoList getAllClasses()
        Get all classes, interfaces and annotations found during the scan.
        Returns:
        A list of all whitelisted classes found during the scan, or the empty list if none.

      • getAllStandardClasses

        public ClassInfoList getAllStandardClasses()
        Get all standard (non-interface/non-annotation) classes found during the scan.
        Returns:
        A list of all whitelisted standard classes found during the scan, or the empty list if none.

      • getSubclasses

        public ClassInfoList getSubclasses​(java.lang.String superclassName)
        Get all subclasses of the named superclass.
        Parameters:
        superclassName - The name of the superclass.
        Returns:
        A list of subclasses of the named superclass, or the empty list if none.

      • getSuperclasses

        public ClassInfoList getSuperclasses​(java.lang.String subclassName)
        Get superclasses of the named subclass.
        Parameters:
        subclassName - The name of the subclass.
        Returns:
        A list of superclasses of the named subclass, or the empty list if none.

      • getClassesWithMethodAnnotation

        public ClassInfoList getClassesWithMethodAnnotation​(java.lang.String methodAnnotationName)
        Get classes that have a method with an annotation of the named type.
        Parameters:
        methodAnnotationName - the name of the method annotation.
        Returns:
        A list of classes with a method that has an annotation of the named type, or the empty list if none.

      • getClassesWithFieldAnnotation

        public ClassInfoList getClassesWithFieldAnnotation​(java.lang.String fieldAnnotationName)
        Get classes that have a field with an annotation of the named type.
        Parameters:
        fieldAnnotationName - the name of the field annotation.
        Returns:
        A list of classes that have a field with an annotation of the named type, or the empty list if none.

      • getAllInterfaces

        public ClassInfoList getAllInterfaces()
        Get all interface classes found during the scan (not including annotations, which are also technically interfaces). See also getAllInterfacesAndAnnotations().
        Returns:
        A list of all whitelisted interfaces found during the scan, or the empty list if none.

      • getInterfaces

        public ClassInfoList getInterfaces​(java.lang.String className)
        Get all interfaces implemented by the named class or by one of its superclasses, if this is a standard class, or the superinterfaces extended by this interface, if this is an interface.
        Parameters:
        className - The class name.
        Returns:
        A list of interfaces implemented by the named class (or superinterfaces extended by the named interface), or the empty list if none.

      • getClassesImplementing

        public ClassInfoList getClassesImplementing​(java.lang.String interfaceName)
        Get all classes that implement (or have superclasses that implement) the named interface (or one of its subinterfaces).
        Parameters:
        interfaceName - The interface name.
        Returns:
        A list of all classes that implement the named interface, or the empty list if none.

      • getAllAnnotations

        public ClassInfoList getAllAnnotations()
        Get all annotation classes found during the scan. See also getAllInterfacesAndAnnotations().
        Returns:
        A list of all annotation classes found during the scan, or the empty list if none.

      • getAllInterfacesAndAnnotations

        public ClassInfoList getAllInterfacesAndAnnotations()
        Get all interface or annotation classes found during the scan. (Annotations are technically interfaces, and they can be implemented.)
        Returns:
        A list of all whitelisted interfaces found during the scan, or the empty list if none.

      • getClassesWithAnnotation

        public ClassInfoList getClassesWithAnnotation​(java.lang.String annotationName)
        Get classes with the named class annotation or meta-annotation.
        Parameters:
        annotationName - The name of the class annotation or meta-annotation.
        Returns:
        A list of all non-annotation classes that were found with the named class annotation during the scan, or the empty list if none.

      • getAnnotationsOnClass

        public ClassInfoList getAnnotationsOnClass​(java.lang.String className)
        Get annotations on the named class. This only returns the annotating classes; to read annotation parameters, call getClassInfo(String) to get the ClassInfo object for the named class, then if the ClassInfo object is non-null, call ClassInfo.getAnnotationInfo() to get detailed annotation info.
        Parameters:
        className - The name of the class.
        Returns:
        A list of all annotation classes that were found with the named class annotation during the scan, or the empty list if none.

      • classpathContentsModifiedSinceScan

        public boolean classpathContentsModifiedSinceScan()
        Determine whether the classpath contents have been modified since the last scan. Checks the timestamps of files and jarfiles encountered during the previous scan to see if they have changed. Does not perform a full scan, so cannot detect the addition of directories that newly match whitelist criteria -- you need to perform a full scan to detect those changes.
        Returns:
        true if the classpath contents have been modified since the last scan.

      • classpathContentsLastModifiedTime

        public long classpathContentsLastModifiedTime()
        Find the maximum last-modified timestamp of any whitelisted file/directory/jarfile encountered during the scan. Checks the current timestamps, so this should increase between calls if something changes in whitelisted paths. Assumes both file and system timestamps were generated from clocks whose time was accurate. Ignores timestamps greater than the system time.

        This method cannot in general tell if classpath has changed (or modules have been added or removed) if it is run twice during the same runtime session.

        Returns:
        the maximum last-modified time for whitelisted files/directories/jars encountered during the scan.

      • loadClass

        public java.lang.Class<?> loadClass​(java.lang.String className,
                                    boolean returnNullIfClassNotFound)
                             throws java.lang.IllegalArgumentException
        Load a class given a class name. If ignoreExceptions is false, and the class cannot be loaded (due to classloading error, or due to an exception being thrown in the class initialization block), an IllegalArgumentException is thrown; otherwise, the class will simply be skipped if an exception is thrown.

        Enable verbose scanning to see details of any exceptions thrown during classloading, even if ignoreExceptions is false.

        Parameters:
        className - the class to load.
        returnNullIfClassNotFound - If true, null is returned if there was an exception during classloading, otherwise IllegalArgumentException is thrown if a class could not be loaded.
        Returns:
        a reference to the loaded class, or null if the class could not be loaded and ignoreExceptions is true.
        Throws:
        java.lang.IllegalArgumentException - if ignoreExceptions is false, IllegalArgumentException is thrown if there were problems loading or initializing the class. (Note that class initialization on load is disabled by default, you can enable it with ClassGraph#initializeLoadedClasses(true) .) Otherwise exceptions are suppressed, and null is returned if any of these problems occurs.

      • loadClass

        public <T> java.lang.Class<T> loadClass​(java.lang.String className,
                                        java.lang.Class<T> superclassOrInterfaceType,
                                        boolean returnNullIfClassNotFound)
                                 throws java.lang.IllegalArgumentException
        Load a class given a class name. If ignoreExceptions is false, and the class cannot be loaded (due to classloading error, or due to an exception being thrown in the class initialization block), an IllegalArgumentException is thrown; otherwise, the class will simply be skipped if an exception is thrown.

        Enable verbose scanning to see details of any exceptions thrown during classloading, even if ignoreExceptions is false.

        Parameters:
        className - the class to load.
        superclassOrInterfaceType - The class type to cast the result to.
        returnNullIfClassNotFound - If true, null is returned if there was an exception during classloading, otherwise IllegalArgumentException is thrown if a class could not be loaded.
        Returns:
        a reference to the loaded class, or null if the class could not be loaded and ignoreExceptions is true.
        Throws:
        java.lang.IllegalArgumentException - if ignoreExceptions is false, IllegalArgumentException is thrown if there were problems loading the class, initializing the class, or casting it to the requested type. (Note that class initialization on load is disabled by default, you can enable it with ClassGraph#initializeLoadedClasses(true) .) Otherwise exceptions are suppressed, and null is returned if any of these problems occurs.

      • fromJSON

        public static ScanResult fromJSON​(java.lang.String json)
        Deserialize a ScanResult from previously-serialized JSON.
        Parameters:
        json - The JSON string for the serialized ScanResult.
        Returns:
        The deserialized ScanResult.

      • toJSON

        public java.lang.String toJSON​(int indentWidth)
        Serialize a ScanResult to JSON.
        Parameters:
        indentWidth - If greater than 0, JSON will be formatted (indented), otherwise it will be minified (un-indented).
        Returns:
        This ScanResult, serialized as a JSON string.

      • toJSON

        public java.lang.String toJSON()
        Serialize a ScanResult to minified (un-indented) JSON.
        Returns:
        This ScanResult, serialized as a JSON string.

      • close

        public void close()
        Free any temporary files created by extracting jars or files from within jars. Without calling this method, the temporary files created by extracting the inner jars will be removed in a finalizer, called by the garbage collector (or at JVM shutdown). If you don't want to experience long GC pauses, make sure you call this close method when you have finished with the ScanResult.
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable