tessl/maven-io-github-classgraph--classgraph

The uber-fast, ultra-lightweight classpath and module scanner for JVM languages.

—

Pending

Overview

Eval results

Files

Core Scanning and Configuration

Name: tessl/maven-io-github-classgraph--classgraph
Author: tessl

The ClassGraph class is the main entry point for configuring and executing classpath scans. It uses a builder pattern for fluent configuration and provides extensive filtering and customization options.

Basic Setup

import io.github.classgraph.ClassGraph;
import io.github.classgraph.ScanResult;
import java.util.concurrent.Future;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.Arrays;
import java.io.File;
import java.net.URI;
import java.net.URL;
import java.util.List;
import io.github.classgraph.ModuleRef;
import io.github.classgraph.ModulePathInfo;
import io.github.classgraph.ClassInfoList;

Simple Scanning

// Basic scan with default settings
try (ScanResult scanResult = new ClassGraph().scan()) {
    // Use scan results
}

// Scan with custom thread count
try (ScanResult scanResult = new ClassGraph().scan(8)) {
    // Uses 8 threads for scanning
}

Asynchronous Scanning

// Async scan with callback
ExecutorService executor = Executors.newFixedThreadPool(4);
Future<ScanResult> future = new ClassGraph().scanAsync(executor, 8);

// Async scan with callbacks
new ClassGraph().scanAsync(executor, 8,
    scanResult -> {
        // Process results
        System.out.println("Found " + scanResult.getAllClasses().size() + " classes");
        scanResult.close();
    },
    throwable -> {
        // Handle errors
        System.err.println("Scan failed: " + throwable.getMessage());
    }
);

Information Scanning Control

Enable specific types of information to be scanned:

ClassGraph classGraph = new ClassGraph()
    .enableAllInfo()                    // Enable all scanning features
    .enableClassInfo()                  // Scan class information (default)
    .enableFieldInfo()                  // Scan field information and annotations
    .enableMethodInfo()                 // Scan method information and annotations
    .enableAnnotationInfo()             // Scan annotation information
    .enableStaticFinalFieldConstantInitializerValues()  // Scan constant values
    .enableInterClassDependencies()     // Track class dependencies
    .enableExternalClasses();           // Include external class references

Information Scope Examples

// Minimal scan - only class names and basic hierarchy
ClassGraph minimal = new ClassGraph()
    .enableClassInfo();  // Default - just class structure

// Comprehensive scan - everything including dependencies  
ClassGraph comprehensive = new ClassGraph()
    .enableAllInfo()
    .enableInterClassDependencies()
    .enableExternalClasses();

// Annotation-focused scan
ClassGraph annotationScan = new ClassGraph()
    .enableAnnotationInfo()
    .enableMethodInfo()
    .enableFieldInfo();

Package and Class Filtering

Control which packages and classes are scanned:

ClassGraph classGraph = new ClassGraph()
    // Accept specific packages (recursive by default)
    .acceptPackages("com.example", "org.myproject")
    
    // Accept packages non-recursively
    .acceptPackagesNonRecursive("com.example.api")
    
    // Accept specific classes (supports wildcards)
    .acceptClasses("com.example.*Service", "org.myproject.*Controller")
    
    // Reject packages (takes precedence over accept)
    .rejectPackages("com.example.internal", "*.impl")
    
    // Reject specific classes
    .rejectClasses("com.example.*Test", "*Benchmark");

Path-Based Filtering

ClassGraph classGraph = new ClassGraph()
    // Accept specific paths
    .acceptPaths("META-INF/services", "config")
    
    // Accept paths non-recursively
    .acceptPathsNonRecursive("META-INF")
    
    // Reject paths
    .rejectPaths("test", "benchmark");

JAR and Module Filtering

Control which JARs and modules are scanned:

ClassGraph classGraph = new ClassGraph()
    // JAR filtering
    .acceptJars("mylib-*.jar", "commons-*.jar")
    .rejectJars("*-test.jar", "*-benchmark.jar")
    
    // Module filtering (JPMS)
    .acceptModules("java.base", "com.example.core")
    .rejectModules("jdk.compiler", "jdk.jshell")
    
    // JRE lib/ext JAR filtering
    .acceptLibOrExtJars("tools.jar")
    .rejectLibOrExtJars("*javafx*");

System Components

ClassGraph classGraph = new ClassGraph()
    // Include system JARs and modules
    .enableSystemJarsAndModules()
    
    // Include multi-release JAR versions
    .enableMultiReleaseVersions();

Classpath Override and ClassLoader Control

Override default classpath discovery:

ClassGraph classGraph = new ClassGraph()
    // Override classpath entirely
    .overrideClasspath("/path/to/classes", "/path/to/lib/*")
    
    // Override with collection
    .overrideClasspath(Arrays.asList(new File("/path/to/classes")))
    
    // Override ClassLoaders
    .overrideClassLoaders(myClassLoader, otherClassLoader)
    
    // Add additional ClassLoader
    .addClassLoader(additionalClassLoader)
    
    // Ignore parent ClassLoaders
    .ignoreParentClassLoaders();

Classpath Introspection

// Inspect classpath without scanning
ClassGraph classGraph = new ClassGraph();

List<File> classpathFiles = classGraph.getClasspathFiles();
String classpathString = classGraph.getClasspath();
List<URI> classpathURIs = classGraph.getClasspathURIs();
List<URL> classpathURLs = classGraph.getClasspathURLs();

// Module information
List<ModuleRef> modules = classGraph.getModules();
ModulePathInfo modulePathInfo = classGraph.getModulePathInfo();

Visibility and Access Control

Control which classes, fields, and methods are included based on visibility:

ClassGraph classGraph = new ClassGraph()
    // Include non-public classes
    .ignoreClassVisibility()
    
    // Include non-public fields  
    .ignoreFieldVisibility()
    
    // Include non-public methods
    .ignoreMethodVisibility();

Advanced Configuration Options

Performance and Behavior

ClassGraph classGraph = new ClassGraph()
    // Logging and debugging
    .verbose()                          // Enable verbose logging to stderr
    .verbose(true)                      // Conditional verbose logging
    
    // Class initialization
    .initializeLoadedClasses()          // Initialize classes when loaded
    
    // Temporary file management  
    .removeTemporaryFilesAfterScan()    // Clean up temp files automatically
    
    // Performance optimizations
    .enableMemoryMapping()              // Use memory mapping for better performance
    
    // Remote JAR support
    .enableRemoteJarScanning()          // Allow http/https URLs in classpath
    
    // Custom URL schemes
    .enableURLScheme("custom");         // Enable custom URL scheme support

Selective Scanning Disable

ClassGraph classGraph = new ClassGraph()
    // Disable specific scan types
    .disableJarScanning()               // Skip JAR files entirely
    .disableNestedJarScanning()         // Skip nested JARs (faster, less complete)
    .disableDirScanning()               // Skip directory scanning
    .disableModuleScanning();           // Skip module path scanning

Functional Interface Support

ClassGraph supports functional interfaces for advanced filtering:

// Custom classpath element filter
ClassGraph classGraph = new ClassGraph()
    .filterClasspathElements(classpathElementPath -> 
        !classpathElementPath.contains("test") && 
        !classpathElementPath.endsWith("-sources.jar"));

// Custom URL filter  
classGraph.filterClasspathElementsByURL(url ->
    !"file".equals(url.getProtocol()) ||
    !url.getPath().contains("/target/"));

Error Handling and Callbacks

Scan Result Processing

// Success callback interface
ClassGraph.ScanResultProcessor processor = scanResult -> {
    System.out.println("Scan completed with " + scanResult.getAllClasses().size() + " classes");
    // Process results...
    scanResult.close(); // Important: close when done
};

// Failure callback interface
ClassGraph.FailureHandler failureHandler = throwable -> {
    System.err.println("Scan failed: " + throwable.getMessage());
    throwable.printStackTrace();
};

// Use with async scanning
new ClassGraph()
    .enableAllInfo()
    .scanAsync(executor, 4, processor, failureHandler);

Comprehensive Configuration Example

// Production-ready configuration
try (ScanResult scanResult = new ClassGraph()
        // Information scope
        .enableAllInfo()
        .enableInterClassDependencies()
        
        // Package filtering
        .acceptPackages("com.mycompany", "org.myproject")
        .rejectPackages("com.mycompany.test", "com.mycompany.benchmark")
        
        // JAR filtering
        .acceptJars("myproject-*.jar", "commons-*.jar")
        .rejectJars("*-test.jar", "*-sources.jar")
        
        // Visibility
        .ignoreClassVisibility()  // Include package-private classes
        
        // Performance
        .enableMemoryMapping()
        .removeTemporaryFilesAfterScan()
        
        // Logging
        .verbose()
        
        // Execute scan with 8 threads
        .scan(8)) {
        
    // Use scan results...
    ClassInfoList allClasses = scanResult.getAllClasses();
    System.out.println("Scanned " + allClasses.size() + " classes");
}

Version and Compatibility

// Get ClassGraph version
String version = ClassGraph.getVersion();
System.out.println("Using ClassGraph version: " + version);

// Handle encapsulation for JDK 16+
ClassGraph.CIRCUMVENT_ENCAPSULATION = CircumventEncapsulationMethod.NARCISSUS;
// or
ClassGraph.CIRCUMVENT_ENCAPSULATION = CircumventEncapsulationMethod.JVM_DRIVER;

The ClassGraph configuration system provides fine-grained control over scanning behavior while maintaining simple defaults for common use cases. The builder pattern allows for readable, maintainable configuration that can be easily adjusted for different environments and requirements.

Install with Tessl CLI

npx tessl i tessl/maven-io-github-classgraph--classgraph

docs