5) Equals and Hashcode
1) equals()
The Object class defines both the equals() and hashCode() methods – which means that these two methods are implicitly defined in every Java class, including the ones we create:
We would expect income.equals(expenses) to return true. But with the Money class in its current form, it won’t.
The default implementation of equals() in the class Object says that equality is the same as object identity. And income and expenses are two distinct instances.
Without Equals :
1.1) Overriding equals()
Let’s override the equals() method so that it doesn’t consider only object identity, but rather also the value of the two relevant properties:
Genrating Equals/Hashcode using Eclipse:
Way 1: Using getClass()
Way 2: Using instanceOf()
With Equals :
1.2) equals() Contract
Java SE defines a contract that our implementation of the equals() method must fulfill. Most of the criteria are common sense. The equals() method must be:
reflexive: an object must equal itself
symmetric: x.equals(y) must return the same result as y.equals(x)
transitive: if x.equals(y) and y.equals(z) then also x.equals(z)
consistent: the value of equals() should change only if a property that is contained in equals() changes (no randomness allowed)
We can look up the exact criteria in the Java SE Docs for the Object class.
1.3) Violating equals() Symmetry with Inheritance
If the criteria for equals() is such common sense, how can we violate it at all? Well, violations happen most often, if we extend a class that has overridden equals(). Let’s consider a Voucher class that extends our Money class:
At first glance, the Voucher class and its override for equals() seem to be correct. And both equals()methods behave correctly as long as we compare Money to Money or Voucher to Voucher. But what happens, if we compare these two objects?
That violates the symmetry criteria of the equals() contract.
1.4) Way 1: Using getClass instead of instanceOf()
Refer to Way 1: Using getClass()
Example 2:
1.4) Way 2 : Fixing equals() Symmetry with Composition
To avoid this pitfall, we should favor composition over inheritance.
Instead of subclassing Money, let’s create a Voucher class with a Money property:
And now, equals will work symmetrically as the contract requires.
2. hashCode()
hashCode() returns an integer representing the current instance of the class. We should calculate this value consistent with the definition of equality for the class. Thus if we override the equals() method, we also have to override hashCode().
For some more details, check out our guide to hashCode().
2.1) hashCode() Contract
Java SE also defines a contract for the hashCode() method. A thorough look at it shows how closely related hashCode() and equals() are.
All three criteria in the contract of hashCode() mention in some ways the equals() method:
internal consistency: the value of hashCode() may only change if a property that is in equals() changes
equals consistency: objects that are equal to each other must return the same hashCode
collisions: unequal objects may have the same hashCode
2.2) Violating the Consistency of hashCode() and equals()
The 2nd criteria of the hashCode methods contract has an important consequence: If we override equals(), we must also override hashCode(). And this is by far the most widespread violation regarding the contracts of the equals() and hashCode() methods.
Let’s see such an example:
The Team class overrides only equals(), but it still implicitly uses the default implementation of hashCode() as defined in the Object class. And this returns a different hashCode() for every instance of the class. This violates the second rule.
Now if we create two Team objects, both with city “New York” and department “marketing”, they will be equal, but they will return different hashCodes.
2.3) HashMap Key with an Inconsistent hashCode()
But why is the contract violation in our Team class a problem? Well, the trouble starts when some hash-based collections are involved. Let’s try to use our Team class as a key of a HashMap:
We would expect myTeamLeader to return “Anne”. But with the current code, it doesn’t.
If we want to use instances of the Team class as HashMap keys, we have to override the hashCode()method so that it adheres to the contract: Equal objects return the same hashCode.
Let’s see an example implementation:
Example : collisions: unequal objects may have the same hashCode
3. When Do We Override equals() and hashCode()?
Generally, we want to override either both of them or neither of them. We’ve just seen in Section 3 the undesired consequences if we ignore this rule.
Domain-Driven Design can help us decide circumstances when we should leave them be. For entity classes – for objects having an intrinsic identity – the default implementation often makes sense.
However, for value objects, we usually prefer equality based on their properties. Thus want to override equals() and hashCode(). Remember our Money class from Section 1: 55 USD equals 55 USD – even if they’re two separate instances.
4. Implementation Helpers
We typically don’t write the implementation of these methods by hand. As can be seen, there are quite a few pitfalls.
One common way is to let our IDE generate the equals() and hashCode() methods.
Apache Commons Lang and Google Guava have helper classes in order to simplify writing both methods.
Project Lombok also provides an @EqualsAndHashCode annotation. Note again how equals() and hashCode() “go together” and even have a common annotation.
6. Verifying the Contracts
If we want to check whether our implementations adhere to the Java SE contracts and also to some best practices, we can use the EqualsVerifier library.
Let’s add the EqualsVerifier Maven test dependency:
Let’s verify that our Team class follows the equals() and hashCode() contracts:
It’s worth noting that EqualsVerifier tests both the equals() and hashCode() methods.
EqualsVerifier is much stricter than the Java SE contract. For example, it makes sure that our methods can’t throw a NullPointerException. Also, it enforces that both methods, or the class itself, is final.
It’s important to realize that the default configuration of EqualsVerifier allows only immutable fields. This is a stricter check than what the Java SE contract allows. This adheres to a recommendation of Domain-Driven Design to make value objects immutable.
If we find some of the built-in constraints unnecessary, we can add a suppress(Warning.SPECIFIC_WARNING) to our EqualsVerifier call.
7. Conclusion
We should remember to:
Always override hashCode() if we override equals()
Override equals() and hashCode() for value objects
Be aware of the traps of extending classes that have overridden equals() and hashCode()
Consider using an IDE or a third-party library for generating the equals() and hashCode() methods
Consider using EqualsVerifier to test our implementation
Finally, all code examples can be found over on GitHub.
Last updated