The equals/hashCode contract

Written Explanation

The equals contract

When you override equals(Object), the Java documentation requires that it is an equivalence relation on non-null objects:

Notice that the parameter type is Object, not your class. If you write equals(Money other), you have overloaded the method instead of overriding it, so @Override will give a compile error. Always write @Override and the Object parameter.

The hashCode contract

hashCode() returns an int. The documented rules:

• Within one run, it returns the same value for the same object, as long as the information used in equals does not change.
• If x.equals(y) is true, then x.hashCode() == y.hashCode() must be true.
• If two objects are not equal, they are not required to have different hash codes. Different codes help performance (fewer clashes), but sharing one is allowed.

The reverse is not a rule: the same hash does not prove equality. A hash code is the pile number, not the identity card.

Why they travel together

Hash-based collections (such as HashSet and HashMap, which you will meet in a later module) work in two steps. First they use hashCode() to pick a bucket, a small group of entries. Then they use equals only on entries in that bucket. So if two equal objects produce different hash codes, they go to different buckets and the collection never even compares them. The result is silent duplicates and failed lookups. The default hashCode is identity-based, so a class that overrides only equals is exactly in this trap.

A reliable recipe

For a value class:

1. Decide which fields define "the same value". (For Money: cents and currency. For a Customer identified by id: only id.)
2. In equals: return true for the same object, return false if the other is not your type (this also handles null), then compare the chosen fields.
3. In hashCode: combine the same fields.

@Override
public boolean equals(Object o) {
    if (this == o) return true;
    if (!(o instanceof Money m)) return false;
    return cents == m.cents && currency.equals(m.currency);
}

@Override
public int hashCode() {
    return Objects.hash(cents, currency);
}

o instanceof Money m is false for null, so the non-null rule holds. Compare primitive fields with == and object fields with equals. If a field can be null, use Objects.equals(a, b) instead of a.equals(b).

Objects.hash(...) accepts any number of values and combines them; it copes with null values too. The exact numbers it produces are an implementation detail, so never hard-code them in tests.

Which fields should you use?

• Use exactly the fields that define equality, in both methods.
• Do not use fields that change after the object is stored in a hash-based collection. A hashCode based on a mutable field means the object is filed in one bucket, then the field changes, the hash changes, and later lookups search another bucket. The object seems to vanish, although it is still inside. The safest design is to base the pair on final fields, or on a stable identifier such as an id.
• A class can be equal by id only. Two Customer objects with the same id and different names can be "the same customer at different moments", so you may choose to ignore the name.

A note on subclasses

Using instanceof in equals is fine when the class is final or when subclasses add no fields that matter. When subclasses add fields and are compared with their parents, symmetry can break. For now, keep value classes final (or immutable and simple) and you avoid the problem. Lesson 5 shows a way to skip this boilerplate altogether.