0
# Single Class API
1

2
Core functionality for verifying equals and hashCode contracts for individual classes. The `SingleTypeEqualsVerifierApi` provides extensive configuration options for field handling, warning suppression, and inheritance scenarios.
3

4
## Capabilities
5

6
### Basic Single Class Verification
7

8
Creates a verifier for testing a single class with EqualsVerifier.
9

10
```java { .api }
11
/**
12
 * Factory method for general use
13
 * @param type The class for which the equals method should be tested
14
 * @return A fluent API for EqualsVerifier
15
 */
16
public static <T> SingleTypeEqualsVerifierApi<T> forClass(Class<T> type);
17
```
18

19
**Usage Examples:**
20

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

24
// Basic verification
25
EqualsVerifier.forClass(Person.class).verify();
26

27
// With configuration
28
EqualsVerifier.forClass(Person.class)
29
    .suppress(Warning.STRICT_INHERITANCE)
30
    .verify();
31
```
32

33
### Simple Pre-configured Verification
34

35
Creates a pre-configured verifier that works with most IDE-generated equals and hashCode methods.
36

37
```java { .api }
38
/**
39
 * Creates a configuration object that is pre-configured so that it can be used with most
40
 * IDE-generated equals and hashCode methods without any further configuration
41
 * @return A reusable configuration object with a fluent API
42
 */
43
public static ConfiguredEqualsVerifier simple();
44
```
45

46
**Usage Examples:**
47

48
```java
49
// Pre-configured for IDE-generated methods
50
EqualsVerifier.simple()
51
    .forClass(Person.class)
52
    .verify();
53

54
// Automatically suppresses STRICT_INHERITANCE and NONFINAL_FIELDS warnings
55
```
56

57
### Warning Suppression
58

59
Suppresses specific warnings that may not apply to your use case.
60

61
```java { .api }
62
/**
63
 * Suppresses warnings given by EqualsVerifier
64
 * @param warnings A list of warnings to suppress in EqualsVerifier
65
 * @return this, for easy method chaining
66
 */
67
public SingleTypeEqualsVerifierApi<T> suppress(Warning... warnings);
68
```
69

70
**Usage Examples:**
71

72
```java
73
EqualsVerifier.forClass(Person.class)
74
    .suppress(Warning.STRICT_INHERITANCE, Warning.NONFINAL_FIELDS)
75
    .verify();
76
```
77

78
### Prefab Value Configuration
79

80
Adds prefabricated values for classes that EqualsVerifier cannot instantiate automatically.
81

82
```java { .api }
83
/**
84
 * Adds prefabricated values for instance fields of classes that EqualsVerifier cannot
85
 * instantiate by itself
86
 * @param otherType The class of the prefabricated values
87
 * @param red An instance of S
88
 * @param blue Another instance of S, not equal to red
89
 * @return this, for easy method chaining
90
 * @throws NullPointerException If either otherType, red, or blue is null
91
 * @throws IllegalArgumentException If red equals blue
92
 */
93
public <S> SingleTypeEqualsVerifierApi<T> withPrefabValues(
94
    Class<S> otherType, 
95
    S red, 
96
    S blue
97
);
98

99
/**
100
 * Adds prefabricated values for instance fields with a given name that EqualsVerifier 
101
 * cannot instantiate by itself
102
 * @param fieldName The name of the field that the prefabricated values are linked to
103
 * @param red An instance of S
104
 * @param blue Another instance of S, not equal to red
105
 * @return this, for easy method chaining
106
 * @throws NullPointerException If red or blue is null, or if the named field does not exist in the class
107
 * @throws IllegalArgumentException If red equals blue
108
 */
109
public <S> SingleTypeEqualsVerifierApi<T> withPrefabValuesForField(
110
    String fieldName,
111
    S red, 
112
    S blue
113
);
114
```
115

116
**Usage Examples:**
117

118
```java
119
// Global prefab values for a type
120
EqualsVerifier.forClass(Person.class)
121
    .withPrefabValues(Address.class, redAddress, blueAddress)
122
    .verify();
123

124
// Field-specific prefab values
125
EqualsVerifier.forClass(Person.class)
126
    .withPrefabValuesForField("specialField", redValue, blueValue)
127
    .verify();
128
```
129

130
### Generic Prefab Values
131

132
Adds factories for generating prefab values for generic classes.
133

134
```java { .api }
135
/**
136
 * Adds a factory to generate prefabricated values for instance fields of classes with 1 generic
137
 * type parameter that EqualsVerifier cannot instantiate by itself
138
 * @param otherType The class of the prefabricated values
139
 * @param factory A factory to generate an instance of S, given a value of its generic type parameter
140
 * @return this, for easy method chaining
141
 * @throws NullPointerException if either otherType or factory is null
142
 */
143
public <S> SingleTypeEqualsVerifierApi<T> withGenericPrefabValues(
144
    Class<S> otherType, 
145
    Func1<?, S> factory
146
);
147

148
/**
149
 * Adds a factory to generate prefabricated values for instance fields of classes with 2 generic
150
 * type parameters that EqualsVerifier cannot instantiate by itself
151
 * @param otherType The class of the prefabricated values
152
 * @param factory A factory to generate an instance of S, given values of its generic type parameters
153
 * @return this, for easy method chaining
154
 * @throws NullPointerException if either otherType or factory is null
155
 */
156
public <S> SingleTypeEqualsVerifierApi<T> withGenericPrefabValues(
157
    Class<S> otherType, 
158
    Func2<?, ?, S> factory
159
);
160
```
161

162
**Usage Examples:**
163

164
```java
165
// Factory for generic class with one type parameter
166
EqualsVerifier.forClass(Container.class)
167
    .withGenericPrefabValues(Optional.class, Optional::of)
168
    .verify();
169

170
// Factory for generic class with two type parameters  
171
EqualsVerifier.forClass(Container.class)
172
    .withGenericPrefabValues(Map.class, (k, v) -> Map.of(k, v))
173
    .verify();
174
```
175

176
### Field Management
177

178
Controls which fields are included or excluded from equals contract verification.
179

180
```java { .api }
181
/**
182
 * Signals that all given fields are not relevant for the equals contract
183
 * @param fields Fields that should be ignored
184
 * @return this, for easy method chaining
185
 */
186
public SingleTypeEqualsVerifierApi<T> withIgnoredFields(String... fields);
187

188
/**
189
 * Signals that only the given fields are relevant for the equals contract
190
 * @param fields Fields that should be included
191
 * @return this, for easy method chaining
192
 */
193
public SingleTypeEqualsVerifierApi<T> withOnlyTheseFields(String... fields);
194

195
/**
196
 * Signals that certain fields can never be null
197
 * @param fields Fields that can never be null
198
 * @return this, for easy method chaining
199
 */
200
public SingleTypeEqualsVerifierApi<T> withNonnullFields(String... fields);
201
```
202

203
**Usage Examples:**
204

205
```java
206
// Ignore specific fields
207
EqualsVerifier.forClass(Person.class)
208
    .withIgnoredFields("id", "lastModified")
209
    .verify();
210

211
// Only test specific fields
212
EqualsVerifier.forClass(Person.class)
213
    .withOnlyTheseFields("firstName", "lastName", "email")
214
    .verify();
215

216
// Mark fields as non-null
217
EqualsVerifier.forClass(Person.class)
218
    .withNonnullFields("firstName", "lastName")
219
    .verify();
220
```
221

222
### Inheritance Configuration
223

224
Configures verification behavior for inheritance hierarchies.
225

226
```java { .api }
227
/**
228
 * Signals that getClass is used in the implementation of the equals method,
229
 * instead of an instanceof check
230
 * @return this, for easy method chaining
231
 */
232
public SingleTypeEqualsVerifierApi<T> usingGetClass();
233

234
/**
235
 * Signals inheritance hierarchy with overridden equals in superclass
236
 * @return this, for easy method chaining
237
 */
238
public SingleTypeEqualsVerifierApi<T> withRedefinedSuperclass();
239

240
/**
241
 * Provides reference to subclass with overridden equals
242
 * @param subclass Reference to a subclass of T for which no instance can be equal to any instance of T
243
 * @return this, for easy method chaining
244
 */
245
public SingleTypeEqualsVerifierApi<T> withRedefinedSubclass(Class<? extends T> subclass);
246
```
247

248
**Usage Examples:**
249

250
```java
251
// For classes using getClass() instead of instanceof
252
EqualsVerifier.forClass(Person.class)
253
    .usingGetClass()
254
    .verify();
255

256
// For inheritance hierarchies
257
EqualsVerifier.forClass(Person.class)
258
    .withRedefinedSuperclass()
259
    .withRedefinedSubclass(Employee.class)
260
    .verify();
261
```
262

263
### Cached HashCode Support
264

265
Configures verification for classes with cached hashCode implementations.
266

267
```java { .api }
268
/**
269
 * Configures cached hashCode verification
270
 * @param cachedHashCodeField Name of field that caches the hashCode
271
 * @param calculateHashCodeMethod Name of method that calculates the hashCode
272
 * @param example An instance of T with cached hashCode properly initialized
273
 * @return this, for easy method chaining
274
 */
275
public SingleTypeEqualsVerifierApi<T> withCachedHashCode(
276
    String cachedHashCodeField,
277
    String calculateHashCodeMethod, 
278
    T example
279
);
280

281
/**
282
 * Configures Lombok cached hashCode verification
283
 * @param example An instance of T with cached hashCode properly initialized
284
 * @return this, for easy method chaining
285
 */
286
public SingleTypeEqualsVerifierApi<T> withLombokCachedHashCode(T example);
287
```
288

289
**Usage Examples:**
290

291
```java
292
// Custom cached hashCode
293
Person example = new Person("John", "Doe");
294
example.hashCode(); // Initialize cache
295

296
EqualsVerifier.forClass(Person.class)
297
    .withCachedHashCode("cachedHashCode", "calculateHashCode", example)
298
    .verify();
299

300
// Lombok cached hashCode
301
Person lombokExample = new Person("John", "Doe");
302
lombokExample.hashCode(); // Initialize cache
303

304
EqualsVerifier.forClass(Person.class)
305
    .withLombokCachedHashCode(lombokExample)
306
    .verify();
307
```
308

309
### Annotation Handling
310

311
Configures how annotations are handled during verification.
312

313
```java { .api }
314
/**
315
 * Ignores specified annotations during verification
316
 * @param annotations Annotation classes to ignore
317
 * @return this, for easy method chaining
318
 */
319
public SingleTypeEqualsVerifierApi<T> withIgnoredAnnotations(Class<?>... annotations);
320

321
/**
322
 * Determines how a getter name can be derived from a field name
323
 * @param converter A function that converts from field name to getter name
324
 * @return this, for easy method chaining
325
 */
326
public SingleTypeEqualsVerifierApi<T> withFieldnameToGetterConverter(
327
    Function<String, String> converter
328
);
329
```
330

331
**Usage Examples:**
332

333
```java
334
// Ignore specific annotations
335
EqualsVerifier.forClass(Person.class)
336
    .withIgnoredAnnotations(Generated.class, SuppressWarnings.class)
337
    .verify();
338

339
// Custom getter naming convention
340
EqualsVerifier.forClass(Person.class)
341
    .withFieldnameToGetterConverter(field -> "retrieve" + 
342
        field.substring(0, 1).toUpperCase() + field.substring(1))
343
    .verify();
344
```
345

346
### Execution Methods
347

348
Methods to execute the verification and get results.
349

350
```java { .api }
351
/**
352
 * Performs verification and throws AssertionError on failure
353
 * @throws AssertionError if the equals and/or hashCode contract is violated
354
 * @throws NullPointerException if required parameters are null
355
 */
356
public void verify();
357

358
/**
359
 * Performs verification and returns report with results
360
 * @return EqualsVerifierReport with verification results
361
 */
362
public EqualsVerifierReport report();
363

364
/**
365
 * Performs verification and returns report with URL control
366
 * @param showUrl Whether to include URL in error messages
367
 * @return EqualsVerifierReport with verification results
368
 */
369
public EqualsVerifierReport report(boolean showUrl);
370
```
371

372
**Usage Examples:**
373

374
```java
375
// Basic verification (throws on failure)
376
EqualsVerifier.forClass(Person.class).verify();
377

378
// Report-based verification
379
EqualsVerifierReport report = EqualsVerifier.forClass(Person.class).report();
380
if (!report.isSuccessful()) {
381
    System.err.println("Verification failed: " + report.getMessage());
382
}
383

384
// Report with URL control
385
EqualsVerifierReport reportWithoutUrl = EqualsVerifier.forClass(Person.class)
386
    .report(false);
387
```