Package io.github.lukehutch.fastclasspathscanner.scanner

Class ScanResult

  • public class ScanResult
extends Object
    The result of a scan.

    • Method Detail

      • getClassLoadersForClass

        public ClassLoader[] getClassLoadersForClass​(String className)
        Find the classloader(s) for the named class. Typically there will only be one ClassLoader returned. However, if more than one is returned, they should be called in turn until one is able to load the class.
        Parameters:
        className - The class name.
        Returns:
        The classloader(s) for the named class.

      • getMatchProcessorExceptions

        public List<Throwable> getMatchProcessorExceptions()
        Return the exceptions and errors thrown during classloading and/or while calling MatchProcessors on loaded classes.
        Returns:
        A list of Throwables thrown while MatchProcessors were running.

      • getUniqueClasspathElements

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

      • 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.
        Returns:
        a the unique directories and jarfiles on the classpath, in classpath resolution order, as a path string.

      • getUniqueClasspathElementURLs

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

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

      • getClassNameToClassInfo

        public Map<String,ClassInfo> getClassNameToClassInfo()
        Get a map from class name to ClassInfo object for all whitelisted classes found during the scan. You can get the info for a specific class directly from this map, or the values() of this map may be filtered using Java 8 stream processing, see here:

        https://github.com/lukehutch/fast-classpath-scanner/wiki/1.-Usage#mechanism-3

        Returns:
        A map from class name to ClassInfo object for the class.

      • getNamesOfAllClasses

        public List<String> getNamesOfAllClasses()
        Get the names of all classes, interfaces and annotations found during the scan.
        Returns:
        The sorted list of the names of all whitelisted classes found during the scan, or the empty list if none.

      • getNamesOfAllStandardClasses

        public List<String> getNamesOfAllStandardClasses()
        Get the names of all standard (non-interface/non-annotation) classes found during the scan.
        Returns:
        The sorted list of the names of all encountered standard classes, or the empty list if none.

      • getNamesOfSubclassesOf

        public List<String> getNamesOfSubclassesOf​(String superclassName)
        Get the names of all subclasses of the named class.
        Parameters:
        superclassName - The name of the superclass.
        Returns:
        The sorted list of the names of matching subclasses, or the empty list if none.

      • getNamesOfSubclassesOf

        public List<String> getNamesOfSubclassesOf​(Class<?> superclass)
        Get the names of classes 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).
        Returns:
        The sorted list of the names of matching subclasses, or the empty list if none.

      • getNamesOfSuperclassesOf

        public List<String> getNamesOfSuperclassesOf​(String subclassName)
        Get the names of classes on the classpath that are superclasses of the named subclass.
        Parameters:
        subclassName - The name of the subclass.
        Returns:
        The sorted list of the names of superclasses of the named subclass, or the empty list if none.

      • getNamesOfSuperclassesOf

        public List<String> getNamesOfSuperclassesOf​(Class<?> subclass)
        Get the names of classes on the classpath that are superclasses of the specified subclass.
        Parameters:
        subclass - The subclass to match (i.e. the class that needs to extend a superclass for the superclass to match).
        Returns:
        The sorted list of the names of superclasses of the subclass, or the empty list if none.

      • getNamesOfClassesWithMethodAnnotation

        public List<String> getNamesOfClassesWithMethodAnnotation​(String annotationName)
        Get the names of classes that have a method with an annotation of the named type.
        Parameters:
        annotationName - the name of the method annotation.
        Returns:
        The sorted list of the names of classes with a method that has an annotation of the named type, or the empty list if none.

      • getNamesOfClassesWithMethodAnnotation

        public List<String> getNamesOfClassesWithMethodAnnotation​(Class<?> annotation)
        Get the names of classes that have a method with an annotation of the given type.
        Parameters:
        annotation - the method annotation.
        Returns:
        The sorted list of the names of classes with a method that has an annotation of the given type, or the empty list if none.

      • getNamesOfClassesWithFieldAnnotation

        public List<String> getNamesOfClassesWithFieldAnnotation​(String annotationName)
        Get the names of classes that have a field with an annotation of the named type.
        Parameters:
        annotationName - the name of the field annotation.
        Returns:
        The sorted list of the names of classes that have a field with an annotation of the named type, or the empty list if none.

      • getNamesOfClassesWithFieldAnnotation

        public List<String> getNamesOfClassesWithFieldAnnotation​(Class<?> annotation)
        Get the names of classes that have a field with an annotation of the given type.
        Parameters:
        annotation - the field annotation.
        Returns:
        The sorted list of the names of classes that have a field with an annotaton of the given type, or the empty list if none.

      • getNamesOfAllInterfaceClasses

        public List<String> getNamesOfAllInterfaceClasses()
        Get the names of all interface classes found during the scan.
        Returns:
        The sorted list of the names of all whitelisted interfaces found during the scan, or the empty list if none.

      • getNamesOfSubinterfacesOf

        public List<String> getNamesOfSubinterfacesOf​(String interfaceName)
        Get the names of all subinterfaces of the named interface.
        Parameters:
        interfaceName - The interface name.
        Returns:
        The sorted list of the names of all subinterfaces of the named interface, or the empty list if none.

      • getNamesOfSubinterfacesOf

        public List<String> getNamesOfSubinterfacesOf​(Class<?> superInterface)
        Get the names of interfaces on the classpath that extend a given superinterface.
        Parameters:
        superInterface - The superinterface.
        Returns:
        The sorted list of the names of subinterfaces of the given superinterface, or the empty list if none.

      • getNamesOfSuperinterfacesOf

        public List<String> getNamesOfSuperinterfacesOf​(String subInterfaceName)
        Get the names of all superinterfaces of the named interface.
        Parameters:
        subInterfaceName - The subinterface name.
        Returns:
        The sorted list of the names of superinterfaces of the named subinterface, or the empty list if none.

      • getNamesOfSuperinterfacesOf

        public List<String> getNamesOfSuperinterfacesOf​(Class<?> subInterface)
        Get the names of all superinterfaces of the given subinterface.
        Parameters:
        subInterface - The subinterface.
        Returns:
        The sorted list of the names of superinterfaces of the given subinterface, or the empty list if none.

      • getNamesOfClassesImplementing

        public List<String> getNamesOfClassesImplementing​(String interfaceName)
        Get the names of all classes that implement (or have superclasses that implement) the named interface (or one of its subinterfaces).
        Parameters:
        interfaceName - The interface name.
        Returns:
        The sorted list of the names of all classes that implement the named interface, or the empty list if none.

      • getNamesOfClassesImplementing

        public List<String> getNamesOfClassesImplementing​(Class<?> implementedInterface)
        Get the names of all classes that implement (or have superclasses that implement) the given interface (or one of its subinterfaces).
        Parameters:
        implementedInterface - The interface.
        Returns:
        The sorted list of the names of all classes that implement the given interface, or the empty list if none.

      • getNamesOfClassesImplementingAllOf

        public List<String> getNamesOfClassesImplementingAllOf​(String... implementedInterfaceNames)
        Get the names of all classes that implement (or have superclasses that implement) all of the named interfaces (or their subinterfaces).
        Parameters:
        implementedInterfaceNames - The names of the interfaces.
        Returns:
        The sorted list of the names of all classes that implement all of the named interfaces, or the empty list if none.

      • getNamesOfClassesImplementingAllOf

        public List<String> getNamesOfClassesImplementingAllOf​(Class<?>... implementedInterfaces)
        Get the names of all classes that implement (or have superclasses that implement) all of the given interfaces (or their subinterfaces).
        Parameters:
        implementedInterfaces - The interfaces.
        Returns:
        The sorted list of the names of all classes that implement all of the given interfaces, or the empty list if none.

      • getNamesOfAllAnnotationClasses

        public List<String> getNamesOfAllAnnotationClasses()
        Get the names of all annotation classes found during the scan.
        Returns:
        The sorted list of the names of all annotation classes found during the scan, or the empty list if none.

      • getNamesOfClassesWithAnnotation

        public List<String> getNamesOfClassesWithAnnotation​(String annotationName)
        Get the names of non-annotation classes with the named class annotation or meta-annotation.
        Parameters:
        annotationName - The name of the class annotation or meta-annotation.
        Returns:
        The sorted list of the names of all non-annotation classes that were found with the named class annotation during the scan, or the empty list if none.

      • getNamesOfClassesWithAnnotation

        public List<String> getNamesOfClassesWithAnnotation​(Class<?> annotation)
        Get the names of non-annotation classes with the given class annotation or meta-annotation.
        Parameters:
        annotation - The class annotation or meta-annotation to match.
        Returns:
        The sorted list of the names of all non-annotation classes that were found with the given class annotation during the scan, or the empty list if none.

      • getNamesOfClassesWithAnnotationsAllOf

        public List<String> getNamesOfClassesWithAnnotationsAllOf​(String... annotationNames)
        Get the names of classes that have all of the named annotations.
        Parameters:
        annotationNames - The class annotation names.
        Returns:
        The sorted list of the names of classes that have all of the named class annotations, or the empty list if none.

      • getNamesOfClassesWithAnnotationsAllOf

        public List<String> getNamesOfClassesWithAnnotationsAllOf​(Class<?>... annotations)
        Get the names of classes that have all of the given annotations.
        Parameters:
        annotations - The class annotations.
        Returns:
        The sorted list of the names of classes that have all of the given class annotations, or the empty list if none.

      • getNamesOfClassesWithAnnotationsAnyOf

        public List<String> getNamesOfClassesWithAnnotationsAnyOf​(String... annotationNames)
        Get the names of classes that have any of the named annotations.
        Parameters:
        annotationNames - The annotation names.
        Returns:
        The sorted list of the names of classes that have any of the named class annotations, or the empty list if none.

      • getNamesOfClassesWithAnnotationsAnyOf

        public List<String> getNamesOfClassesWithAnnotationsAnyOf​(Class<?>... annotations)
        Get the names of classes that have any of the given annotations.
        Parameters:
        annotations - The annotations.
        Returns:
        The sorted list of the names of classes that have any of the given class annotations, or the empty list if none.

      • getNamesOfAnnotationsOnClass

        public List<String> getNamesOfAnnotationsOnClass​(String className)
        Get the names of all annotations and meta-annotations on the named class.
        Parameters:
        className - The class name.
        Returns:
        The sorted list of the names of annotations and meta-annotations on the named class, or the empty list if none.

      • getNamesOfAnnotationsOnClass

        public List<String> getNamesOfAnnotationsOnClass​(Class<?> klass)
        Get the names of all annotations and meta-annotations on the given class.
        Parameters:
        klass - The class.
        Returns:
        The sorted list of the names of annotations and meta-annotations on the given class, or the empty list if none.

      • getNamesOfAnnotationsWithMetaAnnotation

        public List<String> getNamesOfAnnotationsWithMetaAnnotation​(String metaAnnotationName)
        Return the names of all annotations that have the named meta-annotation.
        Parameters:
        metaAnnotationName - The name of the meta-annotation.
        Returns:
        The sorted list of the names of annotations that have the named meta-annotation, or the empty list if none.

      • getNamesOfAnnotationsWithMetaAnnotation

        public List<String> getNamesOfAnnotationsWithMetaAnnotation​(Class<?> metaAnnotation)
        Return the names of all annotations that have the named meta-annotation.
        Parameters:
        metaAnnotation - The meta-annotation.
        Returns:
        The sorted list of the names of annotations that have the given meta-annotation, or the empty list if none.

      • generateClassGraphDotFile

        public String generateClassGraphDotFile​(float sizeX,
                                        float sizeY,
                                        boolean showFields,
                                        boolean showMethods)
        Generate a .dot file which can be fed into GraphViz for layout and visualization of the class graph. The sizeX and sizeY parameters are the image output size to use (in inches) when GraphViz is asked to render the .dot file.

        Note that if you call this with showFields or showMethods set to false, but with method and/or field info enabled during scanning, then arrows will still be added between classes even if the field or method that created that dependency is not shown.

        Parameters:
        sizeX - The GraphViz layout width in inches.
        sizeY - The GraphViz layout width in inches.
        showFields - If true, show fields within class nodes in the graph. To show field info, FastClasspathScanner.enableFieldInfo() should be called before scanning. You may also want to call FastClasspathScanner.ignoreFieldVisibility() before scanning, to show non-public fields.
        showMethods - If true, show methods within class nodes in the graph. To show method info, FastClasspathScanner.enableMethodInfo() should be called before scanning. You may also want to call FastClasspathScanner.ignoreMethodVisibility() before scanning, to show non-public methods.
        Returns:
        the GraphViz file contents.

      • classNamesToClassRefs

        public List<Class<?>> classNamesToClassRefs​(List<String> classNames,
                                            boolean ignoreExceptions)
                                     throws IllegalArgumentException
        Produce a list of Class references given a list of class names. If ignoreExceptions is true, and any classes 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:
        classNames - The list of names of classes to load.
        ignoreExceptions - If true, exceptions are ignored during classloading, otherwise IllegalArgumentException is thrown if a class could not be loaded.
        Returns:
        a list of references to the loaded classes.
        Throws:
        IllegalArgumentException - if ignoreExceptions is false, IllegalArgumentException is thrown if there were problems loading or initializing the classes. (Note that class initialization on load is disabled by default, you can enable it with FastClasspathScanner#initializeLoadedClasses(true) .) Otherwise exceptions are suppressed, and classes are not added to the resulting list if loading them exhibits any of these problems.

      • classNamesToClassRefs

        public <T> List<Class<T>> classNamesToClassRefs​(List<String> classNames,
                                                Class<T> commonClassType,
                                                boolean ignoreExceptions)
                                         throws IllegalArgumentException
        Produce a list of Class references, given a list of names of classes extending a common superclass or implementing a common interface. If ignoreExceptions is true, and any classes 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:
        classNames - The list of names of classes to load.
        commonClassType - The common superclass of, or interface implemented by, the named classes.
        ignoreExceptions - If true, exceptions are ignored during classloading, otherwise IllegalArgumentException is thrown if a class could not be loaded.
        Returns:
        a list of references to the loaded classes.
        Throws:
        IllegalArgumentException - if ignoreExceptions is false, IllegalArgumentException is thrown if there were problems loading the classes, initializing the classes, or casting them to the requested type. (Note that class initialization on load is disabled by default, you can enable it with FastClasspathScanner#initializeLoadedClasses(true) .) Otherwise exceptions are suppressed, and classes are not added to the resulting list if loading them exhibits any of these problems.

      • classNamesToClassRefs

        public List<Class<?>> classNamesToClassRefs​(List<String> classNames)
                                     throws IllegalArgumentException
        Produce a list of Class references given a list of class names. If any classes cannot be loaded (due to classloading error, or due to an exception being thrown in the class initialization block), IllegalArgumentException will be thrown.
        Parameters:
        classNames - The list of names of classes to load.
        Returns:
        a list of references to the loaded classes.
        Throws:
        IllegalArgumentException - if there were problems loading or initializing the classes. (Note that class initialization on load is disabled by default, you can enable it with FastClasspathScanner#initializeLoadedClasses(true) .)

      • classNamesToClassRefs

        public <T> List<Class<T>> classNamesToClassRefs​(List<String> classNames,
                                                Class<T> commonClassType)
                                         throws IllegalArgumentException
        Produce a list of Class references, given a list of names of classes extending a common superclass or implementing a common interface. If any classes cannot be loaded (due to classloading error, or due to an exception being thrown in the class initialization block), IllegalArgumentException will be thrown.
        Parameters:
        classNames - The list of names of classes to load.
        commonClassType - The common superclass of, or interface implemented by, the named classes.
        Returns:
        a list of references to the loaded classes.
        Throws:
        IllegalArgumentException - if there were problems loading the classes, initializing the classes, or casting them to the requested type. (Note that class initialization on load is disabled by default, you can enable it with FastClasspathScanner#initializeLoadedClasses(true) .)

      • classNameToClassRef

        public Class<?> classNameToClassRef​(String className,
                                    boolean ignoreExceptions)
                             throws IllegalArgumentException
        Produce Class reference 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 names of the class to load.
        ignoreExceptions - 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:
        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 FastClasspathScanner#initializeLoadedClasses(true) .) Otherwise exceptions are suppressed, and null is returned if any of these problems occurs.

      • classNameToClassRef

        public <T> Class<T> classNameToClassRef​(String className,
                                        Class<T> classType,
                                        boolean ignoreExceptions)
                                 throws IllegalArgumentException
        Produce Class reference 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 names of the class to load.
        classType - The class type to cast the result to.
        ignoreExceptions - 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:
        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 FastClasspathScanner#initializeLoadedClasses(true) .) Otherwise exceptions are suppressed, and null is returned if any of these problems occurs.

      • classNameToClassRef

        public Class<?> classNameToClassRef​(String className)
                             throws IllegalArgumentException
        Produce Class reference given a class name. If 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.

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

        Parameters:
        className - The names of the classe to load.
        Returns:
        a reference to the loaded class, or null if the class could not be loaded and ignoreExceptions is true.
        Throws:
        IllegalArgumentException - if there were problems loading or initializing the class. (Note that class initialization on load is disabled by default, you can enable it with FastClasspathScanner#initializeLoadedClasses(true) .)

      • classNameToClassRef

        public <T> Class<T> classNameToClassRef​(String className,
                                        Class<T> classType)
                                 throws IllegalArgumentException
        Produce Class reference given a class name. If 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.

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

        Parameters:
        className - The names of the classe to load.
        classType - The class type to cast the result to.
        Returns:
        a reference to the loaded class, or null if the class could not be loaded and ignoreExceptions is true.
        Throws:
        IllegalArgumentException - 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 FastClasspathScanner#initializeLoadedClasses(true) .)

      • fromJSON

        public static ScanResult fromJSON​(String json)
        Deserialize a ScanResult from previously-saved JSON.

      • toJSON

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

      • toJSON

        public String toJSON()
        Serialize a ScanResult to minified (un-indented) JSON.

      • freeTempFiles

        public void freeTempFiles​(LogNode log)
        Free any temporary files created by extracting jars from within jars. By default, temporary files are removed at the end of a scan, after MatchProcessors have completed, so this typically does not need to be called. The case where it might need to be called is if the list of classpath elements has been fetched, and the classpath contained jars within jars. Without calling this method, the temporary files created by extracting the inner jars will not be removed until the temporary file system cleans them up (typically at reboot).
        Parameters:
        log - The log.