equals & hashCode — the Contract Behind Hash Collections

The object model showed that == compares identity and .equals compares meaning — if the class defines what "meaning" is. By default it does not: a class inherits an equals that just checks identity (same object) and a hashCode tied to the object's address. So two Point(1, 2) objects are not equal, and they misbehave in the hash-based collections of the last chapter. To fix that you override equals to compare values — and here is the trap this chapter exists for: if you override equals, you must override hashCode to match, or HashSet/HashMap will silently fail to find your objects and let duplicates in. The two are a contract; honoring one without the other is worse than neither.

Every output below was produced by compiling and running the code.

Table of contents

1. Default equals is identity
2. Overriding equals for value equality
3. The hashCode contract
4. Generating both correctly
5. Mental-model summary
6. Gotcha checklist

1. Default equals is identity

A class that defines no equals inherits the one from Object, which returns true only for the same object. So two separately created objects with identical fields are not equal:

Output:

false
false

Analysis. a == b is false because they are distinct objects (the object model's identity rule). But a.equals(b) is also false — the inherited equals is just an identity check, so by default .equals and == agree. The class hasn't said what it means for two points to be "equal," so Java assumes the safest default: only a thing equals itself.

Intuition. Mechanism. Object.equals(o) is defined as this == o — pure identity. Unless a class overrides it, "equal" means "the same object," and value-equal-but-distinct objects compare false.

Concrete bite. The second false is the surprise: people expect .equals to compare contents, but for a class that didn't override it, .equals is identity too. A List.contains, a Map key lookup, a deduplicating Set — all use .equals, so all of them treat your two equal points as different.

2. Overriding equals for value equality

To define value equality, override equals(Object o): check the argument is a Point, then compare the fields. (o instanceof Point tests the type; (Point) o casts it — the cast lets you reach the fields; pattern-matching instanceof in Tutorial 26 fuses the two.)

Output:

false
true

Analysis. Now a.equals(b) is true — the overridden method compared x and y, which match. a == b is still false, because == is identity and these remain two different objects. We've split the two notions cleanly: == for "same object," .equals for "same value." The @Override annotation asks the compiler to confirm we're really overriding Object.equals (correct signature: parameter type Object).

Intuition. Mechanism. Overriding equals replaces identity comparison with your value comparison wherever .equals is called — including deep inside the collections. The instanceof guard also handles null and wrong types (returning false), satisfying equals's contract that it never throws on a bad argument.

Concrete bite. A subtle slip: writing public boolean equals(Point o) (parameter Point, not Object) does not override Object.equals — it overloads it, so collections (which call equals(Object)) ignore your version and fall back to identity. The @Override annotation catches this at compile time; without it the bug is silent.

3. The hashCode contract

Here is the rule that makes or breaks hash collections: if a.equals(b) is true, then a.hashCode() must equal b.hashCode(). Override equals but leave hashCode as the inherited identity-based one, and equal objects get different hash codes — so a HashSet/HashMap looks in the wrong bucket and your object vanishes.

Output:

false
2

Analysis. This is broken in two visible ways. contains(new Point(1, 2)) is false — the set computed the lookup point's (identity) hash code, went to that bucket, and didn't find the stored point, which lives in a different bucket. And adding a second equal point grew the size to 2 — the set put it in yet another bucket without ever discovering it was a duplicate. The diagram shows the cause: value-equal points scatter to different buckets because identity hashCode ignores the fields. The equals method was never even consulted, because the set never looked in the right bucket.

Intuition. Mechanism. A hash collection finds an object in two steps: hash to a bucket, then .equals within that bucket. If equal objects have unequal hash codes, step one sends them to different buckets, so step two never runs — equals is correct but unreachable. Overriding equals without hashCode breaks the first step.

Concrete bite. The false and the 2 are the breakage: a present element reports absent, and a duplicate slips in. This is among the most insidious Java bugs because the class looks right (equals works in isolation) and only fails inside hash collections.

4. Generating both correctly

You rarely write hashCode by hand. Objects.hash(...) builds a hash from the same fields equals uses, and Objects.equals(a, b) null-safely compares fields. Use exactly the fields in both methods, and the contract holds.

Output:

true
1

Analysis. With hashCode derived from x and y, two equal points now hash to the same bucket — so contains finds the stored point (true), and adding a duplicate is recognized and dropped (size stays 1). The collection works because the contract holds: equal points → equal hashes → same bucket → equals confirms the match.

Intuition. Mechanism. Objects.hash(x, y) combines the fields into one int deterministically, so equal field-values yield equal hashes; equals then confirms equality within the bucket. The two methods must use the same fields — a field in equals but not hashCode re-breaks the contract.

Concrete bite. The fix is exactly the inverse of §3's breakage: true and 1 instead of false and 2. The only change was adding a hashCode consistent with equals — proof that the broken behavior was the missing hashCode, nothing else.

5. Mental-model summary

6. Gotcha checklist

Your Turn

Before you move on, check your understanding with the coach — explain the idea, apply it, weigh the trade-offs, then defend your reasoning.