FastClasspathScanner is an uber-fast, ultra-lightweight classpath scanner, module scanner, and annotation processor for Java, Scala, Kotlin and other JVM languages. FastClasspathScanner can scan the classpath and module path either at build-time (e.g. to implement annotation processing for Android), or dynamically at runtime. FastClasspathScanner handles a huge number of classpath specification mechanisms found in the wild.
FastClasspathScanner reads the classfile bytecode format directly for speed, to avoid the overhead of loading classes, and to avoid the overhead and side effects of initializing classes (causing static initializer blocks to be run).
FastClasspathScanner can scan both the traditional classpath and the visible Java modules (Project Jigsaw / JDK 9+), but is also backwards and forwards compatible with JDK 7 and JDK 8. FastClasspathScanner has been carefully optimized. The project is stable and actively maintained.
What is classpath scanning? Classpath scanning involves scanning directories and jar/zip files on the classpath to find files (especially classfiles) that meet certain criteria. In many ways, classpath scanning offers the inverse of the Java class API and/or reflection: for example, the Java class API can tell you the superclass of a given class, or give you the list of annotations on a class; classpath scanning can find all subclasses of a given class, or find all classes that are annotated with a given annotation.
FastClasspathScanner is able to:
- Find classes that subclass/extend a given class.
- Find classes that implement an interface or one of its subinterfaces, or whose superclasses implement the interface or one of its subinterfaces.
- Find interfaces that extend a given interface or one of its subinterfaces.
- Find classes that have a specific class annotation or meta-annotation.
- Find classes that have methods with a given annotation.
- Find classes that have fields with a given annotation.
- Read the constant literal initializer value in a classfile's constant pool for a specified static final field.
- Determine the containment hierarchy between outer classes and inner classes (including anonymous inner classes).
- Find files (even non-classfiles) anywhere on the classpath that have a path that matches a given string or regular expression, or with a specific file extension.
- Return a list of the names of all classes, interfaces and/or annotations on the classpath (after whitelist and blacklist filtering).
- Return a list of all directories and files on the classpath (i.e. all classpath elements) as a list of File objects, with the list deduplicated and filtered to include only classpath directories and files that actually exist, saving you from the complexities of working with the classpath and classloaders.
- Detect changes to the files within the classpath since the first time the classpath was scanned.
- Serialize a class graph to JSON, and deserialize back from JSON. This can be used for build-time scanning, for example to support Android, and it can also be used for analysis of the class graph. (Example of serialized JSON, for the class graph shown below.)
- Generate a GraphViz .dot file from the class graph for visualization purposes, as shown below. A class graph visualization depicts connections between classes, interfaces, annotations and meta-annotations, and connections between classes and the types of their fields.
FastClasspathScanner is stable, feature complete, and optimized. Every effort is made to fix bugs quickly when they are reported.
See the wiki for full documentation.
JavaDoc for the core classes:
- API entry point:
- MatchProcessors:
- Classes:
- Annotations:
- Interfaces:
- Fields:
- Files:
- Scan results:
- Exceptions:
Feel free to subscribe to the FastClasspathScanner-Users email list for updates, or to ask questions.
There is also a Gitter room for discussion of FCS.
<dependency>
<groupId>io.github.lukehutch</groupId>
<artifactId>fast-classpath-scanner</artifactId>
<version>LATEST</version>
</dependency>You can get pre-built JARs (usable in JRE 1.7 or later) from Sonatype.
The following commands will build the most recent version of FastClasspathScanner from git master. The compiled package will then be in the "fast-classpath-scanner/target" directory.
git clone https://github.com/lukehutch/fast-classpath-scanner.git
cd fast-classpath-scanner
export JAVA_HOME=/usr/java/default # Or similar -- Maven needs JAVA_HOME
mvn -Dmaven.test.skip=true package
To use FastClasspathScanner as a Java module, add the jar dependency to your project using one of the above methods, then add the following to your module-info.java:
requires io.github.lukehutch.fastclasspathscanner;
The MIT License (MIT)
Copyright (c) 2016 Luke Hutchison
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.