equals(), hashCode() & Object Methods

equals() defines when two objects count as "the same value", and hashCode() must agree with it — together they are the contract every object stored in a HashSet or HashMap has to honour.

Learn equals(), hashCode() & Object Methods in our free Java course — a beginner-friendly interactive lesson with worked examples, a practice exercise and a…

Part of the free Java course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

Before You Start

You should know classes and objects and have used the Collections (especially HashSet and HashMap ). A glance at records shows the shortcut that generates these for you.

What You'll Learn

The Big Idea — Library Shelves

💡 Analogy: A HashMap is a library where hashCode is the shelf number and equals is reading the title to find the exact book. To return a book you first walk to the shelf its hash points to, then check titles on that shelf. If two identical books somehow get different shelf numbers (equal by equals but different hashCode ), the librarian walks to the wrong shelf and swears the book isn't there. That is the silent bug behind "my object is in the set but contains() returns false".

The rule that keeps the library sane: equal objects must hash to the same shelf. Override one, override the other.

1️⃣ The Default Behaviour (identity)

Every class inherits equals and hashCode from Object . By default equals is just == (reference identity) and hashCode is derived from the object's memory identity. So two objects with identical fields are not equal, and a HashSet happily stores both as duplicates.

2️⃣ Implementing equals and hashCode Correctly

A correct equals follows a fixed shape: identity fast-path, an instanceof check (which also rejects null ), a cast, then a field-by-field comparison. The matching hashCode uses Objects.hash(...) over the same fields . Add a readable toString while you're there.

3️⃣ The Classic Bug — equals without hashCode

Override equals but forget hashCode and you get the most infamous Java bug: objects that are equal but have different hash codes. They land in different buckets, so set.contains and map.get fail to find them even though an equal object is right there.

4️⃣ Records Give You All Three for Free

Declare the same value type as a record and the compiler generates equals , hashCode , and toString — all consistent, all derived from the components. For simple immutable data carriers this is the safest and shortest option.

🧠 Quick Recall

Answer: illegal — it breaks the contract and breaks hash collections. The reverse (different objects sharing a hashCode) is legal; that's just a collision, which equals resolves.

Answer: because a might be null . Objects.equals(a, b) is null-safe — it returns true if both are null and never throws an NPE.

Answer: no — == compares references and new String makes a distinct object. .equals is true . Always use .equals for String value comparison.

🎯 YOUR TURN — Equal by ISBN

Override equals and hashCode on Book so two books with the same ISBN are one in a HashSet .

🧩 MINI-CHALLENGE — Record as a map key

Use a record Coord(int x, int y) as a HashMap key. Re-putting the same coordinate overwrites, and lookups by a fresh Coord must hit.

Common Errors

• ❌ Overriding equals but not hashCode. Hash collections silently break. Fix: always override both, over the same fields.
• ❌ Wrong equals signature. equals(Point p) overloads instead of overriding. Fix: the parameter must be Object ; add @Override so the compiler catches it.
• ❌ Using == to compare fields that are objects. It compares references. Fix: use Objects.equals for object fields, == only for primitives.
• ❌ Including mutable fields in hashCode. If a key's hash changes after insertion, it's lost in the map. Fix: base equals/hashCode on stable (ideally final) fields.
• ❌ Forgetting the null/type check. Casting first throws on a wrong type. Fix: guard with instanceof , which is false for null and wrong types.
• ❌ Hand-writing all this when a record would do. More code, more bugs. Fix: use a record for plain immutable data.

Pro Tips

• 💡 Let your IDE or a record generate them. Hand-rolled equals/hashCode is a top source of subtle bugs.
• 💡 Use the same fields in both methods — and only fields that define identity, not caches or timestamps.
• 💡 Keep value types final to avoid the subclass symmetry trap in equals.
• 💡 Always override toString too. Good toString output makes logs and debugger views instantly readable.

📋 Quick Reference

Concept

Syntax

Note

identity fast path

if (this == o) return true;

First line of equals

type/null check

if (!(o instanceof T)) return false;

false for null too

field compare

Objects.equals(a, b)

Null-safe

primitive compare

x == p.x

== fine for primitives

hashCode

Objects.hash(f1, f2)

Same fields as equals

contract

equal ⇒ same hashCode

Reverse not required

override marker

@Override

Catches bad signatures

toString

@Override String toString()

Readable output

value vs identity

.equals vs ==

Value vs reference

record

record T(...)

All three for free

use in

HashSet / HashMap

Needs correct pair

📚 Resources / Keep Learning

• 📘 Object (equals, hashCode, toString) — Java 21 API (docs.oracle.com)
• 📘 Objects utility class — Java 21 API (docs.oracle.com)
• 📗 Records — dev.java tutorial

❓ Frequently Asked Questions

🎉 Lesson Complete!

You now know what the default equals / hashCode do, the contract that binds them, how to write both correctly with instanceof , Objects.equals and Objects.hash , why a missing hashCode silently breaks hash collections, and how records hand you all of it for free.

Next up: Immutability & Defensive Copying — building objects that can't be corrupted after construction.

Practice quiz

Continue this course

• Previous: The Java HTTP Client
• Next: Immutability & Defensive Copying

Related lessons

• classes and objects
• Collections
• records