What is the contract between equals and hashCode?

The contract has three practical rules. equals must be reflexive, symmetric and transitive. It must be consistent while the object is used as a key. And if two objects are equal, they must produce the same hashCode. Unequal objects may share a hash code, which is a collision, but equal objects may not.

public final class Point {
    private final int x;
    private final int y;

    public Point(int x, int y) {
        this.x = x;
        this.y = y;
    }

    @Override
    public boolean equals(Object other) {
        if (this == other) {
            return true;
        }
        if (!(other instanceof Point)) {
            return false;
        }
        Point point = (Point) other;
        return x == point.x && y == point.y;
    }

    @Override
    public int hashCode() {
        return Objects.hash(x, y);
    }
}

How hash collections use the contract

• HashMap computes the hash to choose a bucket, then calls equals to find the exact key
• If equals is overridden without hashCode, equal keys can land in different buckets and become unreachable
• If a mutable field used in hashCode changes after insertion, the entry is effectively lost
• Records generate a consistent equals and hashCode from their components

Use getClass comparison when subclass equality must be strict, and instanceof when a subtype should be able to equal its parent representation, which is uncommon and risky. Prefer composition over inheritance for value types to avoid these questions.