ClassGraph - Ultra-fast JVM Classpath Scanner

ClassGraph is an uber-fast parallelized classpath scanner and module scanner for Java, Scala, Kotlin and other JVM languages. It scans classfiles by parsing the classfile binary format directly rather than using reflection, making it extremely fast and capable of working without loading or initializing classes.

Package Information

• Package Name: classgraph
• Package Type: maven
• Language: Java
• Installation:

  <dependency>
      <groupId>io.github.classgraph</groupId>
      <artifactId>classgraph</artifactId>
      <version>4.8.180</version>
  </dependency>

Basic Usage

import io.github.classgraph.ClassGraph;
import io.github.classgraph.ScanResult;
import io.github.classgraph.ClassInfoList;

// Simple scan with automatic resource cleanup
try (ScanResult scanResult = new ClassGraph().scan()) {
    // Get all classes in a specific package
    ClassInfoList classes = scanResult.getPackageInfo("com.example").getClassInfo();
    
    // Find all classes with a specific annotation
    ClassInfoList annotatedClasses = scanResult.getClassesWithAnnotation("javax.persistence.Entity");
    
    // Find all subclasses of a specific class
    ClassInfoList subclasses = scanResult.getSubclasses("java.util.AbstractList");
}

Comprehensive Example

import io.github.classgraph.ClassGraph;
import io.github.classgraph.ScanResult;
import io.github.classgraph.ClassInfo;
import io.github.classgraph.ClassInfoList;
import io.github.classgraph.AnnotationInfo;
import io.github.classgraph.AnnotationParameterValue;
import java.util.List;

String pkg = "com.example";
String routeAnnotation = pkg + ".Route";

try (ScanResult scanResult = new ClassGraph()
        .verbose()                    // Enable verbose logging
        .enableAllInfo()              // Scan classes, methods, fields, annotations
        .acceptPackages(pkg)          // Limit scan to specific package
        .scan()) {                    // Perform the scan
        
    // Find classes with specific annotation and extract parameter values
    for (ClassInfo routeClassInfo : scanResult.getClassesWithAnnotation(routeAnnotation)) {
        AnnotationInfo routeAnnotationInfo = routeClassInfo.getAnnotationInfo(routeAnnotation);
        List<AnnotationParameterValue> routeParamVals = routeAnnotationInfo.getParameterValues();
        String route = (String) routeParamVals.get(0).getValue();
        System.out.println(routeClassInfo.getName() + " is annotated with route " + route);
    }
}

Core Capabilities

Classpath and Module Scanning

• Ultra-fast performance: Optimized multithreaded scanning close to I/O bandwidth limits
• Complete compatibility: Works with JDK 7+ including full JPMS (module system) support
• Direct bytecode parsing: Reads classfile format directly without class loading
• Comprehensive classpath support: Handles more classpath mechanisms than any other scanner

Class Relationship Queries

• Inheritance analysis: Find subclasses, superclasses, and complete inheritance hierarchies
• Interface implementation: Discover all classes implementing specific interfaces
• Annotation queries: Locate classes, methods, or fields with specific annotations
• Dependency mapping: Build complete dependency graphs between classes

Advanced Metadata Access

• Complete type signatures: Full generic type information including wildcards and bounds
• Method and field details: Access to modifiers, annotations, parameter info, and constant values
• Package and module info: Comprehensive module system integration
• Source file mapping: Track original source files and line numbers

Resource Management

• Resource discovery: Find and load resources by path patterns, extensions, or regex
• JAR and module support: Scan nested JARs, multi-release JARs, and JPMS modules
• Memory efficient: Lazy loading and proper resource cleanup
• Change detection: Monitor classpath changes since scan

Sub-Documentation

• Core Scanning and Configuration - ClassGraph setup, filtering, and scan execution
• Querying and Results - ScanResult API for finding classes and resources
• Class Metadata - ClassInfo, MethodInfo, FieldInfo and annotation details
• Type Signatures - Generic type system and signature parsing
• Resources and Classpath - Resource handling, classpath management, and modules

Architecture

ClassGraph is built around several key components that work together to provide comprehensive classpath scanning capabilities:

• ClassGraph: Main entry point providing fluent configuration through builder pattern
• Scanner: Core scanning engine that performs parallel classpath traversal and classfile parsing
• ScanResult: Result container providing comprehensive query API for discovered metadata
• Info Hierarchy: Rich metadata model (ClassInfo, MethodInfo, FieldInfo, AnnotationInfo, etc.)
• Type Signature System: Complete representation of Java's generic type system
• Classpath Elements: Abstraction layer handling directories, JARs, modules, and nested archives

The design emphasizes separation of concerns: configuration is isolated in ClassGraph, scanning logic in Scanner, querying in ScanResult, and metadata representation in the Info classes. This modular approach enables efficient resource management, parallel processing, and extensibility for different classpath element types.

Key Design Patterns

Builder Pattern Configuration

ClassGraph uses method chaining for fluent configuration:

ClassGraph classGraph = new ClassGraph()
    .verbose()                              // Enable logging
    .enableAllInfo()                        // Scan everything
    .acceptPackages("com.example")          // Package filtering
    .rejectClasses("com.example.Legacy*")   // Class filtering
    .enableSystemJarsAndModules()           // Include system components
    .initializeLoadedClasses();             // Auto-initialize on load

Resource Management

ScanResult implements Closeable and should be used in try-with-resources:

try (ScanResult scanResult = new ClassGraph().scan()) {
    // Use scan results here
    ClassInfoList classes = scanResult.getAllClasses();
} // Automatically closes and cleans up resources

Type-Safe Operations

Generic methods provide compile-time type safety:

import java.util.List;

// Load and cast classes safely
List<Class<? extends Service>> serviceClasses = 
    scanResult.getClassesImplementing(Service.class)
              .loadClasses(Service.class);

// Get specific annotation with type safety  
MyAnnotation annotation = classInfo.getAnnotationInfo(MyAnnotation.class)
                                  .loadClassAndInstantiate();

Key Features at a Glance

ClassGraph enables powerful metaprogramming capabilities for JVM applications by providing complete introspection of class relationships and metadata without the overhead of traditional reflection-based approaches.