0
# ClassGraph - Ultra-fast JVM Classpath Scanner
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: classgraph
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**:
10
```xml
11
<dependency>
12
<groupId>io.github.classgraph</groupId>
13
<artifactId>classgraph</artifactId>
14
<version>4.8.180</version>
15
</dependency>
16
```
17
18
## Basic Usage
19
20
```java { .api }
21
import io.github.classgraph.ClassGraph;
22
import io.github.classgraph.ScanResult;
23
import io.github.classgraph.ClassInfoList;
24
25
// Simple scan with automatic resource cleanup
26
try (ScanResult scanResult = new ClassGraph().scan()) {
27
// Get all classes in a specific package
28
ClassInfoList classes = scanResult.getPackageInfo("com.example").getClassInfo();
29
30
// Find all classes with a specific annotation
31
ClassInfoList annotatedClasses = scanResult.getClassesWithAnnotation("javax.persistence.Entity");
32
33
// Find all subclasses of a specific class
34
ClassInfoList subclasses = scanResult.getSubclasses("java.util.AbstractList");
35
}
36
```
37
38
### Comprehensive Example
39
40
```java { .api }
41
import io.github.classgraph.ClassGraph;
42
import io.github.classgraph.ScanResult;
43
import io.github.classgraph.ClassInfo;
44
import io.github.classgraph.ClassInfoList;
45
import io.github.classgraph.AnnotationInfo;
46
import io.github.classgraph.AnnotationParameterValue;
47
import java.util.List;
48
49
String pkg = "com.example";
50
String routeAnnotation = pkg + ".Route";
51
52
try (ScanResult scanResult = new ClassGraph()
53
.verbose() // Enable verbose logging
54
.enableAllInfo() // Scan classes, methods, fields, annotations
55
.acceptPackages(pkg) // Limit scan to specific package
56
.scan()) { // Perform the scan
57
58
// Find classes with specific annotation and extract parameter values
59
for (ClassInfo routeClassInfo : scanResult.getClassesWithAnnotation(routeAnnotation)) {
60
AnnotationInfo routeAnnotationInfo = routeClassInfo.getAnnotationInfo(routeAnnotation);
61
List<AnnotationParameterValue> routeParamVals = routeAnnotationInfo.getParameterValues();
62
String route = (String) routeParamVals.get(0).getValue();
63
System.out.println(routeClassInfo.getName() + " is annotated with route " + route);
64
}
65
}
66
```
67
68
## Core Capabilities
69
70
### Classpath and Module Scanning
71
- **Ultra-fast performance**: Optimized multithreaded scanning close to I/O bandwidth limits
72
- **Complete compatibility**: Works with JDK 7+ including full JPMS (module system) support
73
- **Direct bytecode parsing**: Reads classfile format directly without class loading
74
- **Comprehensive classpath support**: Handles more classpath mechanisms than any other scanner
75
76
### Class Relationship Queries
77
- **Inheritance analysis**: Find subclasses, superclasses, and complete inheritance hierarchies
78
- **Interface implementation**: Discover all classes implementing specific interfaces
79
- **Annotation queries**: Locate classes, methods, or fields with specific annotations
80
- **Dependency mapping**: Build complete dependency graphs between classes
81
82
### Advanced Metadata Access
83
- **Complete type signatures**: Full generic type information including wildcards and bounds
84
- **Method and field details**: Access to modifiers, annotations, parameter info, and constant values
85
- **Package and module info**: Comprehensive module system integration
86
- **Source file mapping**: Track original source files and line numbers
87
88
### Resource Management
89
- **Resource discovery**: Find and load resources by path patterns, extensions, or regex
90
- **JAR and module support**: Scan nested JARs, multi-release JARs, and JPMS modules
91
- **Memory efficient**: Lazy loading and proper resource cleanup
92
- **Change detection**: Monitor classpath changes since scan
93
94
## Sub-Documentation
95
96
- [Core Scanning and Configuration](./scanning.md) - ClassGraph setup, filtering, and scan execution
97
- [Querying and Results](./querying.md) - ScanResult API for finding classes and resources
98
- [Class Metadata](./class-info.md) - ClassInfo, MethodInfo, FieldInfo and annotation details
99
- [Type Signatures](./type-signatures.md) - Generic type system and signature parsing
100
- [Resources and Classpath](./resources.md) - Resource handling, classpath management, and modules
101
102
## Architecture
103
104
ClassGraph is built around several key components that work together to provide comprehensive classpath scanning capabilities:
105
106
- **ClassGraph**: Main entry point providing fluent configuration through builder pattern
107
- **Scanner**: Core scanning engine that performs parallel classpath traversal and classfile parsing
108
- **ScanResult**: Result container providing comprehensive query API for discovered metadata
109
- **Info Hierarchy**: Rich metadata model (ClassInfo, MethodInfo, FieldInfo, AnnotationInfo, etc.)
110
- **Type Signature System**: Complete representation of Java's generic type system
111
- **Classpath Elements**: Abstraction layer handling directories, JARs, modules, and nested archives
112
113
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.
114
115
## Key Design Patterns
116
117
### Builder Pattern Configuration
118
ClassGraph uses method chaining for fluent configuration:
119
120
```java { .api }
121
ClassGraph classGraph = new ClassGraph()
122
.verbose() // Enable logging
123
.enableAllInfo() // Scan everything
124
.acceptPackages("com.example") // Package filtering
125
.rejectClasses("com.example.Legacy*") // Class filtering
126
.enableSystemJarsAndModules() // Include system components
127
.initializeLoadedClasses(); // Auto-initialize on load
128
```
129
130
### Resource Management
131
ScanResult implements Closeable and should be used in try-with-resources:
132
133
```java { .api }
134
try (ScanResult scanResult = new ClassGraph().scan()) {
135
// Use scan results here
136
ClassInfoList classes = scanResult.getAllClasses();
137
} // Automatically closes and cleans up resources
138
```
139
140
### Type-Safe Operations
141
Generic methods provide compile-time type safety:
142
143
```java { .api }
144
import java.util.List;
145
146
// Load and cast classes safely
147
List<Class<? extends Service>> serviceClasses =
148
scanResult.getClassesImplementing(Service.class)
149
.loadClasses(Service.class);
150
151
// Get specific annotation with type safety
152
MyAnnotation annotation = classInfo.getAnnotationInfo(MyAnnotation.class)
153
.loadClassAndInstantiate();
154
```
155
156
## Key Features at a Glance
157
158
| Feature | Description |
159
|---------|-------------|
160
| **Zero Dependencies** | No external runtime dependencies required |
161
| **JDK 7+ Compatible** | Works on JDK 7-21+ with full backwards compatibility |
162
| **Module System Ready** | Complete JPMS support while remaining classpath compatible |
163
| **Thread Safe** | All operations are thread-safe and optimized for concurrent use |
164
| **Memory Efficient** | Lazy loading with automatic resource cleanup |
165
| **Comprehensive Filtering** | Package, class, JAR, and module-level filtering |
166
| **Change Detection** | Monitor and respond to classpath modifications |
167
| **Serialization Support** | JSON serialization for caching and persistence |
168
169
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.