0
# Scanners
1

2
Comprehensive scanning capabilities for different types of metadata including types, annotations, methods, constructors, fields, resources, and signatures. The scanner system is the foundation of Reflections' metadata indexing.
3

4
## Capabilities
5

6
### Scanner Interface
7

8
Base contract for all metadata scanners that defines how to scan class files and other resources.
9

10
```java { .api }
11
/**
12
 * Base contract for metadata scanners
13
 */
14
interface Scanner {
15
    /** Scan a class file and return key-value entries for indexing */
16
    List<Map.Entry<String, String>> scan(ClassFile classFile);
17
    
18
    /** Scan a VFS file (optional, returns null by default) */
19
    @Nullable List<Map.Entry<String, String>> scan(Vfs.File file);
20
    
21
    /** Get unique scanner index name (defaults to class simple name) */
22
    default String index();
23
    
24
    /** Check if scanner accepts a file for scanning (defaults to .class files) */
25
    default boolean acceptsInput(String file);
26
    
27
    /** Create a key-value entry */
28
    default Map.Entry<String, String> entry(String key, String value);
29
    
30
    /** Create multiple entries from keys collection to single value */
31
    default List<Map.Entry<String, String>> entries(Collection<String> keys, String value);
32
    
33
    /** Create multiple entries from single key to values collection */
34
    default List<Map.Entry<String, String>> entries(String key, Collection<String> values);
35
}
36
```
37

38
### Built-in Scanners Enum
39

40
Comprehensive set of built-in scanner implementations covering all major metadata types.
41

42
```java { .api }
43
/**
44
 * Built-in scanner implementations
45
 */
46
enum Scanners implements Scanner, QueryBuilder, NameHelper {
47
    /** Scan type superclasses and interfaces (excludes Object by default) */
48
    SubTypes,
49
    
50
    /** Scan type annotations */
51
    TypesAnnotated,
52
    
53
    /** Scan method annotations */
54
    MethodsAnnotated,
55
    
56
    /** Scan constructor annotations */
57
    ConstructorsAnnotated,
58
    
59
    /** Scan field annotations */
60
    FieldsAnnotated,
61
    
62
    /** Scan non-.class files such as xml or properties files */
63
    Resources,
64
    
65
    /** Scan method parameters types and annotations */
66
    MethodsParameter,
67
    
68
    /** Scan constructor parameters types and annotations */
69
    ConstructorsParameter,
70
    
71
    /** Scan method signatures (parameter types) */
72
    MethodsSignature,
73
    
74
    /** Scan constructor signatures (parameter types) */
75
    ConstructorsSignature,
76
    
77
    /** Scan method return types */
78
    MethodsReturn;
79
    
80
    /** Get scanner index name */
81
    String index();
82
    
83
    /** Filter scanner results by predicate */
84
    Scanners filterResultsBy(Predicate<String> filter);
85
}
86
```
87

88
### Individual Scanner Classes
89

90
Concrete scanner implementations that can be used individually or customized.
91

92
```java { .api }
93
/**
94
 * Abstract base scanner providing common functionality
95
 */
96
abstract class AbstractScanner implements Scanner {
97
    // Base implementation details
98
}
99

100
/**
101
 * Scan field annotations
102
 */
103
class FieldAnnotationsScanner extends AbstractScanner {
104
    // Implementation for scanning field annotations
105
}
106

107
/**
108
 * Scan member usage in code
109
 */
110
class MemberUsageScanner extends AbstractScanner {
111
    // Implementation for finding where methods/constructors/fields are used
112
}
113

114
/**
115
 * Scan method annotations
116
 */
117
class MethodAnnotationsScanner extends AbstractScanner {
118
    // Implementation for scanning method annotations
119
}
120

121
/**
122
 * Scan method parameter names using debug information
123
 */
124
class MethodParameterNamesScanner extends AbstractScanner {
125
    // Implementation for extracting parameter names from bytecode
126
}
127

128
/**
129
 * Scan method parameters types and annotations
130
 */
131
class MethodParameterScanner extends AbstractScanner {
132
    // Implementation for scanning method parameter information
133
}
134

135
/**
136
 * Scan non-class resources
137
 */
138
class ResourcesScanner extends AbstractScanner {
139
    // Implementation for scanning classpath resources
140
}
141

142
/**
143
 * Scan class inheritance hierarchies
144
 */
145
class SubTypesScanner extends AbstractScanner {
146
    // Implementation for scanning superclasses and interfaces
147
}
148

149
/**
150
 * Scan type annotations
151
 */
152
class TypeAnnotationsScanner extends AbstractScanner {
153
    // Implementation for scanning class/interface annotations
154
}
155

156
/**
157
 * Scan type elements (methods, fields, constructors)
158
 */
159
class TypeElementsScanner extends AbstractScanner {
160
    // Implementation for scanning all type members
161
}
162
```
163

164
## Usage Examples
165

166
### Using Built-in Scanners
167

168
```java
169
import org.reflections.Reflections;
170
import org.reflections.util.ConfigurationBuilder;
171
import static org.reflections.scanners.Scanners.*;
172

173
// Use specific scanners
174
Reflections reflections = new Reflections(new ConfigurationBuilder()
175
    .forPackages("com.mycompany")
176
    .addScanners(SubTypes, TypesAnnotated, MethodsAnnotated));
177

178
// Use all available scanners
179
Reflections reflections = new Reflections(new ConfigurationBuilder()
180
    .forPackages("com.mycompany")
181
    .addScanners(Scanners.values()));
182

183
// Filter scanner results
184
SubTypes.filterResultsBy(name -> !name.startsWith("java."));
185
```
186

187
### Scanner-Specific Queries
188

189
```java
190
// SubTypes scanner
191
Set<String> subtypeNames = reflections.get(SubTypes.of(MyInterface.class));
192
Set<Class<?>> subtypeClasses = reflections.get(SubTypes.of(MyInterface.class).asClass());
193

194
// TypesAnnotated scanner
195
Set<String> annotatedTypeNames = reflections.get(TypesAnnotated.with(MyAnnotation.class));
196
Set<Class<?>> annotatedTypes = reflections.get(TypesAnnotated.with(MyAnnotation.class).asClass());
197

198
// MethodsAnnotated scanner
199
Set<String> methodNames = reflections.get(MethodsAnnotated.with(RequestMapping.class));
200
Set<Method> methods = reflections.get(MethodsAnnotated.with(RequestMapping.class).as(Method.class));
201

202
// Resources scanner with pattern matching
203
Set<String> xmlFiles = reflections.get(Resources.with(".*\\.xml"));
204
Set<String> propFiles = reflections.get(Resources.with(".*\\.properties"));
205

206
// Method signatures
207
Set<String> methodsWithIntParam = reflections.get(MethodsSignature.with(int.class));
208
Set<Method> methods = reflections.get(MethodsSignature.with(String.class, int.class).as(Method.class));
209

210
// Method return types
211
Set<String> voidMethods = reflections.get(MethodsReturn.with(void.class));
212
Set<Method> stringReturning = reflections.get(MethodsReturn.with(String.class).as(Method.class));
213
```
214

215
### Custom Scanner Implementation
216

217
```java
218
import org.reflections.scanners.AbstractScanner;
219
import javassist.bytecode.ClassFile;
220

221
public class CustomScanner extends AbstractScanner {
222
    @Override
223
    public void scan(ClassFile classFile, List<Map.Entry<String, String>> entries) {
224
        // Custom scanning logic
225
        if (meetsCriteria(classFile)) {
226
            entries.add(entry(extractKey(classFile), classFile.getName()));
227
        }
228
    }
229
    
230
    private boolean meetsCriteria(ClassFile classFile) {
231
        // Custom criteria logic
232
        return true;
233
    }
234
    
235
    private String extractKey(ClassFile classFile) {
236
        // Extract meaningful key for indexing
237
        return classFile.getName();
238
    }
239
}
240

241
// Use custom scanner
242
Reflections reflections = new Reflections(new ConfigurationBuilder()
243
    .forPackages("com.mycompany")
244
    .addScanners(new CustomScanner()));
245
```
246

247
### Scanner Result Filtering
248

249
```java
250
// Filter SubTypes to exclude system classes
251
SubTypes.filterResultsBy(name -> !name.startsWith("java.") && !name.startsWith("javax."));
252

253
// Filter TypesAnnotated to include only specific patterns
254
TypesAnnotated.filterResultsBy(name -> name.contains("Service") || name.contains("Controller"));
255

256
// Chain filters
257
Resources.filterResultsBy(name -> name.endsWith(".xml") || name.endsWith(".yml"));
258
```
259

260
### Working with Scanner Indexes
261

262
```java
263
// Get all data for a specific scanner
264
Set<String> allSubTypes = reflections.getAll(SubTypes);
265
Set<String> allAnnotatedTypes = reflections.getAll(TypesAnnotated);
266

267
// Access raw store data by scanner index
268
Store store = reflections.getStore();
269
Map<String, Set<String>> subTypesData = store.get(SubTypes.index());
270
Map<String, Set<String>> resourcesData = store.get(Resources.index());
271
```
272

273
## Scanner Categories
274

275
### Type Hierarchy Scanners
276
- **SubTypes**: Scans superclasses and interfaces, building inheritance hierarchies
277
- **TypesAnnotated**: Scans class-level annotations including inherited annotations
278

279
### Member Annotation Scanners  
280
- **MethodsAnnotated**: Scans method-level annotations
281
- **ConstructorsAnnotated**: Scans constructor-level annotations
282
- **FieldsAnnotated**: Scans field-level annotations
283

284
### Signature and Parameter Scanners
285
- **MethodsSignature**: Scans method parameter type signatures
286
- **ConstructorsSignature**: Scans constructor parameter type signatures
287
- **MethodsParameter**: Scans method parameter types and annotations
288
- **ConstructorsParameter**: Scans constructor parameter types and annotations
289
- **MethodsReturn**: Scans method return types
290

291
### Resource and Usage Scanners
292
- **Resources**: Scans non-class files (XML, properties, etc.)
293
- **MemberUsageScanner**: Finds code locations where members are used
294
- **MethodParameterNamesScanner**: Extracts parameter names from debug info
295

296
## Types
297

298
```java { .api }
299
/**
300
 * Filter builder for scanner result filtering
301
 */
302
class FilterBuilder implements Predicate<String> {
303
    /** Include packages matching prefix */
304
    FilterBuilder includePackage(String value);
305
    
306
    /** Exclude packages matching prefix */
307
    FilterBuilder excludePackage(String value);
308
    
309
    /** Include names matching regex pattern */
310
    FilterBuilder includePattern(String regex);
311
    
312
    /** Exclude names matching regex pattern */
313
    FilterBuilder excludePattern(String regex);
314
    
315
    /** Add custom predicate filter */
316
    FilterBuilder add(Predicate<String> filter);
317
    
318
    /** Test string against all configured filters */
319
    boolean test(String input);
320
}
321
```