0
# Core Scanning and Configuration
1

2
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.
3

4
## Basic Setup
5

6
```java { .api }
7
import io.github.classgraph.ClassGraph;
8
import io.github.classgraph.ScanResult;
9
import java.util.concurrent.Future;
10
import java.util.concurrent.ExecutorService;
11
import java.util.concurrent.Executors;
12
import java.util.Arrays;
13
import java.io.File;
14
import java.net.URI;
15
import java.net.URL;
16
import java.util.List;
17
import io.github.classgraph.ModuleRef;
18
import io.github.classgraph.ModulePathInfo;
19
import io.github.classgraph.ClassInfoList;
20
```
21

22
### Simple Scanning
23

24
```java { .api }
25
// Basic scan with default settings
26
try (ScanResult scanResult = new ClassGraph().scan()) {
27
    // Use scan results
28
}
29

30
// Scan with custom thread count
31
try (ScanResult scanResult = new ClassGraph().scan(8)) {
32
    // Uses 8 threads for scanning
33
}
34
```
35

36
### Asynchronous Scanning
37

38
```java { .api }
39
// Async scan with callback
40
ExecutorService executor = Executors.newFixedThreadPool(4);
41
Future<ScanResult> future = new ClassGraph().scanAsync(executor, 8);
42

43
// Async scan with callbacks
44
new ClassGraph().scanAsync(executor, 8,
45
    scanResult -> {
46
        // Process results
47
        System.out.println("Found " + scanResult.getAllClasses().size() + " classes");
48
        scanResult.close();
49
    },
50
    throwable -> {
51
        // Handle errors
52
        System.err.println("Scan failed: " + throwable.getMessage());
53
    }
54
);
55
```
56

57
## Information Scanning Control
58

59
Enable specific types of information to be scanned:
60

61
```java { .api }
62
ClassGraph classGraph = new ClassGraph()
63
    .enableAllInfo()                    // Enable all scanning features
64
    .enableClassInfo()                  // Scan class information (default)
65
    .enableFieldInfo()                  // Scan field information and annotations
66
    .enableMethodInfo()                 // Scan method information and annotations
67
    .enableAnnotationInfo()             // Scan annotation information
68
    .enableStaticFinalFieldConstantInitializerValues()  // Scan constant values
69
    .enableInterClassDependencies()     // Track class dependencies
70
    .enableExternalClasses();           // Include external class references
71
```
72

73
### Information Scope Examples
74

75
```java { .api }
76
// Minimal scan - only class names and basic hierarchy
77
ClassGraph minimal = new ClassGraph()
78
    .enableClassInfo();  // Default - just class structure
79

80
// Comprehensive scan - everything including dependencies  
81
ClassGraph comprehensive = new ClassGraph()
82
    .enableAllInfo()
83
    .enableInterClassDependencies()
84
    .enableExternalClasses();
85

86
// Annotation-focused scan
87
ClassGraph annotationScan = new ClassGraph()
88
    .enableAnnotationInfo()
89
    .enableMethodInfo()
90
    .enableFieldInfo();
91
```
92

93
## Package and Class Filtering
94

95
Control which packages and classes are scanned:
96

97
```java { .api }
98
ClassGraph classGraph = new ClassGraph()
99
    // Accept specific packages (recursive by default)
100
    .acceptPackages("com.example", "org.myproject")
101
    
102
    // Accept packages non-recursively
103
    .acceptPackagesNonRecursive("com.example.api")
104
    
105
    // Accept specific classes (supports wildcards)
106
    .acceptClasses("com.example.*Service", "org.myproject.*Controller")
107
    
108
    // Reject packages (takes precedence over accept)
109
    .rejectPackages("com.example.internal", "*.impl")
110
    
111
    // Reject specific classes
112
    .rejectClasses("com.example.*Test", "*Benchmark");
113
```
114

115
### Path-Based Filtering
116

117
```java { .api }
118
ClassGraph classGraph = new ClassGraph()
119
    // Accept specific paths
120
    .acceptPaths("META-INF/services", "config")
121
    
122
    // Accept paths non-recursively
123
    .acceptPathsNonRecursive("META-INF")
124
    
125
    // Reject paths
126
    .rejectPaths("test", "benchmark");
127
```
128

129
## JAR and Module Filtering
130

131
Control which JARs and modules are scanned:
132

133
```java { .api }
134
ClassGraph classGraph = new ClassGraph()
135
    // JAR filtering
136
    .acceptJars("mylib-*.jar", "commons-*.jar")
137
    .rejectJars("*-test.jar", "*-benchmark.jar")
138
    
139
    // Module filtering (JPMS)
140
    .acceptModules("java.base", "com.example.core")
141
    .rejectModules("jdk.compiler", "jdk.jshell")
142
    
143
    // JRE lib/ext JAR filtering
144
    .acceptLibOrExtJars("tools.jar")
145
    .rejectLibOrExtJars("*javafx*");
146
```
147

148
### System Components
149

150
```java { .api }
151
ClassGraph classGraph = new ClassGraph()
152
    // Include system JARs and modules
153
    .enableSystemJarsAndModules()
154
    
155
    // Include multi-release JAR versions
156
    .enableMultiReleaseVersions();
157
```
158

159
## Classpath Override and ClassLoader Control
160

161
Override default classpath discovery:
162

163
```java { .api }
164
ClassGraph classGraph = new ClassGraph()
165
    // Override classpath entirely
166
    .overrideClasspath("/path/to/classes", "/path/to/lib/*")
167
    
168
    // Override with collection
169
    .overrideClasspath(Arrays.asList(new File("/path/to/classes")))
170
    
171
    // Override ClassLoaders
172
    .overrideClassLoaders(myClassLoader, otherClassLoader)
173
    
174
    // Add additional ClassLoader
175
    .addClassLoader(additionalClassLoader)
176
    
177
    // Ignore parent ClassLoaders
178
    .ignoreParentClassLoaders();
179
```
180

181
### Classpath Introspection
182

183
```java { .api }
184
// Inspect classpath without scanning
185
ClassGraph classGraph = new ClassGraph();
186

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

192
// Module information
193
List<ModuleRef> modules = classGraph.getModules();
194
ModulePathInfo modulePathInfo = classGraph.getModulePathInfo();
195
```
196

197
## Visibility and Access Control
198

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

201
```java { .api }
202
ClassGraph classGraph = new ClassGraph()
203
    // Include non-public classes
204
    .ignoreClassVisibility()
205
    
206
    // Include non-public fields  
207
    .ignoreFieldVisibility()
208
    
209
    // Include non-public methods
210
    .ignoreMethodVisibility();
211
```
212

213
## Advanced Configuration Options
214

215
### Performance and Behavior
216

217
```java { .api }
218
ClassGraph classGraph = new ClassGraph()
219
    // Logging and debugging
220
    .verbose()                          // Enable verbose logging to stderr
221
    .verbose(true)                      // Conditional verbose logging
222
    
223
    // Class initialization
224
    .initializeLoadedClasses()          // Initialize classes when loaded
225
    
226
    // Temporary file management  
227
    .removeTemporaryFilesAfterScan()    // Clean up temp files automatically
228
    
229
    // Performance optimizations
230
    .enableMemoryMapping()              // Use memory mapping for better performance
231
    
232
    // Remote JAR support
233
    .enableRemoteJarScanning()          // Allow http/https URLs in classpath
234
    
235
    // Custom URL schemes
236
    .enableURLScheme("custom");         // Enable custom URL scheme support
237
```
238

239
### Selective Scanning Disable
240

241
```java { .api }
242
ClassGraph classGraph = new ClassGraph()
243
    // Disable specific scan types
244
    .disableJarScanning()               // Skip JAR files entirely
245
    .disableNestedJarScanning()         // Skip nested JARs (faster, less complete)
246
    .disableDirScanning()               // Skip directory scanning
247
    .disableModuleScanning();           // Skip module path scanning
248
```
249

250
## Functional Interface Support
251

252
ClassGraph supports functional interfaces for advanced filtering:
253

254
```java { .api }
255
// Custom classpath element filter
256
ClassGraph classGraph = new ClassGraph()
257
    .filterClasspathElements(classpathElementPath -> 
258
        !classpathElementPath.contains("test") && 
259
        !classpathElementPath.endsWith("-sources.jar"));
260

261
// Custom URL filter  
262
classGraph.filterClasspathElementsByURL(url ->
263
    !"file".equals(url.getProtocol()) ||
264
    !url.getPath().contains("/target/"));
265
```
266

267
## Error Handling and Callbacks
268

269
### Scan Result Processing
270

271
```java { .api }
272
// Success callback interface
273
ClassGraph.ScanResultProcessor processor = scanResult -> {
274
    System.out.println("Scan completed with " + scanResult.getAllClasses().size() + " classes");
275
    // Process results...
276
    scanResult.close(); // Important: close when done
277
};
278

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

285
// Use with async scanning
286
new ClassGraph()
287
    .enableAllInfo()
288
    .scanAsync(executor, 4, processor, failureHandler);
289
```
290

291
## Comprehensive Configuration Example
292

293
```java { .api }
294
// Production-ready configuration
295
try (ScanResult scanResult = new ClassGraph()
296
        // Information scope
297
        .enableAllInfo()
298
        .enableInterClassDependencies()
299
        
300
        // Package filtering
301
        .acceptPackages("com.mycompany", "org.myproject")
302
        .rejectPackages("com.mycompany.test", "com.mycompany.benchmark")
303
        
304
        // JAR filtering
305
        .acceptJars("myproject-*.jar", "commons-*.jar")
306
        .rejectJars("*-test.jar", "*-sources.jar")
307
        
308
        // Visibility
309
        .ignoreClassVisibility()  // Include package-private classes
310
        
311
        // Performance
312
        .enableMemoryMapping()
313
        .removeTemporaryFilesAfterScan()
314
        
315
        // Logging
316
        .verbose()
317
        
318
        // Execute scan with 8 threads
319
        .scan(8)) {
320
        
321
    // Use scan results...
322
    ClassInfoList allClasses = scanResult.getAllClasses();
323
    System.out.println("Scanned " + allClasses.size() + " classes");
324
}
325
```
326

327
## Version and Compatibility
328

329
```java { .api }
330
// Get ClassGraph version
331
String version = ClassGraph.getVersion();
332
System.out.println("Using ClassGraph version: " + version);
333

334
// Handle encapsulation for JDK 16+
335
ClassGraph.CIRCUMVENT_ENCAPSULATION = CircumventEncapsulationMethod.NARCISSUS;
336
// or
337
ClassGraph.CIRCUMVENT_ENCAPSULATION = CircumventEncapsulationMethod.JVM_DRIVER;
338
```
339

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