Package nl.jqno.equalsverifier
Class EqualsVerifierApi<T>
- java.lang.Object
-
- nl.jqno.equalsverifier.EqualsVerifierApi<T>
-
- Type Parameters:
T
- The class under test.
public class EqualsVerifierApi<T> extends java.lang.Object
Helps to construct anEqualsVerifier
test with a fluent API.
-
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description EqualsVerifierReport
report()
Performs the verification of the contracts forequals
andhashCode
and returns anEqualsVerifierReport
with the results of the verification.EqualsVerifierApi<T>
suppress(Warning... warnings)
Suppresses warnings given byEqualsVerifier
.EqualsVerifierApi<T>
usingGetClass()
Signals thatgetClass
is used in the implementation of theequals
method, instead of aninstanceof
check.void
verify()
Performs the verification of the contracts forequals
andhashCode
and throws anAssertionError
if there is a problem.EqualsVerifierApi<T>
withCachedHashCode(java.lang.String cachedHashCodeField, java.lang.String calculateHashCodeMethod, T example)
Signals that T caches its hashCode, instead of re-calculating it each time thehashCode()
method is called.<S> EqualsVerifierApi<T>
withGenericPrefabValues(java.lang.Class<S> otherType, Func.Func1<?,S> factory)
Adds a factory to generate prefabricated values for instance fields of classes with 1 generic type parameter that EqualsVerifier cannot instantiate by itself.<S> EqualsVerifierApi<T>
withGenericPrefabValues(java.lang.Class<S> otherType, Func.Func2<?,?,S> factory)
Adds a factory to generate prefabricated values for instance fields of classes with 2 generic type parameters that EqualsVerifier cannot instantiate by itself.EqualsVerifierApi<T>
withIgnoredAnnotations(java.lang.Class<?>... annotations)
Signals that all given annotations are to be ignored by EqualsVerifier.EqualsVerifierApi<T>
withIgnoredFields(java.lang.String... fields)
Signals that all given fields are not relevant for theequals
contract.EqualsVerifierApi<T>
withNonnullFields(java.lang.String... fields)
Signals that all given fields can never be null, andEqualsVerifier
therefore doesn't have to verify that proper null checks are in place for these fields.EqualsVerifierApi<T>
withOnlyTheseFields(java.lang.String... fields)
Signals that all given fields, and only the given fields, are relevant for theequals
contract.<S> EqualsVerifierApi<T>
withPrefabValues(java.lang.Class<S> otherType, S red, S black)
Adds prefabricated values for instance fields of classes that EqualsVerifier cannot instantiate by itself.EqualsVerifierApi<T>
withRedefinedSubclass(java.lang.Class<? extends T> subclass)
Supplies a reference to a subclass of T in whichequals
is overridden.EqualsVerifierApi<T>
withRedefinedSuperclass()
Signals that T is part of an inheritance hierarchy whereequals
is overridden.
-
-
-
Method Detail
-
suppress
public EqualsVerifierApi<T> suppress(Warning... warnings)
Suppresses warnings given byEqualsVerifier
. SeeWarning
to see what warnings can be suppressed.- Parameters:
warnings
- A list of warnings to suppress inEqualsVerifier
.- Returns:
this
, for easy method chaining.
-
withPrefabValues
public <S> EqualsVerifierApi<T> withPrefabValues(java.lang.Class<S> otherType, S red, S black)
Adds prefabricated values for instance fields of classes that EqualsVerifier cannot instantiate by itself.- Type Parameters:
S
- The class of the prefabricated values.- Parameters:
otherType
- The class of the prefabricated values.red
- An instance ofS
.black
- Another instance ofS
, not equal tored
.- Returns:
this
, for easy method chaining.- Throws:
java.lang.NullPointerException
- If eitherotherType
,red
, orblack
is null.java.lang.IllegalArgumentException
- Ifred
equalsblack
.
-
withGenericPrefabValues
public <S> EqualsVerifierApi<T> withGenericPrefabValues(java.lang.Class<S> otherType, Func.Func1<?,S> factory)
Adds a factory to generate prefabricated values for instance fields of classes with 1 generic type parameter that EqualsVerifier cannot instantiate by itself.- Type Parameters:
S
- The class of the prefabricated values.- Parameters:
otherType
- The class of the prefabricated values.factory
- A factory to generate an instance ofS
, given a value of its generic type parameter.- Returns:
this
, for easy method chaining.- Throws:
java.lang.NullPointerException
- if eitherotherType
orfactory
is null.
-
withGenericPrefabValues
public <S> EqualsVerifierApi<T> withGenericPrefabValues(java.lang.Class<S> otherType, Func.Func2<?,?,S> factory)
Adds a factory to generate prefabricated values for instance fields of classes with 2 generic type parameters that EqualsVerifier cannot instantiate by itself.- Type Parameters:
S
- The class of the prefabricated values.- Parameters:
otherType
- The class of the prefabricated values.factory
- A factory to generate an instance ofS
, given a value of each of its generic type parameters.- Returns:
this
, for easy method chaining.- Throws:
java.lang.NullPointerException
- if eitherotherType
orfactory
is null.
-
usingGetClass
public EqualsVerifierApi<T> usingGetClass()
Signals thatgetClass
is used in the implementation of theequals
method, instead of aninstanceof
check.- Returns:
this
, for easy method chaining.
-
withIgnoredFields
public EqualsVerifierApi<T> withIgnoredFields(java.lang.String... fields)
Signals that all given fields are not relevant for theequals
contract.EqualsVerifier
will not fail if one of these fields does not affect the outcome ofequals
, but it will fail if one of these fields does affect the outcome ofequals
. Note that these fields will still be used to test for null-ness, among other things.- Parameters:
fields
- Fields that should be ignored.- Returns:
this
, for easy method chaining.
-
withOnlyTheseFields
public EqualsVerifierApi<T> withOnlyTheseFields(java.lang.String... fields)
Signals that all given fields, and only the given fields, are relevant for theequals
contract.EqualsVerifier
will fail if one of these fields does not affect the outcome ofequals
, and it will fail if a field that isn't listed here, does affect the outcome ofequals
.- Parameters:
fields
- Fields that should be ignored.- Returns:
this
, for easy method chaining.
-
withNonnullFields
public EqualsVerifierApi<T> withNonnullFields(java.lang.String... fields)
Signals that all given fields can never be null, andEqualsVerifier
therefore doesn't have to verify that proper null checks are in place for these fields. This can be used instead of {link #suppress(Warning...)}, which provides the same behaviour for all fields, when only some fields are never null but others are.- Parameters:
fields
- Fields that can never be null.- Returns:
this
, for easy method chaining.
-
withIgnoredAnnotations
public EqualsVerifierApi<T> withIgnoredAnnotations(java.lang.Class<?>... annotations)
Signals that all given annotations are to be ignored by EqualsVerifier. For instance, EqualsVerifier normally doesn't perform null verifications on fields marked with an@Nonnull
annotation. However, if this method is called with aNonnull.class
parameter, the null verifications will be performed after all.- Parameters:
annotations
- Annotations to ignore.- Returns:
this
, for easy method chaining.
-
withRedefinedSuperclass
public EqualsVerifierApi<T> withRedefinedSuperclass()
Signals that T is part of an inheritance hierarchy whereequals
is overridden. Call this method if T has overriddenequals
andhashCode
, and one or more of T's superclasses have as well.T itself does not necessarily have to have subclasses that redefine
equals
andhashCode
.- Returns:
this
, for easy method chaining.
-
withRedefinedSubclass
public EqualsVerifierApi<T> withRedefinedSubclass(java.lang.Class<? extends T> subclass)
Supplies a reference to a subclass of T in whichequals
is overridden. Calling this method is mandatory ifequals
is not final and a strong verification is performed. Note that, for each subclass that overridesequals
,EqualsVerifier
should be used as well to verify its adherence to the contracts.- Parameters:
subclass
- A subclass of T for which no instance can be equal to any instance of T.- Returns:
this
, for easy method chaining.- See Also:
Warning.STRICT_INHERITANCE
-
withCachedHashCode
public EqualsVerifierApi<T> withCachedHashCode(java.lang.String cachedHashCodeField, java.lang.String calculateHashCodeMethod, T example)
Signals that T caches its hashCode, instead of re-calculating it each time thehashCode()
method is called. There are 3 conditions to verify cached hashCodes: First, the class under test must have a private int field that contains the cached hashCode. Second, the class under test must have a private method that calculates the hashCode. The method must return an int and may not take any parameters. It should be used by the constructor or the hashCode method of the class under test to initialize the cached hashCode. This may lead to slightly awkward production code, but unfortunately, it is necessary for EqualsVerifier to verify that the hashCode is correct. Finally, only immutable objects can be verified. In other words,withCachedHashCode
can not be used whenWarning.NONFINAL_FIELDS
is suppressed.- Parameters:
cachedHashCodeField
- The name of the field which stores the cached hash code.calculateHashCodeMethod
- The name of the method which recomputes the hash code. It should return an int and take no parameters.example
- An instance of the class under test, to verify that the hashCode has been initialized properly.- Returns:
this
, for easy method chaining.
-
verify
public void verify()
Performs the verification of the contracts forequals
andhashCode
and throws anAssertionError
if there is a problem.- Throws:
java.lang.AssertionError
- If the contract is not met, or ifEqualsVerifier
's preconditions do not hold.
-
report
public EqualsVerifierReport report()
Performs the verification of the contracts forequals
andhashCode
and returns anEqualsVerifierReport
with the results of the verification.- Returns:
- An
EqualsVerifierReport
that indicates whether the contract is met and whetherEqualsVerifier
's preconditions hold.
-
-