0
# Multiple Class API
1

2
Batch verification capabilities for testing multiple classes with shared configuration. The `MultipleTypeEqualsVerifierApi` supports package scanning, filtering, and exception handling for large codebases.
3

4
## Capabilities
5

6
### Multiple Class Verification from Collections
7

8
Creates a verifier for testing multiple classes from an iterable collection.
9

10
```java { .api }
11
/**
12
 * Factory method for general use
13
 * @param classes An iterable containing the classes for which equals method should be tested
14
 * @return A fluent API for EqualsVerifier
15
 */
16
public static MultipleTypeEqualsVerifierApi forClasses(Iterable<Class<?>> classes);
17
```
18

19
**Usage Examples:**
20

21
```java
22
import nl.jqno.equalsverifier.EqualsVerifier;
23
import java.util.Arrays;
24

25
// From a list of classes
26
List<Class<?>> classes = Arrays.asList(Person.class, Address.class, Phone.class);
27
EqualsVerifier.forClasses(classes)
28
    .suppress(Warning.STRICT_INHERITANCE)
29
    .verify();
30
```
31

32
### Multiple Class Verification with Varargs
33

34
Creates a verifier for testing multiple classes using varargs syntax.
35

36
```java { .api }
37
/**
38
 * Factory method for general use
39
 * @param first A class for which the equals method should be tested
40
 * @param second Another class for which the equals method should be tested
41
 * @param more More classes for which the equals method should be tested
42
 * @return A fluent API for EqualsVerifier
43
 */
44
public static MultipleTypeEqualsVerifierApi forClasses(
45
    Class<?> first,
46
    Class<?> second,
47
    Class<?>... more
48
);
49
```
50

51
**Usage Examples:**
52

53
```java
54
// Direct class specification
55
EqualsVerifier.forClasses(Person.class, Address.class, Phone.class)
56
    .suppress(Warning.STRICT_INHERITANCE)
57
    .verify();
58

59
// With configuration
60
EqualsVerifier.forClasses(Person.class, Address.class)
61
    .withPrefabValues(ExternalDependency.class, redValue, blueValue)
62
    .verify();
63
```
64

65
### Package Scanning Verification
66

67
Scans packages to automatically discover and test classes with equals implementations.
68

69
```java { .api }
70
/**
71
 * Factory method for package scanning (non-recursive)
72
 * Note that this operation may be slow. If the test is too slow, use forClasses instead
73
 * @param packageName A package for which each class's equals should be tested
74
 * @return A fluent API for EqualsVerifier
75
 */
76
public static MultipleTypeEqualsVerifierApi forPackage(String packageName);
77

78
/**
79
 * Factory method for package scanning with recursion control
80
 * Note that this operation may be slow. If the test is too slow, use forClasses instead
81
 * @param packageName A package for which each class's equals should be tested
82
 * @param scanRecursively true to scan all sub-packages
83
 * @return A fluent API for EqualsVerifier
84
 */
85
public static MultipleTypeEqualsVerifierApi forPackage(
86
    String packageName,
87
    boolean scanRecursively
88
);
89

90
/**
91
 * Factory method for package scanning with type filtering
92
 * Note that this operation may be slow. If the test is too slow, use forClasses instead
93
 * Also note that if mustExtend is given, and it exists within packageName, it will NOT be included
94
 * @param packageName A package for which each class's equals should be tested
95
 * @param mustExtend if not null, returns only classes that extend or implement this class
96
 * @return A fluent API for EqualsVerifier
97
 */
98
public static MultipleTypeEqualsVerifierApi forPackage(
99
    String packageName,
100
    Class<?> mustExtend
101
);
102
```
103

104
**Usage Examples:**
105

106
```java
107
// Scan single package (non-recursive)
108
EqualsVerifier.forPackage("com.example.model")
109
    .suppress(Warning.STRICT_INHERITANCE)
110
    .verify();
111

112
// Scan package recursively
113
EqualsVerifier.forPackage("com.example", true)
114
    .suppress(Warning.STRICT_INHERITANCE)
115
    .verify();
116

117
// Scan package for specific type hierarchy
118
EqualsVerifier.forPackage("com.example.entities", BaseEntity.class)
119
    .suppress(Warning.SURROGATE_KEY)
120
    .verify();
121
```
122

123
### Class Filtering and Exclusion
124

125
Removes specific classes from the verification list.
126

127
```java { .api }
128
/**
129
 * Removes specific types from verification list
130
 * @param type First type to exclude
131
 * @param more Additional types to exclude
132
 * @return this, for easy method chaining
133
 */
134
public MultipleTypeEqualsVerifierApi except(Class<?> type, Class<?>... more);
135

136
/**
137
 * Removes types matching predicate from verification list
138
 * @param exclusionPredicate Predicate to determine which types to exclude
139
 * @return this, for easy method chaining
140
 */
141
public MultipleTypeEqualsVerifierApi except(Predicate<Class<?>> exclusionPredicate);
142
```
143

144
**Usage Examples:**
145

146
```java
147
// Exclude specific classes
148
EqualsVerifier.forPackage("com.example.model")
149
    .except(BaseClass.class, AbstractClass.class)
150
    .verify();
151

152
// Exclude classes matching criteria
153
EqualsVerifier.forPackage("com.example.model")
154
    .except(clazz -> clazz.isInterface() || Modifier.isAbstract(clazz.getModifiers()))
155
    .verify();
156

157
// Exclude by name pattern
158
EqualsVerifier.forPackage("com.example.model")
159
    .except(clazz -> clazz.getSimpleName().endsWith("Test"))
160
    .verify();
161
```
162

163
### Configuration Methods
164

165
All configuration methods from the base `EqualsVerifierApi` are available for batch operations.
166

167
```java { .api }
168
/**
169
 * Suppresses warnings for all classes in the batch
170
 * @param warnings A list of warnings to suppress
171
 * @return this, for easy method chaining
172
 */
173
public MultipleTypeEqualsVerifierApi suppress(Warning... warnings);
174

175
/**
176
 * Adds prefabricated values for all classes in the batch
177
 * @param otherType The class of the prefabricated values
178
 * @param red An instance of S
179
 * @param blue Another instance of S, not equal to red
180
 * @return this, for easy method chaining
181
 */
182
public <S> MultipleTypeEqualsVerifierApi withPrefabValues(
183
    Class<S> otherType, 
184
    S red, 
185
    S blue
186
);
187

188
/**
189
 * Adds a factory for generic types with 1 parameter for all classes in the batch
190
 * @param otherType The class of the prefabricated values
191
 * @param factory A factory to generate instances
192
 * @return this, for easy method chaining
193
 */
194
public <S> MultipleTypeEqualsVerifierApi withGenericPrefabValues(
195
    Class<S> otherType, 
196
    Func1<?, S> factory
197
);
198

199
/**
200
 * Adds a factory for generic types with 2 parameters for all classes in the batch
201
 * @param otherType The class of the prefabricated values
202
 * @param factory A factory to generate instances
203
 * @return this, for easy method chaining
204
 */
205
public <S> MultipleTypeEqualsVerifierApi withGenericPrefabValues(
206
    Class<S> otherType, 
207
    Func2<?, ?, S> factory
208
);
209

210
/**
211
 * Signals that getClass is used in equals implementations for all classes
212
 * @return this, for easy method chaining
213
 */
214
public MultipleTypeEqualsVerifierApi usingGetClass();
215

216
/**
217
 * Sets field name to getter name converter for all classes
218
 * @param converter A function that converts from field name to getter name
219
 * @return this, for easy method chaining
220
 */
221
public MultipleTypeEqualsVerifierApi withFieldnameToGetterConverter(
222
    Function<String, String> converter
223
);
224
```
225

226
**Usage Examples:**
227

228
```java
229
// Batch configuration
230
EqualsVerifier.forClasses(Person.class, Address.class, Phone.class)
231
    .suppress(Warning.STRICT_INHERITANCE, Warning.NONFINAL_FIELDS)
232
    .withPrefabValues(ExternalDependency.class, redValue, blueValue)
233
    .withGenericPrefabValues(Optional.class, Optional::of)
234
    .usingGetClass()
235
    .verify();
236
```
237

238
### Execution Methods
239

240
Methods to execute batch verification and get results.
241

242
```java { .api }
243
/**
244
 * Performs verification on all types and throws AssertionError on any failure
245
 */
246
public void verify();
247

248
/**
249
 * Performs verification on all types and returns list of reports
250
 * @return List of EqualsVerifierReport, one for each tested class
251
 */
252
public List<EqualsVerifierReport> report();
253
```
254

255
**Usage Examples:**
256

257
```java
258
// Basic batch verification (throws on any failure)
259
EqualsVerifier.forClasses(Person.class, Address.class, Phone.class)
260
    .suppress(Warning.STRICT_INHERITANCE)
261
    .verify();
262

263
// Report-based batch verification
264
List<EqualsVerifierReport> reports = EqualsVerifier
265
    .forClasses(Person.class, Address.class, Phone.class)
266
    .suppress(Warning.STRICT_INHERITANCE)
267
    .report();
268

269
// Process individual results
270
for (EqualsVerifierReport report : reports) {
271
    if (!report.isSuccessful()) {
272
        System.err.println("Failed for " + report.getType().getSimpleName() + 
273
                          ": " + report.getMessage());
274
    } else {
275
        System.out.println("Passed for " + report.getType().getSimpleName());
276
    }
277
}
278

279
// Count failures
280
long failureCount = reports.stream()
281
    .filter(report -> !report.isSuccessful())
282
    .count();
283
```
284

285
### Advanced Usage Patterns
286

287
**Configuration Reuse with Multiple Classes:**
288

289
```java
290
// Create base configuration
291
ConfiguredEqualsVerifier config = EqualsVerifier.configure()
292
    .suppress(Warning.STRICT_INHERITANCE, Warning.NONFINAL_FIELDS)
293
    .withPrefabValues(ExternalDependency.class, redValue, blueValue);
294

295
// Apply to different class sets
296
config.forClasses(Person.class, Address.class).verify();
297
config.forPackage("com.example.entities").verify();
298
```
299

300
**Package Scanning with Complex Filtering:**
301

302
```java
303
// Scan packages with sophisticated filtering
304
EqualsVerifier.forPackage("com.example.model", true)
305
    .except(clazz -> {
306
        // Exclude test classes
307
        if (clazz.getSimpleName().endsWith("Test")) return true;
308
        
309
        // Exclude abstract classes and interfaces
310
        if (clazz.isInterface() || Modifier.isAbstract(clazz.getModifiers())) return true;
311
        
312
        // Exclude classes without equals override
313
        try {
314
            clazz.getDeclaredMethod("equals", Object.class);
315
            return false; // Has equals method, include it
316
        } catch (NoSuchMethodException e) {
317
            return true; // No equals method, exclude it
318
        }
319
    })
320
    .suppress(Warning.INHERITED_DIRECTLY_FROM_OBJECT)
321
    .verify();
322
```
323

324
**Conditional Verification:**
325

326
```java
327
// Verify different class sets based on environment
328
List<Class<?>> entityClasses = Arrays.asList(User.class, Order.class, Product.class);
329
MultipleTypeEqualsVerifierApi verifier = EqualsVerifier.forClasses(entityClasses)
330
    .suppress(Warning.STRICT_INHERITANCE);
331

332
if (isJpaEnvironment()) {
333
    verifier.suppress(Warning.SURROGATE_KEY);
334
}
335

336
verifier.verify();
337
```