0
# Configuration
1

2
Flexible configuration system for setting up scanning parameters, URLs, filters, class loaders, and scanner selection. Configuration is essential for controlling what gets scanned and how the scanning process behaves.
3

4
## Capabilities
5

6
### Configuration Interface
7

8
Core configuration contract that defines all settings needed for Reflections scanning.
9

10
```java { .api }
11
/**
12
 * Configuration contract for Reflections instances
13
 */
14
interface Configuration {
15
    /** Scanner instances used for indexing metadata (defaults to SubTypes and TypesAnnotated) */
16
    Set<Scanner> getScanners();
17
    
18
    /** URLs to be scanned (required) */
19
    Set<URL> getUrls();
20
    
21
    /** Filter used to filter types to be scanned (defaults to accept all if null) */
22
    Predicate<String> getInputsFilter();
23
    
24
    /** Whether to scan URLs in parallel (defaults to true) */
25
    boolean isParallel();
26
    
27
    /** Optional class loaders for resolving types */
28
    ClassLoader[] getClassLoaders();
29
    
30
    /** Whether to expand super types after scanning for unscanned types (defaults to true) */
31
    boolean shouldExpandSuperTypes();
32
}
33
```
34

35
### ConfigurationBuilder
36

37
Builder class implementing Configuration interface for easy and flexible configuration creation.
38

39
```java { .api }
40
/**
41
 * Configuration builder for instantiating Reflections
42
 */
43
class ConfigurationBuilder implements Configuration {
44
    /** Default scanners: SubTypes and TypesAnnotated */
45
    public static final Set<Scanner> DEFAULT_SCANNERS;
46
    
47
    /** Default inputs filter: accepts all */
48
    public static final Predicate<String> DEFAULT_INPUTS_FILTER;
49
    
50
    /** Default constructor */
51
    ConfigurationBuilder();
52
    
53
    /** Build configuration from various parameter types */
54
    static ConfigurationBuilder build(Object... params);
55
}
56
```
57

58
### Package Configuration Methods
59

60
Methods for configuring which packages and URLs to scan.
61

62
```java { .api }
63
/**
64
 * Package and URL configuration methods
65
 */
66
class ConfigurationBuilder implements Configuration {
67
    /** Add URLs for package prefix with optional class loaders */
68
    ConfigurationBuilder forPackage(String pkg, ClassLoader... classLoaders);
69
    
70
    /** Add URLs for multiple package prefixes */
71
    ConfigurationBuilder forPackages(String... packages);
72
    
73
    /** Set URLs to be scanned (replaces existing) */
74
    ConfigurationBuilder setUrls(Collection<URL> urls);
75
    
76
    /** Set URLs to be scanned from array (replaces existing) */
77
    ConfigurationBuilder setUrls(URL... urls);
78
    
79
    /** Add URLs to existing set */
80
    ConfigurationBuilder addUrls(Collection<URL> urls);
81
    
82
    /** Add URLs from array to existing set */
83
    ConfigurationBuilder addUrls(URL... urls);
84
}
85
```
86

87
### Scanner Configuration Methods
88

89
Methods for configuring which scanners to use for metadata indexing.
90

91
```java { .api }
92
/**
93
 * Scanner configuration methods
94
 */
95
class ConfigurationBuilder implements Configuration {
96
    /** Set scanners to use (replaces existing) */
97
    ConfigurationBuilder setScanners(Scanner... scanners);
98
    
99
    /** Add scanners to existing set */
100
    ConfigurationBuilder addScanners(Scanner... scanners);
101
}
102
```
103

104
### Filter Configuration Methods
105

106
Methods for configuring input filtering to control which types get scanned.
107

108
```java { .api }
109
/**
110
 * Filter configuration methods
111
 */
112
class ConfigurationBuilder implements Configuration {
113
    /** Set input filter predicate */
114
    ConfigurationBuilder setInputsFilter(Predicate<String> inputsFilter);
115
    
116
    /** Set input filter predicate (alias for setInputsFilter) */
117
    ConfigurationBuilder filterInputsBy(Predicate<String> inputsFilter);
118
}
119
```
120

121
### Other Configuration Methods
122

123
Methods for configuring parallelism, class loaders, and super type expansion.
124

125
```java { .api }
126
/**
127
 * Other configuration options
128
 */
129
class ConfigurationBuilder implements Configuration {
130
    /** Set whether to scan URLs in parallel */
131
    ConfigurationBuilder setParallel(boolean parallel);
132
    
133
    /** Set class loaders for type resolution (replaces existing) */
134
    ConfigurationBuilder setClassLoaders(ClassLoader[] classLoaders);
135
    
136
    /** Add class loaders to existing array */
137
    ConfigurationBuilder addClassLoaders(ClassLoader... classLoaders);
138
    
139
    /** Set whether to expand super types after scanning */
140
    ConfigurationBuilder setExpandSuperTypes(boolean expandSuperTypes);
141
}
142
```
143

144
## Usage Examples
145

146
### Basic Package Configuration
147

148
```java
149
import org.reflections.util.ConfigurationBuilder;
150
import org.reflections.scanners.Scanners;
151

152
// Simple package configuration with defaults
153
ConfigurationBuilder config = new ConfigurationBuilder()
154
    .forPackage("com.mycompany");
155

156
// Multiple packages
157
ConfigurationBuilder config = new ConfigurationBuilder()
158
    .forPackages("com.mycompany.api", "com.mycompany.core", "com.mycompany.util");
159

160
// Package with specific class loaders
161
ConfigurationBuilder config = new ConfigurationBuilder()
162
    .forPackage("com.mycompany", MyClass.class.getClassLoader());
163
```
164

165
### Scanner Configuration
166

167
```java
168
// Use specific scanners
169
ConfigurationBuilder config = new ConfigurationBuilder()
170
    .forPackages("com.mycompany")
171
    .setScanners(Scanners.SubTypes, Scanners.TypesAnnotated, Scanners.MethodsAnnotated);
172

173
// Add additional scanners to defaults
174
ConfigurationBuilder config = new ConfigurationBuilder()
175
    .forPackages("com.mycompany")
176
    .addScanners(Scanners.FieldsAnnotated, Scanners.Resources);
177

178
// Use all available scanners
179
ConfigurationBuilder config = new ConfigurationBuilder()
180
    .forPackages("com.mycompany")
181
    .setScanners(Scanners.values());
182
```
183

184
### URL Configuration
185

186
```java
187
import org.reflections.util.ClasspathHelper;
188
import java.net.URL;
189
import java.util.Collection;
190

191
// Explicit URL configuration
192
Collection<URL> urls = ClasspathHelper.forPackage("com.mycompany");
193
ConfigurationBuilder config = new ConfigurationBuilder()
194
    .setUrls(urls)
195
    .addScanners(Scanners.SubTypes);
196

197
// Add specific URLs
198
URL jarUrl = new URL("jar:file:/path/to/my.jar!/");
199
ConfigurationBuilder config = new ConfigurationBuilder()
200
    .forPackages("com.mycompany")
201
    .addUrls(jarUrl);
202

203
// Use classpath URLs
204
ConfigurationBuilder config = new ConfigurationBuilder()
205
    .addUrls(ClasspathHelper.forJavaClassPath())
206
    .addUrls(ClasspathHelper.forClassLoader());
207
```
208

209
### Filter Configuration
210

211
```java
212
import org.reflections.util.FilterBuilder;
213

214
// Include/exclude package patterns
215
ConfigurationBuilder config = new ConfigurationBuilder()
216
    .forPackages("com.mycompany")
217
    .filterInputsBy(new FilterBuilder()
218
        .includePackage("com.mycompany")
219
        .excludePackage("com.mycompany.internal")
220
        .excludePackage("com.mycompany.test"));
221

222
// Pattern-based filtering
223
ConfigurationBuilder config = new ConfigurationBuilder()
224
    .forPackages("com.mycompany")
225
    .filterInputsBy(new FilterBuilder()
226
        .includePattern(".*Service.*")
227
        .includePattern(".*Controller.*")
228
        .excludePattern(".*Test.*"));
229

230
// Custom predicate filtering
231
ConfigurationBuilder config = new ConfigurationBuilder()
232
    .forPackages("com.mycompany")
233
    .filterInputsBy(className -> 
234
        className.contains("Service") || 
235
        className.contains("Repository"));
236
```
237

238
### Advanced Configuration
239

240
```java
241
// Complete configuration example
242
ConfigurationBuilder config = new ConfigurationBuilder()
243
    .forPackages("com.mycompany.api", "com.mycompany.core")
244
    .addUrls(ClasspathHelper.forClassLoader(Thread.currentThread().getContextClassLoader()))
245
    .setScanners(Scanners.values())
246
    .filterInputsBy(new FilterBuilder()
247
        .includePackage("com.mycompany")
248
        .excludePackage("com.mycompany.test")
249
        .excludePattern(".*\\$.*")) // exclude inner classes
250
    .setParallel(true)
251
    .setExpandSuperTypes(true)
252
    .addClassLoaders(MyClass.class.getClassLoader());
253

254
// Use with Reflections
255
Reflections reflections = new Reflections(config);
256
```
257

258
### Configuration from Various Parameters
259

260
```java
261
// ConfigurationBuilder.build() accepts various parameter types
262
ConfigurationBuilder config = ConfigurationBuilder.build(
263
    "com.mycompany",                    // package name
264
    ClasspathHelper.forPackage("com.mycompany"), // URLs
265
    new FilterBuilder().includePackage("com.mycompany"), // filter
266
    Scanners.SubTypes,                  // scanners
267
    MyClass.class.getClassLoader()      // class loader
268
);
269
```
270

271
### Performance and Parallelism Configuration
272

273
```java
274
// Optimize for performance
275
ConfigurationBuilder config = new ConfigurationBuilder()
276
    .forPackages("com.mycompany")
277
    .setParallel(true) // scan in parallel (default)
278
    .setExpandSuperTypes(false) // skip super type expansion if not needed
279
    .filterInputsBy(new FilterBuilder()
280
        .includePackage("com.mycompany")) // filter early to reduce scanning
281
    .setScanners(Scanners.SubTypes); // use minimal scanners needed
282
```
283

284
### Class Loader Configuration
285

286
```java
287
// Multiple class loaders
288
ClassLoader appClassLoader = MyApp.class.getClassLoader();
289
ClassLoader contextClassLoader = Thread.currentThread().getContextClassLoader();
290

291
ConfigurationBuilder config = new ConfigurationBuilder()
292
    .forPackages("com.mycompany")
293
    .setClassLoaders(new ClassLoader[]{appClassLoader, contextClassLoader})
294
    .addClassLoaders(ClassLoader.getSystemClassLoader());
295
```
296

297
## Configuration Best Practices
298

299
### URL Selection
300
- Use `forPackage()` or `forPackages()` for simple package-based scanning
301
- Use `ClasspathHelper` utilities for more control over URL selection
302
- Filter URLs early to avoid scanning unnecessary JARs
303

304
### Scanner Selection
305
- Use minimal set of scanners needed for your use case
306
- Default scanners (SubTypes, TypesAnnotated) are sufficient for most cases
307
- Add specific scanners (MethodsAnnotated, FieldsAnnotated, etc.) only when needed
308

309
### Filtering Strategy
310
- Always use input filters to avoid scanning system classes
311
- Include only packages you need to scan
312
- Exclude test packages, internal packages, and third-party packages when possible
313

314
### Performance Optimization
315
- Keep parallel scanning enabled (default: true)
316
- Use restrictive filters to minimize scanning scope
317
- Consider disabling super type expansion if not needed
318
- Cache and reuse Reflections instances when possible
319

320
## Types
321

322
```java { .api }
323
/**
324
 * Filter builder for creating input filters
325
 */
326
class FilterBuilder implements Predicate<String> {
327
    /** Parse include/exclude string in CSV format */
328
    static FilterBuilder parsePackages(String includeExcludeString);
329
    
330
    /** Include package prefix */
331
    FilterBuilder includePackage(String value);
332
    
333
    /** Exclude package prefix */
334
    FilterBuilder excludePackage(String value);
335
    
336
    /** Include regex pattern */
337
    FilterBuilder includePattern(String regex);
338
    
339
    /** Exclude regex pattern */
340
    FilterBuilder excludePattern(String regex);
341
    
342
    /** Add custom predicate */
343
    FilterBuilder add(Predicate<String> filter);
344
    
345
    /** Test string against filters */
346
    boolean test(String regex);
347
}
348
```