0
# Reflections
1

2
Reflections is a Java runtime metadata analysis library that enables reverse querying of the type system by scanning and indexing classpath metadata. It provides comprehensive functionality to discover subtypes, annotated types/methods/fields, method signatures, resources, and more using both modern functional query APIs and legacy backward-compatible methods.
3

4
## Package Information
5

6
- **Package Name**: org.reflections:reflections
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>org.reflections</groupId>
13
    <artifactId>reflections</artifactId>
14
    <version>0.10.2</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import org.reflections.Reflections;
22
import org.reflections.util.ConfigurationBuilder;
23
import org.reflections.util.ClasspathHelper;
24
import org.reflections.util.FilterBuilder;
25
import org.reflections.scanners.Scanners;
26
```
27

28
## Basic Usage
29

30
```java
31
import org.reflections.Reflections;
32
import org.reflections.util.ConfigurationBuilder;
33
import org.reflections.scanners.Scanners;
34
import static org.reflections.scanners.Scanners.*;
35

36
// Simple package scanning with default scanners
37
Reflections reflections = new Reflections("com.mycompany");
38

39
// Advanced configuration with all scanners
40
Reflections reflections = new Reflections(new ConfigurationBuilder()
41
    .forPackages("com.mycompany.package1", "com.mycompany.package2")
42
    .addScanners(Scanners.values()) // all available scanners
43
    .filterInputsBy(new FilterBuilder()
44
        .includePackage("com.mycompany")
45
        .excludePackage("com.mycompany.exclude")));
46

47
// Query using modern functional API
48
Set<Class<?>> subtypes = reflections.get(SubTypes.of(MyInterface.class).asClass());
49
Set<Method> methods = reflections.get(MethodsAnnotated.with(MyAnnotation.class).as(Method.class));
50
Set<String> resources = reflections.get(Resources.with(".*\\.properties"));
51

52
// Query using legacy backward-compatible API
53
Set<Class<? extends MyInterface>> legacySubtypes = reflections.getSubTypesOf(MyInterface.class);
54
Set<Class<?>> annotatedTypes = reflections.getTypesAnnotatedWith(MyAnnotation.class);
55
```
56

57
## Architecture
58

59
Reflections is built around several key components:
60

61
- **Core Reflections Class**: Main entry point providing both modern functional and legacy query APIs
62
- **Scanner System**: Pluggable scanners for different metadata types (SubTypes, TypesAnnotated, MethodsAnnotated, etc.)
63
- **Configuration System**: Flexible configuration via ConfigurationBuilder for URLs, scanners, filters, and class loaders
64
- **Storage System**: Efficient multimap-based Store for indexed metadata with serialization support
65
- **Virtual File System**: VFS abstraction handling different URL types (JAR files, directories, JBoss VFS, etc.)
66
- **Query System**: Both modern QueryFunction-based functional API and legacy backward-compatible methods
67
- **Utility Classes**: Comprehensive helpers for classpath handling, filtering, name resolution, and reflection operations
68

69
## Capabilities
70

71
### Core Scanning and Querying
72

73
Central scanning functionality for indexing classpath metadata and performing reverse queries on the type system. Supports both configuration and querying operations.
74

75
```java { .api }
76
class Reflections {
77
    Reflections(Configuration configuration);
78
    Reflections(String prefix, Scanner... scanners);
79
    <T> Set<T> get(QueryFunction<Store, T> query);
80
    static Reflections collect();
81
}
82
```
83

84
[Core Operations](./core-operations.md)
85

86
### Scanner System
87

88
Comprehensive scanning capabilities for different types of metadata including types, annotations, methods, constructors, fields, resources, and signatures.
89

90
```java { .api }
91
enum Scanners implements Scanner, QueryBuilder, NameHelper {
92
    SubTypes, TypesAnnotated, MethodsAnnotated, ConstructorsAnnotated, 
93
    FieldsAnnotated, Resources, MethodsParameter, ConstructorsParameter, 
94
    MethodsSignature, ConstructorsSignature, MethodsReturn;
95
}
96

97
interface Scanner {
98
    List<Map.Entry<String, String>> scan(ClassFile classFile);
99
    String index();
100
    boolean acceptsInput(String file);
101
}
102
```
103

104
[Scanners](./scanners.md)
105

106
### Configuration and Setup
107

108
Flexible configuration system for setting up scanning parameters, URLs, filters, class loaders, and scanner selection.
109

110
```java { .api }
111
class ConfigurationBuilder implements Configuration {
112
    static ConfigurationBuilder build(Object... params);
113
    ConfigurationBuilder forPackage(String pkg, ClassLoader... classLoaders);
114
    ConfigurationBuilder forPackages(String... packages);
115
    ConfigurationBuilder setScanners(Scanner... scanners);
116
    ConfigurationBuilder addScanners(Scanner... scanners);
117
    ConfigurationBuilder setUrls(Collection<URL> urls);
118
    ConfigurationBuilder addUrls(Collection<URL> urls);
119
    ConfigurationBuilder setInputsFilter(Predicate<String> inputsFilter);
120
}
121
```
122

123
[Configuration](./configuration.md)
124

125
### Utility and Helper Functions
126

127
Extensive utility classes for classpath operations, filtering, name resolution, and reflection operations to support the core scanning functionality.
128

129
```java { .api }
130
abstract class ClasspathHelper {
131
    static Collection<URL> forPackage(String name, ClassLoader... classLoaders);
132
    static Collection<URL> forResource(String resourceName, ClassLoader... classLoaders);
133
    static Collection<URL> forClassLoader(ClassLoader... classLoaders);
134
    static Collection<URL> forJavaClassPath();
135
}
136

137
class FilterBuilder implements Predicate<String> {
138
    FilterBuilder includePackage(String value);
139
    FilterBuilder excludePackage(String value);
140
    FilterBuilder includePattern(String regex);
141
    FilterBuilder excludePattern(String regex);
142
}
143
```
144

145
[Utilities](./utilities.md)
146

147
### Functional Query API
148

149
Modern functional query system using QueryFunction for composable, type-safe metadata queries with filtering, mapping, and transformation capabilities.
150

151
```java { .api }
152
interface QueryFunction<C, T> extends Function<C, Set<T>>, NameHelper {
153
    Set<T> apply(C ctx);
154
    QueryFunction<C, T> filter(Predicate<? super T> predicate);
155
    <R> QueryFunction<C, R> map(Function<? super T, ? extends R> function);
156
    <R> QueryFunction<C, R> as(Class<? extends R> type, ClassLoader... loaders);
157
    QueryFunction<C, Class<?>> asClass(ClassLoader... loaders);
158
}
159

160
abstract class ReflectionUtils {
161
    static <C, T> Set<T> get(QueryFunction<C, T> function);
162
    static final UtilQueryBuilder<Class<?>, Class<?>> SuperTypes;
163
    static final UtilQueryBuilder<AnnotatedElement, Annotation> Annotations;
164
    static final UtilQueryBuilder<Class<?>, Method> Methods;
165
    static final UtilQueryBuilder<Class<?>, Constructor> Constructors;
166
    static final UtilQueryBuilder<Class<?>, Field> Fields;
167
}
168
```
169

170
[Functional Queries](./functional-queries.md)
171

172
### Legacy Compatibility API
173

174
Backward-compatible methods providing the same functionality as earlier versions of Reflections for easy migration and compatibility.
175

176
```java { .api }
177
class Reflections {
178
    <T> Set<Class<? extends T>> getSubTypesOf(Class<T> type);
179
    Set<Class<?>> getTypesAnnotatedWith(Class<? extends Annotation> annotation);
180
    Set<Method> getMethodsAnnotatedWith(Class<? extends Annotation> annotation);
181
    Set<Constructor> getConstructorsAnnotatedWith(Class<? extends Annotation> annotation);
182
    Set<Field> getFieldsAnnotatedWith(Class<? extends Annotation> annotation);
183
    Set<String> getResources(String pattern);
184
}
185
```
186

187
[Legacy API](./legacy-api.md)
188

189
### Serialization and Persistence
190

191
Serialization capabilities for saving and loading scanned metadata in multiple formats including XML, JSON, and Java code generation.
192

193
```java { .api }
194
interface Serializer {
195
    Reflections read(InputStream inputStream);
196
    File save(Reflections reflections, String filename);
197
}
198

199
class XmlSerializer implements Serializer;
200
class JsonSerializer implements Serializer;
201
class JavaCodeSerializer implements Serializer;
202

203
class Reflections {
204
    File save(String filename);
205
    File save(String filename, Serializer serializer);
206
    static Reflections collect();
207
    static Reflections collect(String packagePrefix, Predicate<String> resourceNameFilter);
208
}
209
```
210

211
[Serialization](./serialization.md)
212

213
## Types
214

215
```java { .api }
216
interface Configuration {
217
    Set<Scanner> getScanners();
218
    Set<URL> getUrls();
219
    Predicate<String> getInputsFilter();
220
    boolean isParallel();
221
    ClassLoader[] getClassLoaders();
222
    boolean shouldExpandSuperTypes();
223
}
224

225
class Store extends HashMap<String, Map<String, Set<String>>> {
226
    Store();
227
    Store(Map<String, Map<String, Set<String>>> storeMap);
228
}
229

230
class ReflectionsException extends RuntimeException {
231
    ReflectionsException(String message);
232
    ReflectionsException(String message, Throwable cause);
233
    ReflectionsException(Throwable cause);
234
}
235

236
interface QueryBuilder extends NameHelper {
237
    String index();
238
    QueryFunction<Store, String> get(String key);
239
    QueryFunction<Store, String> get(AnnotatedElement element);
240
    QueryFunction<Store, String> get(Collection<String> keys);
241
    QueryFunction<Store, String> getAll(Collection<String> keys);
242
    QueryFunction<Store, String> of(Collection<String> keys);
243
    QueryFunction<Store, String> of(String key);
244
    QueryFunction<Store, String> of(AnnotatedElement... elements);
245
}
246

247
interface NameHelper {
248
    String toName(AnnotatedElement element);
249
    String toName(Class<?> type);
250
    String toName(Constructor<?> constructor);
251
    String toName(Method method);
252
    String toName(Field field);
253
    Collection<String> toNames(Collection<? extends AnnotatedElement> elements);
254
    <T> T forName(String name, Class<T> resultType, ClassLoader... loaders);
255
    Class<?> forClass(String typeName, ClassLoader... loaders);
256
    Member forMember(String descriptor, ClassLoader... loaders);
257
    Method forMethod(String descriptor, ClassLoader... loaders);
258
    Constructor<?> forConstructor(String descriptor, ClassLoader... loaders);
259
    Field forField(String descriptor, ClassLoader... loaders);
260
}
261
```