What is the relationship between the equals contract and hashCode, and what concretely goes wrong in a HashMap or HashSet if you override one but not the other?

## Two separate contracts that must agree `Object` declares both `equals(Object)` and `hashCode()`. Their Javadoc ties them together: 1. **If `a.equals(b)` is true, then `a.hashCode() == b.hashCode()` must be true.** (Equal ⇒ same hash.) 2. The converse is **not** required: two unequal objects *may* share a hash code (a **collision**) — that's allowed and normal. 3. `hashCode` must be **consistent**: same object returns the same int across calls (unless equals-relevant fields change). ## How a HashMap/HashSet actually uses them A hash-based collection stores entries in an array of **buckets**. To place or find a key it: 1. computes `key.hashCode()`, maps it (via further mixing + modulo) to a **bucket index**; 2. goes to that one bucket and walks its (short) list/tree of entries; 3. for each candidate, calls `equals` to confirm an exact match. The whole point is to avoid scanning all entries — `hashCode` narrows the search to one bucket, `equals` confirms within it. This only works if **equal keys hash to the same bucket**. ## Failure mode 1 — override equals, inherit hashCode Suppose `PhoneNumber` overrides `equals` to compare its digits but leaves `Object.hashCode` (identity hash, essentially the object's address): ```java Map<PhoneNumber,String> m = new HashMap<>(); m.put(new PhoneNumber(707,867,5309), "Jenny"); m.get(new PhoneNumber(707,867,5309)); // null !! ``` The two `PhoneNumber`s are `equals`-equal but have **different** identity hash codes → they map to **different buckets**. `get` searches only the bucket for the *second* object's hash, never finds the first, and returns `null`. Likewise a `HashSet` will happily store both as if they were distinct, so logical duplicates accumulate and `contains` returns false for a value that is logically present. ## Failure mode 2 — override hashCode, inherit equals Now the hashes match, so both objects land in the **same** bucket. But within the bucket the collection still calls `equals`, which is the inherited **identity** equals → the two distinct objects are deemed unequal. So you again get duplicates / failed lookups, just for the opposite reason. Matching hashes are necessary but never sufficient. ## Why 'equal ⇒ same hash', not the reverse Hashing maps a huge value space to a finite int, so collisions are inevitable; demanding unequal objects always differ would be impossible. The collection tolerates collisions by falling back to `equals` within a bucket. What it cannot tolerate is **equal objects with different hashes**, because then it never even visits the right bucket. ## Correct paired implementation ```java public final class PhoneNumber { private final short area, prefix, line; // ... constructor ... @Override public boolean equals(Object o) { if (this == o) return true; if (!(o instanceof PhoneNumber pn)) return false; return area==pn.area && prefix==pn.prefix && line==pn.line; } @Override public int hashCode() { return java.util.Objects.hash(area, prefix, line); // same fields as equals } } ``` Rules of thumb: **use exactly the same fields** in both; never include a mutable field in equals/hashCode if the object will be used as a hash key (changing it after insertion strands the entry in the wrong bucket); and prefer generated implementations — `record`, the IDE, or Lombok `@EqualsAndHashCode` — so the two never drift apart. ## The mutable-key corollary Even a correct pair breaks if you **mutate an equals-relevant field after** putting the object in a hash collection: its hashCode changes, but it's still physically in the old bucket, so it becomes unreachable. Use immutable keys. ## Takeaway equals and hashCode are a package deal: equal objects must hash equally; collisions are fine. Override one and the bucket logic of HashMap/HashSet silently breaks — lost lookups or duplicate entries. Override both over the same immutable fields.