[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6},"actionData","errors","routes/blog-tag",{"_7":8,"_9":10},"tag",{"_31":83,"_72":84,"_35":85},"articles",{"_11":12,"_13":14,"_15":16,"_17":16,"_18":19,"_20":21,"_22":23,"_24":23,"_25":16,"_26":27},"content",[30],"pageable",{"_28":21,"_29":19},"totalElements",1,"totalPages","size",10,"number",0,"first",true,"last","numberOfElements","empty",false,"page_number","page_size",{"_31":32,"_33":34,"_35":36,"_37":38,"_11":39,"_40":-5,"_41":23,"_42":27,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_53":52,"_54":55,"_56":57,"_58":59,"_60":52,"_61":62,"_63":55,"_64":65,"_66":67,"_68":69,"_70":71},"id",99,"title","The equals() and hashCode() Contract","slug","java-collections-part-3-equals-hashcode-contract","excerpt","Understand the critical equals/hashCode contract that governs HashSet and HashMap behavior. Learn why implementation matters and debug 'vanishing' objects in collections.","# Java Collections Part 3: equals(), hashCode() & The Object Contract\n\nThe `equals()` and `hashCode()` methods are the foundation of how Java collections work. Get them wrong, and objects \"disappear\" from HashMaps, duplicates appear in HashSets, and tests fail mysteriously. Get them right, and your collections behave predictably and efficiently.\n\nThis is the #1 most-asked topic in Java interviews for good reason - it reveals whether a developer truly understands how collections work under the hood.\n\n## 📋 At a Glance\n\n| Aspect | Details |\n|--------|---------|\n| Core Methods | `equals()`, `hashCode()` from `Object` class |\n| Related | `Comparable.compareTo()`, `Comparator.compare()` |\n| Contract | Mathematical properties that must hold |\n| Impact | HashSet, HashMap, TreeSet, TreeMap behavior |\n| Key Insight | `equals()` = true ⟹ `hashCode()` must be same |\n\n---\n\n## 🎯 What You'll Learn\n\nAfter reading this article, you will be able to:\n\n- **Explain the contracts** for equals(), hashCode(), and Comparable\n- **Implement correct** equals/hashCode for any class\n- **Identify bugs** when contracts are violated\n- **Understand why** mutable keys cause problems in HashMaps\n- **Use modern alternatives** like Records and Lombok safely\n- **Debug issues** where objects \"disappear\" from collections\n\n---\n\n## 🔥 Production Story: The Vanishing Orders\n\nAn e-commerce platform had a critical bug: orders were \"disappearing\" from the cache. Customer service was getting complaints about orders not appearing in the dashboard, even though they existed in the database.\n\nAfter two days of debugging, the team found the culprit:\n\n```java\npublic class Order {\n private Long id;\n private String customerId;\n private OrderStatus status; // PENDING, PAID, SHIPPED, etc.\n private BigDecimal total;\n\n // ❌ THE BUG: status was included in equals/hashCode\n @Override\n public boolean equals(Object o) {\n if (this == o) return true;\n if (o == null || getClass() != o.getClass()) return false;\n Order order = (Order) o;\n return Objects.equals(id, order.id) &&\n Objects.equals(customerId, order.customerId) &&\n Objects.equals(status, order.status) && // ← Problem!\n Objects.equals(total, order.total);\n }\n\n @Override\n public int hashCode() {\n return Objects.hash(id, customerId, status, total); // ← Problem!\n }\n}\n```\n\nThe cache used a `HashSet`. Here's what happened:\n\n```java\n// Step 1: Order created and cached\nOrder order = new Order(123L, \"CUST-001\", OrderStatus.PENDING, new BigDecimal(\"99.99\"));\norderCache.add(order); // Stored at bucket for hashCode() = X\n\n// Step 2: Later, order status updated\norder.setStatus(OrderStatus.PAID); // hashCode() now = Y (different!)\n\n// Step 3: Try to check if order is cached\norderCache.contains(order); // Returns FALSE!\n// The order IS in the set, but at bucket X. We're looking in bucket Y.\n\n// Step 4: Try to remove the order\norderCache.remove(order); // Returns FALSE! Can't find it.\n// The order is now \"stuck\" in the set - a memory leak!\n```\n\n**The fix:**\n\n```java\npublic class Order {\n private Long id; // Immutable identifier\n // ... other fields\n\n // ✅ CORRECT: Only use immutable, identifying fields\n @Override\n public boolean equals(Object o) {\n if (this == o) return true;\n if (o == null || getClass() != o.getClass()) return false;\n Order order = (Order) o;\n return Objects.equals(id, order.id); // Only ID\n }\n\n @Override\n public int hashCode() {\n return Objects.hash(id); // Only ID\n }\n}\n```\n\n**The lessons:**\n1. Only include immutable fields in equals/hashCode\n2. For entities, identity (ID) is usually the only field needed\n3. Mutable fields in hash calculations = time bombs\n\n---\n\n## 🧠 Mental Model: The Library Card Catalog\n\nThink of `hashCode()` and `equals()` like a library's card catalog system:\n\n```text\n┌─────────────────────────────────────────────────────────────────┐\n│ THE LIBRARY CATALOG │\n├─────────────────────────────────────────────────────────────────┤\n│ │\n│ hashCode() = WHICH DRAWER to look in │\n│ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │\n│ │ A-C │ │ D-F │ │ G-I │ │ J-L │ │ M-O │ ... │\n│ └──┬──┘ └─────┘ └──┬──┘ └─────┘ └─────┘ │\n│ │ │ │\n│ │ equals() = WHICH CARD in the drawer │\n│ │ ┌────────────────────────────────┐ │\n│ └───→│ Card 1: \"Anderson, Alice\" │ │\n│ │ Card 2: \"Brooks, Bob\" │ │\n│ │ Card 3: \"Chen, Charlie\" │ │\n│ └────────────────────────────────┘ │\n│ │\n│ To find a book: │\n│ 1. hashCode() → tells you which drawer (fast!) │\n│ 2. equals() → compare cards in that drawer (may be slow) │\n│ │\n│ THE CONTRACT: │\n│ • Same book → MUST be in same drawer (equal → same hashCode) │\n│ • Different drawers → DEFINITELY different books │\n│ • Same drawer → MIGHT be same book (need equals() to confirm) │\n│ │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n**Key insight:** `hashCode()` is for *speed* (narrow down the search), `equals()` is for *correctness* (confirm exact match).\n\n---\n\n## 🔬 Deep Dive\n\n### 1. The equals() Contract\n\nThe `equals()` method must satisfy these mathematical properties:\n\n```java\n// ✅ The Five Properties of equals()\n\n// 1. REFLEXIVE: x.equals(x) must return true\n// An object must be equal to itself\nassertThat(x.equals(x)).isTrue();\n\n// 2. SYMMETRIC: x.equals(y) == y.equals(x)\n// If A equals B, then B must equal A\nassertThat(x.equals(y)).isEqualTo(y.equals(x));\n\n// 3. TRANSITIVE: x.equals(y) && y.equals(z) ⟹ x.equals(z)\n// If A=B and B=C, then A=C\nif (x.equals(y) && y.equals(z)) {\n assertThat(x.equals(z)).isTrue();\n}\n\n// 4. CONSISTENT: Multiple calls return same result (if objects unchanged)\n// Must be deterministic\nassertThat(x.equals(y)).isEqualTo(x.equals(y));\n\n// 5. NULL HANDLING: x.equals(null) must return false\n// Never throw NullPointerException, return false instead\nassertThat(x.equals(null)).isFalse();\n```\n\n**Breaking symmetry (common mistake):**\n\n```java\n// ❌ BAD: Breaks symmetry with inheritance\npublic class Point {\n protected int x, y;\n\n @Override\n public boolean equals(Object o) {\n if (!(o instanceof Point)) return false;\n Point p = (Point) o;\n return x == p.x && y == p.y;\n }\n}\n\npublic class ColorPoint extends Point {\n private Color color;\n\n @Override\n public boolean equals(Object o) {\n if (!(o instanceof ColorPoint)) return false; // ❌ Problem!\n ColorPoint cp = (ColorPoint) o;\n return super.equals(o) && color.equals(cp.color);\n }\n}\n\n// Symmetry violation:\nPoint p = new Point(1, 2);\nColorPoint cp = new ColorPoint(1, 2, Color.RED);\n\np.equals(cp); // true (Point sees it as equal)\ncp.equals(p); // false (ColorPoint rejects plain Point)\n// ❌ SYMMETRY VIOLATED!\n```\n\n**The fix - use composition instead of inheritance:**\n\n```java\n// ✅ CORRECT: Composition preserves equals contract\npublic class ColorPoint {\n private final Point point;\n private final Color color;\n\n public ColorPoint(int x, int y, Color color) {\n this.point = new Point(x, y);\n this.color = color;\n }\n\n @Override\n public boolean equals(Object o) {\n if (!(o instanceof ColorPoint)) return false;\n ColorPoint cp = (ColorPoint) o;\n return point.equals(cp.point) && color.equals(cp.color);\n }\n\n // Provide access to Point if needed\n public Point asPoint() {\n return new Point(point.x, point.y);\n }\n}\n```\n\n### 2. The hashCode() Contract\n\n```java\n// ✅ The hashCode() Contract\n\n// 1. CONSISTENCY: Same object → same hashCode (if not modified)\nint hash1 = obj.hashCode();\nint hash2 = obj.hashCode();\nassertThat(hash1).isEqualTo(hash2);\n\n// 2. EQUALS IMPLIES SAME HASH: x.equals(y) ⟹ x.hashCode() == y.hashCode()\n// This is CRITICAL for HashMap/HashSet!\nif (x.equals(y)) {\n assertThat(x.hashCode()).isEqualTo(y.hashCode());\n}\n\n// 3. DIFFERENT HASH IMPLIES NOT EQUALS (contrapositive)\n// If hashes differ, objects cannot be equal\nif (x.hashCode() != y.hashCode()) {\n assertThat(x.equals(y)).isFalse(); // Must be false\n}\n\n// NOTE: Same hash does NOT imply equals!\n// Different objects CAN have the same hashCode (collision)\n```\n\n**Why 31 as the multiplier?**\n\n```java\n// ✅ Standard hashCode pattern\n@Override\npublic int hashCode() {\n int result = 17; // Non-zero starting value\n result = 31 * result + field1.hashCode();\n result = 31 * result + field2.hashCode();\n result = 31 * result + intField;\n return result;\n}\n```\n\nWhy 31?\n- **Odd prime**: Primes give better distribution than even numbers\n- **One less than power of 2**: `31 * x` = `(x << 5) - x` (fast bit shift optimization)\n- **Good distribution**: Empirically produces fewer collisions for string-like data\n\n```text\n31 in binary: 11111\n\n31 * x = (32 * x) - x = (x << 5) - x\n\nJVM can optimize this multiplication to bit operations!\n```\n\n### 3. The Relationship: equals() and hashCode()\n\n```text\n┌─────────────────────────────────────────────────────────────────┐\n│ THE GOLDEN RULE │\n├─────────────────────────────────────────────────────────────────┤\n│ │\n│ If you override equals(), you MUST override hashCode() │\n│ │\n│ ┌──────────────────┐ ┌────────────────────────────┐ │\n│ │ a.equals(b) TRUE │ ═══▶ │a.hashCode() == b.hashCode()│ │\n│ └──────────────────┘ └────────────────────────────┘ │\n│ (implies) (MUST be true) │\n│ │\n│ ┌────────────────────────────┐ ┌────────────────────┐ │\n│ │a.hashCode() != b.hashCode()│ ═▶ │ a.equals(b) FALSE │ │\n│ └────────────────────────────┘ └────────────────────┘ │\n│ (different hashes) (MUST be false) │\n│ │\n│ BUT: │\n│ ┌────────────────────────────┐ ┌────────────────────┐ │\n│ │a.hashCode() == b.hashCode()│ │ a.equals(b) ??? │ │\n│ └────────────────────────────┘ └────────────────────┘ │\n│ (same hash) (could be true OR false) │\n│ (this is called collision) │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n### 4. What Happens When You Break the Contract\n\n```java\n// ❌ BROKEN: equals() without hashCode()\npublic class BrokenPerson {\n private String name;\n private int age;\n\n @Override\n public boolean equals(Object o) {\n if (!(o instanceof BrokenPerson)) return false;\n BrokenPerson p = (BrokenPerson) o;\n return Objects.equals(name, p.name) && age == p.age;\n }\n\n // ❌ No hashCode() override - uses Object.hashCode() (memory address)\n}\n\n// The disaster:\nSet people = new HashSet<>();\nBrokenPerson alice1 = new BrokenPerson(\"Alice\", 30);\nBrokenPerson alice2 = new BrokenPerson(\"Alice\", 30);\n\nalice1.equals(alice2); // true - they are \"equal\"\n\npeople.add(alice1);\npeople.add(alice2);\n\npeople.size(); // 2! Both are in the set!\n// HashSet uses hashCode first - different addresses = different buckets\n// equals() is never even called!\n\npeople.contains(new BrokenPerson(\"Alice\", 30)); // false!\n// Again, different hashCode = different bucket = not found\n```\n\n### 5. Implementing equals() and hashCode() Correctly\n\n**The Standard Pattern:**\n\n```java\npublic class Employee {\n private final Long id;\n private final String email;\n private String name; // Mutable - NOT in equals/hashCode\n private int salary; // Mutable - NOT in equals/hashCode\n\n @Override\n public boolean equals(Object o) {\n // 1. Same reference? Quick true.\n if (this == o) return true;\n\n // 2. Null or different class? Quick false.\n if (o == null || getClass() != o.getClass()) return false;\n\n // 3. Cast and compare fields\n Employee employee = (Employee) o;\n return Objects.equals(id, employee.id) &&\n Objects.equals(email, employee.email);\n }\n\n @Override\n public int hashCode() {\n return Objects.hash(id, email);\n }\n}\n```\n\n**Why `getClass()` instead of `instanceof`?**\n\n```java\n// ✅ getClass() - Strict type equality\nif (o == null || getClass() != o.getClass()) return false;\n// Employee.equals(Manager) → false, even if Manager extends Employee\n\n// ⚠️ instanceof - Allows subclass comparison\nif (!(o instanceof Employee)) return false;\n// Employee.equals(Manager) → might be true\n// This can break symmetry (see Point/ColorPoint example above)\n```\n\nRule of thumb:\n- Use `getClass()` for concrete classes (most cases)\n- Use `instanceof` only when explicitly designed for inheritance\n\n### 6. Modern Alternatives\n\n**Java Records (Java 16+):**\n\n```java\n// ✅ Records automatically implement equals/hashCode correctly\npublic record Person(String name, int age) {\n // Compiler generates:\n // - equals() comparing all components\n // - hashCode() based on all components\n // - toString() with all components\n}\n\nPerson p1 = new Person(\"Alice\", 30);\nPerson p2 = new Person(\"Alice\", 30);\np1.equals(p2); // true\np1.hashCode() == p2.hashCode(); // true\n```\n\n**Lombok @EqualsAndHashCode:**\n\n```java\n// ✅ Lombok generates equals/hashCode\n@EqualsAndHashCode\npublic class User {\n private Long id;\n private String email;\n\n @EqualsAndHashCode.Exclude // Exclude from equals/hashCode\n private String displayName;\n}\n\n// ⚠️ PITFALL: With inheritance\n@EqualsAndHashCode(callSuper = true) // Must include parent fields!\npublic class AdminUser extends User {\n private Set permissions;\n}\n\n// ❌ Without callSuper, parent fields are ignored!\n```\n\n**IDE-Generated:**\n\n```java\n// IntelliJ IDEA: Right-click → Generate → equals() and hashCode()\n// Eclipse: Source → Generate hashCode() and equals()\n\n// ✅ Generally correct, but review for:\n// - Are all included fields truly part of identity?\n// - Are all included fields immutable?\n// - Do we need getClass() or instanceof?\n```\n\n### 7. Comparable and Comparator\n\n**The Comparable Contract:**\n\n```java\npublic interface Comparable {\n int compareTo(T o);\n // Returns: negative (this < o), zero (this == o), positive (this > o)\n}\n\n// ✅ Contract properties:\n// 1. ANTISYMMETRIC: sgn(x.compareTo(y)) == -sgn(y.compareTo(x))\n// 2. TRANSITIVE: x.compareTo(y) > 0 && y.compareTo(z) > 0 ⟹ x.compareTo(z) > 0\n// 3. CONSISTENT: x.compareTo(y) == 0 ⟹ sgn(x.compareTo(z)) == sgn(y.compareTo(z))\n\n// ⚠️ STRONGLY RECOMMENDED:\n// (x.compareTo(y) == 0) == x.equals(y)\n// This is \"consistent with equals\"\n```\n\n**Why \"consistent with equals\" matters:**\n\n```java\n// ❌ Inconsistent: compareTo returns 0, but equals returns false\npublic class BadBigDecimal {\n // BigDecimal actually has this issue!\n}\n\nBigDecimal a = new BigDecimal(\"1.0\");\nBigDecimal b = new BigDecimal(\"1.00\");\n\na.equals(b); // false! Different scale\na.compareTo(b); // 0! Same numeric value\n\n// The problem with TreeSet:\nSet hashSet = new HashSet<>();\nhashSet.add(a);\nhashSet.add(b);\nhashSet.size(); // 2 (HashSet uses equals)\n\nSet treeSet = new TreeSet<>();\ntreeSet.add(a);\ntreeSet.add(b);\ntreeSet.size(); // 1 (TreeSet uses compareTo)!\n```\n\n**Implementing Comparable:**\n\n```java\npublic class Employee implements Comparable {\n private String lastName;\n private String firstName;\n private int salary;\n\n // ✅ Natural ordering: by last name, then first name\n @Override\n public int compareTo(Employee other) {\n int lastNameComp = this.lastName.compareTo(other.lastName);\n if (lastNameComp != 0) return lastNameComp;\n\n return this.firstName.compareTo(other.firstName);\n }\n\n // ✅ Or use Comparator.comparing (cleaner)\n private static final Comparator NATURAL_ORDER =\n Comparator.comparing(Employee::getLastName)\n .thenComparing(Employee::getFirstName);\n\n @Override\n public int compareTo(Employee other) {\n return NATURAL_ORDER.compare(this, other);\n }\n}\n```\n\n**Comparator for flexible sorting:**\n\n```java\n// ✅ Multiple sort orders without modifying the class\nComparator bySalary = Comparator.comparing(Employee::getSalary);\nComparator bySalaryDesc = bySalary.reversed();\nComparator byNameThenSalary =\n Comparator.comparing(Employee::getLastName)\n .thenComparing(Employee::getFirstName)\n .thenComparing(Employee::getSalary);\n\n// With null handling\nComparator byManagerNullsLast =\n Comparator.comparing(Employee::getManager,\n Comparator.nullsLast(Comparator.naturalOrder()));\n\n// Usage\nemployees.sort(bySalary);\nCollections.sort(employees, byNameThenSalary);\nTreeSet sorted = new TreeSet<>(bySalaryDesc);\n```\n\n---\n\n## ⚠️ Common Mistakes\n\n### Mistake 1: Mutable Fields in equals/hashCode\n\n❌ **Problem:**\n```java\npublic class Product {\n private Long id;\n private BigDecimal price; // Changes over time!\n\n @Override\n public boolean equals(Object o) {\n // ...\n return Objects.equals(id, p.id) &&\n Objects.equals(price, p.price); // ❌ Mutable!\n }\n\n @Override\n public int hashCode() {\n return Objects.hash(id, price); // ❌ Mutable!\n }\n}\n\n// Object in HashMap, price changes → object \"lost\"\n```\n\n✅ **Solution:**\n```java\n@Override\npublic boolean equals(Object o) {\n if (!(o instanceof Product)) return false;\n Product p = (Product) o;\n return Objects.equals(id, p.id); // ✅ Only immutable ID\n}\n\n@Override\npublic int hashCode() {\n return Objects.hash(id); // ✅ Only immutable ID\n}\n```\n\n---\n\n### Mistake 2: Using == for Object Comparison\n\n❌ **Problem:**\n```java\n@Override\npublic boolean equals(Object o) {\n if (!(o instanceof Person)) return false;\n Person p = (Person) o;\n return name == p.name && age == p.age; // ❌ == for String!\n}\n// new Person(\"Alice\", 30).equals(new Person(\"Alice\", 30)) → false!\n```\n\n✅ **Solution:**\n```java\nreturn Objects.equals(name, p.name) && age == p.age;\n// Or: name.equals(p.name) after null check\n```\n\n---\n\n### Mistake 3: Forgetting Null Handling\n\n❌ **Problem:**\n```java\n@Override\npublic boolean equals(Object o) {\n Person p = (Person) o; // ❌ NullPointerException if o is null!\n return name.equals(p.name); // ❌ NPE if name is null!\n}\n```\n\n✅ **Solution:**\n```java\n@Override\npublic boolean equals(Object o) {\n if (this == o) return true;\n if (o == null || getClass() != o.getClass()) return false; // ✅ Null check\n Person p = (Person) o;\n return Objects.equals(name, p.name); // ✅ Null-safe comparison\n}\n```\n\n---\n\n### Mistake 4: Inconsistent Fields in equals vs hashCode\n\n❌ **Problem:**\n```java\n@Override\npublic boolean equals(Object o) {\n return Objects.equals(id, p.id) &&\n Objects.equals(name, p.name); // Uses id AND name\n}\n\n@Override\npublic int hashCode() {\n return Objects.hash(id); // ❌ Only uses id!\n}\n\n// Two persons with same ID but different names:\n// equals() returns false, but hashCode() is same\n// This WORKS but has poor performance (unnecessary collisions)\n```\n\n✅ **Solution:**\n```java\n// Use exactly the same fields in both methods\n@Override\npublic boolean equals(Object o) {\n return Objects.equals(id, p.id); // Only id\n}\n\n@Override\npublic int hashCode() {\n return Objects.hash(id); // Only id\n}\n```\n\n---\n\n### Mistake 5: Breaking Symmetry with Inheritance\n\n❌ **Problem:**\n```java\npublic class Animal {\n private String name;\n\n @Override\n public boolean equals(Object o) {\n if (!(o instanceof Animal)) return false; // Accepts subclasses\n Animal a = (Animal) o;\n return Objects.equals(name, a.name);\n }\n}\n\npublic class Dog extends Animal {\n private String breed;\n\n @Override\n public boolean equals(Object o) {\n if (!(o instanceof Dog)) return false; // Rejects parent!\n Dog d = (Dog) o;\n return super.equals(o) && Objects.equals(breed, d.breed);\n }\n}\n\nAnimal a = new Animal(\"Buddy\");\nDog d = new Dog(\"Buddy\", \"Labrador\");\n\na.equals(d); // true (Animal accepts Dog)\nd.equals(a); // false (Dog rejects Animal)\n// ❌ SYMMETRY VIOLATED!\n```\n\n✅ **Solution:**\n```java\n// Option 1: Use getClass() instead of instanceof\npublic class Animal {\n @Override\n public boolean equals(Object o) {\n if (o == null || getClass() != o.getClass()) return false; // Strict\n // ...\n }\n}\n\n// Option 2: Make Animal final (no subclasses)\n\n// Option 3: Use composition instead of inheritance (see earlier example)\n```\n\n---\n\n## 🐛 Debug This: The Memory Leak\n\nThe application's memory usage grows continuously. After profiling, you find millions of `Session` objects in a `HashSet` that should have been removed:\n\n```java\npublic class Session {\n private String sessionId;\n private User user;\n private Instant lastAccess;\n\n public Session(String sessionId, User user) {\n this.sessionId = sessionId;\n this.user = user;\n this.lastAccess = Instant.now();\n }\n\n public void touch() {\n this.lastAccess = Instant.now();\n }\n\n @Override\n public boolean equals(Object o) {\n if (this == o) return true;\n if (o == null || getClass() != o.getClass()) return false;\n Session session = (Session) o;\n return Objects.equals(sessionId, session.sessionId) &&\n Objects.equals(user, session.user) &&\n Objects.equals(lastAccess, session.lastAccess);\n }\n\n @Override\n public int hashCode() {\n return Objects.hash(sessionId, user, lastAccess);\n }\n}\n\n// Usage in session manager\npublic class SessionManager {\n private Set activeSessions = new HashSet<>();\n\n public void createSession(String id, User user) {\n activeSessions.add(new Session(id, user));\n }\n\n public void touchSession(Session session) {\n session.touch(); // Updates lastAccess!\n }\n\n public void removeSession(Session session) {\n activeSessions.remove(session); // Doesn't work!\n }\n}\n```\n\n**Find the bug before reading the solution!**\n\n---\n\n**✅ Solution:**\n\nThe `lastAccess` field is mutable and included in `equals()` and `hashCode()`. When `touch()` is called:\n\n1. Session's `lastAccess` changes\n2. `hashCode()` returns different value\n3. Session is now in wrong bucket\n4. `remove()` looks in new bucket, doesn't find it\n5. Session is \"stuck\" in the old bucket → memory leak\n\n**The fix:**\n\n```java\npublic class Session {\n private final String sessionId; // Make immutable fields final\n private final User user;\n private Instant lastAccess; // Still mutable, but excluded from hash\n\n // ✅ Only include immutable identifying fields\n @Override\n public boolean equals(Object o) {\n if (this == o) return true;\n if (o == null || getClass() != o.getClass()) return false;\n Session session = (Session) o;\n return Objects.equals(sessionId, session.sessionId);\n }\n\n @Override\n public int hashCode() {\n return Objects.hash(sessionId);\n }\n}\n```\n\n---\n\n## 💻 Exercises\n\n### Exercise 1: Implement Employee equals/hashCode\n⭐⭐ Difficulty: Medium | ⏱️ Time: 15 minutes\n\n**Task:** Implement proper `equals()` and `hashCode()` for an Employee class.\n\n```java\npublic class Employee {\n private Long id; // Unique identifier, immutable\n private String email; // Unique, immutable\n private String name; // Mutable (can change)\n private Department dept; // Mutable (employee can transfer)\n private int salary; // Mutable\n\n // TODO: Implement equals() and hashCode()\n // Consider: What fields define employee identity?\n}\n```\n\n**✅ Solution:**\n\n```java\npublic class Employee {\n private final Long id;\n private final String email;\n private String name;\n private Department dept;\n private int salary;\n\n public Employee(Long id, String email, String name) {\n this.id = Objects.requireNonNull(id, \"ID cannot be null\");\n this.email = Objects.requireNonNull(email, \"Email cannot be null\");\n this.name = name;\n }\n\n @Override\n public boolean equals(Object o) {\n if (this == o) return true;\n if (o == null || getClass() != o.getClass()) return false;\n Employee employee = (Employee) o;\n // Identity is defined by ID (primary key)\n // Email is also unique but ID is simpler\n return Objects.equals(id, employee.id);\n }\n\n @Override\n public int hashCode() {\n return Objects.hash(id);\n }\n\n // Alternative: If email is the business key\n // @Override\n // public boolean equals(Object o) {\n // if (this == o) return true;\n // if (o == null || getClass() != o.getClass()) return false;\n // Employee employee = (Employee) o;\n // return Objects.equals(email, employee.email);\n // }\n //\n // @Override\n // public int hashCode() {\n // return Objects.hash(email);\n // }\n}\n```\n\n---\n\n### Exercise 2: Find the Bug\n⭐⭐⭐ Difficulty: Medium | ⏱️ Time: 15 minutes\n\n**Task:** This code has a bug in the equals/hashCode implementation. Find it and fix it.\n\n```java\npublic class CacheKey {\n private String namespace;\n private String key;\n private long version;\n\n public CacheKey(String namespace, String key, long version) {\n this.namespace = namespace;\n this.key = key;\n this.version = version;\n }\n\n @Override\n public boolean equals(Object o) {\n if (o instanceof CacheKey) {\n CacheKey other = (CacheKey) o;\n return namespace.equals(other.namespace) &&\n key.equals(other.key) &&\n version == other.version;\n }\n return false;\n }\n\n @Override\n public int hashCode() {\n return namespace.hashCode() + key.hashCode();\n }\n}\n```\n\n**✅ Solution:**\n\nThere are multiple bugs:\n\n```java\npublic class CacheKey {\n private final String namespace; // ✅ Make final\n private final String key; // ✅ Make final\n private final long version; // ✅ Make final\n\n public CacheKey(String namespace, String key, long version) {\n this.namespace = Objects.requireNonNull(namespace);\n this.key = Objects.requireNonNull(key);\n this.version = version;\n }\n\n @Override\n public boolean equals(Object o) {\n if (this == o) return true; // ✅ Bug 1: Missing reference check\n if (o == null || getClass() != o.getClass()) return false; // ✅ Bug 2: null check missing\n CacheKey other = (CacheKey) o;\n return Objects.equals(namespace, other.namespace) && // ✅ Bug 3: namespace might be null\n Objects.equals(key, other.key) &&\n version == other.version;\n }\n\n @Override\n public int hashCode() {\n // ✅ Bug 4: version not included in hashCode!\n // Bug 5: Simple addition causes more collisions than Objects.hash\n return Objects.hash(namespace, key, version);\n }\n}\n```\n\n**Bugs found:**\n1. Missing `this == o` optimization\n2. Missing null check in equals (would NPE on null argument)\n3. `namespace.equals()` would NPE if namespace is null\n4. `version` in equals but NOT in hashCode (inconsistent fields!)\n5. Using `+` instead of proper hash combination (more collisions)\n\n---\n\n### Exercise 3: Comparator Chain\n⭐⭐ Difficulty: Medium | ⏱️ Time: 10 minutes\n\n**Task:** Create comparators for sorting a list of products:\n\n```java\npublic class Product {\n private String category;\n private String name;\n private BigDecimal price;\n private Integer stock; // Can be null for \"unlimited\"\n\n // Create these comparators using Comparator.comparing():\n // 1. byCategory - alphabetically by category\n // 2. byPriceAsc - by price ascending\n // 3. byPriceDesc - by price descending\n // 4. byCategoryThenPrice - by category, then by price within category\n // 5. byStockNullsLast - by stock, with null (unlimited) at the end\n}\n```\n\n**✅ Solution:**\n\n```java\npublic class Product {\n private String category;\n private String name;\n private BigDecimal price;\n private Integer stock;\n\n // 1. By category alphabetically\n public static final Comparator byCategory =\n Comparator.comparing(Product::getCategory);\n\n // 2. By price ascending\n public static final Comparator byPriceAsc =\n Comparator.comparing(Product::getPrice);\n\n // 3. By price descending\n public static final Comparator byPriceDesc =\n Comparator.comparing(Product::getPrice).reversed();\n\n // 4. By category, then by price\n public static final Comparator byCategoryThenPrice =\n Comparator.comparing(Product::getCategory)\n .thenComparing(Product::getPrice);\n\n // 5. By stock with nulls last\n public static final Comparator byStockNullsLast =\n Comparator.comparing(Product::getStock,\n Comparator.nullsLast(Comparator.naturalOrder()));\n\n // Getters\n public String getCategory() { return category; }\n public String getName() { return name; }\n public BigDecimal getPrice() { return price; }\n public Integer getStock() { return stock; }\n}\n\n// Usage:\nList products = getProducts();\nproducts.sort(Product.byCategoryThenPrice);\n```\n\n---\n\n### Exercise 4: Value Object with Record\n⭐⭐ Difficulty: Medium | ⏱️ Time: 10 minutes\n\n**Task:** Convert this class to a Record and add validation:\n\n```java\npublic class Money {\n private BigDecimal amount;\n private String currency;\n\n // Convert to Record\n // Add validation: amount >= 0, currency is 3 uppercase letters\n // Add method: Money add(Money other)\n}\n```\n\n**✅ Solution:**\n\n```java\npublic record Money(BigDecimal amount, String currency) {\n\n // Compact constructor for validation\n public Money {\n Objects.requireNonNull(amount, \"Amount cannot be null\");\n Objects.requireNonNull(currency, \"Currency cannot be null\");\n\n if (amount.compareTo(BigDecimal.ZERO) < 0) {\n throw new IllegalArgumentException(\"Amount cannot be negative\");\n }\n\n if (!currency.matches(\"^[A-Z]{3}$\")) {\n throw new IllegalArgumentException(\n \"Currency must be 3 uppercase letters (e.g., USD, EUR)\");\n }\n }\n\n public Money add(Money other) {\n if (!this.currency.equals(other.currency)) {\n throw new IllegalArgumentException(\n \"Cannot add different currencies: \" + this.currency + \" vs \" + other.currency);\n }\n return new Money(this.amount.add(other.amount), this.currency);\n }\n\n public Money multiply(int factor) {\n return new Money(this.amount.multiply(BigDecimal.valueOf(factor)), this.currency);\n }\n}\n\n// Usage:\nMoney price = new Money(new BigDecimal(\"99.99\"), \"USD\");\nMoney shipping = new Money(new BigDecimal(\"5.00\"), \"USD\");\nMoney total = price.add(shipping); // Money[amount=104.99, currency=USD]\n\n// equals/hashCode automatically work:\nMoney a = new Money(new BigDecimal(\"10.00\"), \"EUR\");\nMoney b = new Money(new BigDecimal(\"10.00\"), \"EUR\");\na.equals(b); // true\n```\n\n---\n\n### Exercise 5: Consistent with Equals\n⭐⭐⭐⭐ Difficulty: Hard | ⏱️ Time: 20 minutes\n\n**Task:** Implement a `Version` class that is `Comparable` and consistent with `equals`:\n\n```java\npublic class Version implements Comparable {\n // Version format: major.minor.patch (e.g., \"1.2.3\")\n // \"1.0.0\" < \"1.0.1\" < \"1.1.0\" < \"2.0.0\"\n\n // Requirements:\n // 1. Parse from string \"1.2.3\"\n // 2. equals() based on major.minor.patch\n // 3. hashCode() based on major.minor.patch\n // 4. compareTo() consistent with equals\n // 5. toString() returns \"1.2.3\" format\n}\n```\n\n**✅ Solution:**\n\n```java\npublic class Version implements Comparable {\n private final int major;\n private final int minor;\n private final int patch;\n\n public Version(int major, int minor, int patch) {\n if (major < 0 || minor < 0 || patch < 0) {\n throw new IllegalArgumentException(\"Version numbers cannot be negative\");\n }\n this.major = major;\n this.minor = minor;\n this.patch = patch;\n }\n\n public static Version parse(String version) {\n Objects.requireNonNull(version, \"Version string cannot be null\");\n String[] parts = version.split(\"\\\\.\");\n if (parts.length != 3) {\n throw new IllegalArgumentException(\n \"Version must be in format major.minor.patch: \" + version);\n }\n try {\n return new Version(\n Integer.parseInt(parts[0]),\n Integer.parseInt(parts[1]),\n Integer.parseInt(parts[2])\n );\n } catch (NumberFormatException e) {\n throw new IllegalArgumentException(\"Invalid version number: \" + version, e);\n }\n }\n\n @Override\n public int compareTo(Version other) {\n // Compare major first\n int majorComp = Integer.compare(this.major, other.major);\n if (majorComp != 0) return majorComp;\n\n // Then minor\n int minorComp = Integer.compare(this.minor, other.minor);\n if (minorComp != 0) return minorComp;\n\n // Then patch\n return Integer.compare(this.patch, other.patch);\n }\n\n @Override\n public boolean equals(Object o) {\n if (this == o) return true;\n if (o == null || getClass() != o.getClass()) return false;\n Version version = (Version) o;\n return major == version.major &&\n minor == version.minor &&\n patch == version.patch;\n }\n\n @Override\n public int hashCode() {\n return Objects.hash(major, minor, patch);\n }\n\n @Override\n public String toString() {\n return major + \".\" + minor + \".\" + patch;\n }\n\n // Getters\n public int getMajor() { return major; }\n public int getMinor() { return minor; }\n public int getPatch() { return patch; }\n}\n\n// Test consistency:\nVersion v1 = Version.parse(\"1.2.3\");\nVersion v2 = Version.parse(\"1.2.3\");\nVersion v3 = Version.parse(\"1.2.4\");\n\nv1.equals(v2); // true\nv1.compareTo(v2) == 0; // true - consistent with equals!\nv1.compareTo(v3) < 0; // true - 1.2.3 < 1.2.4\n```\n\n---\n\n## 📝 Summary & Key Takeaways\n\n### The Contracts\n\n| Method | Key Properties |\n|--------|---------------|\n| equals() | Reflexive, Symmetric, Transitive, Consistent, null→false |\n| hashCode() | Consistent, equal objects→same hash |\n| compareTo() | Antisymmetric, Transitive, should be consistent with equals |\n\n### The Golden Rules\n\n1. **Override both or neither:** If you override `equals()`, override `hashCode()`\n2. **Use same fields:** Include exactly the same fields in both methods\n3. **Immutable fields only:** Never include mutable fields in hash calculations\n4. **Consistent with equals:** `compareTo()` returning 0 should mean `equals()` is true\n\n### Quick Implementation Guide\n\n```java\n// Standard pattern for equals()\n@Override\npublic boolean equals(Object o) {\n if (this == o) return true; // Quick check\n if (o == null || getClass() != o.getClass()) return false;\n MyClass that = (MyClass) o;\n return Objects.equals(field1, that.field1) &&\n Objects.equals(field2, that.field2);\n}\n\n// Standard pattern for hashCode()\n@Override\npublic int hashCode() {\n return Objects.hash(field1, field2); // Same fields as equals()\n}\n```\n\n### Modern Alternatives\n\n| Approach | When to Use |\n|----------|-------------|\n| Record | Value objects, DTOs, immutable data |\n| Lombok | Legacy classes, entities with selected fields |\n| IDE-generated | Most cases, review the output |\n| Manual | Complex inheritance, performance-critical code |\n\n---\n\n## 🎤 Senior-Level Interview Questions\n\n### Question #1: What happens if you break the hashCode contract?\n\n**What interviewers want to hear**: Understanding of how HashMap/HashSet work internally.\n\n**Strong answer**: If `equals()` returns true but `hashCode()` returns different values, objects that should be \"found\" in HashMap/HashSet won't be. The collection uses hashCode to determine which bucket to look in. If two equal objects have different hashes, they'll be in different buckets, and `contains()` or `get()` will fail even though the object is present. Additionally, you can add \"duplicates\" to a HashSet because it doesn't find the existing equal object.\n\n---\n\n### Question #2: Why shouldn't you use mutable objects as HashMap keys?\n\n**What interviewers want to hear**: Understanding of the \"lost object\" problem.\n\n**Strong answer**: If a key's hashCode changes after being added to a HashMap (because its mutable fields changed), the entry becomes \"lost.\" It's still in the map but in a bucket that no longer matches its current hashCode. `get()` with the modified key looks in the wrong bucket and returns null. `remove()` also fails. The object is stuck, causing a memory leak. Even iterating won't help because you can't remove by key. The only solution is to rebuild the entire map.\n\n---\n\n### Question #3: What's the difference between Comparable and Comparator?\n\n**What interviewers want to hear**: Understanding of natural ordering vs external comparison.\n\n**Strong answer**:\n- **Comparable** defines the natural ordering of a class. It's implemented by the class itself via `compareTo(T other)`. There's only one natural ordering per class. Example: `String` is naturally ordered alphabetically.\n\n- **Comparator** is an external comparison strategy. It's a separate object that compares two instances via `compare(T o1, T o2)`. You can have many comparators for different sort orders. Example: Sort employees by name, salary, or hire date using different Comparators.\n\nUse Comparable for the obvious/default ordering, Comparator for alternative orderings.\n\n---\n\n### Question #4: What does \"consistent with equals\" mean for Comparable?\n\n**What interviewers want to hear**: Understanding of the relationship between comparison and equality.\n\n**Strong answer**: A Comparable implementation is \"consistent with equals\" when `(x.compareTo(y) == 0) == x.equals(y)` for all objects. If two objects are equal according to `compareTo()` (returning 0), they should also be equal according to `equals()`, and vice versa.\n\nThis matters for sorted collections like TreeSet. TreeSet uses `compareTo()` for equality, not `equals()`. If they're inconsistent, TreeSet behavior differs from HashSet. Classic example: `BigDecimal` where `new BigDecimal(\"1.0\").equals(new BigDecimal(\"1.00\"))` is false (different scale), but `compareTo()` returns 0 (same numeric value).\n\n---\n\n### Question #5: How do Java Records implement equals and hashCode?\n\n**What interviewers want to hear**: Understanding of Records and automatic implementations.\n\n**Strong answer**: Records automatically generate `equals()` and `hashCode()` based on all record components (the constructor parameters). The generated `equals()` compares all components for equality using `Objects.equals()`. The generated `hashCode()` combines all components using the same algorithm as `Objects.hash()`.\n\nImportant: These implementations use ALL components. If you want to exclude certain fields from equality, you cannot use a Record - use a regular class instead. Also, record components should be immutable (or at least their identity should be), since they're all included in hashCode.\n\n---\n\n### Question #6: When can two different objects have the same hashCode?\n\n**What interviewers want to hear**: Understanding of hash collisions.\n\n**Strong answer**: Any time - this is called a hash collision and is perfectly legal. The hashCode contract only requires that *equal* objects have the same hash, not that *unequal* objects have different hashes. With only 2^32 possible int values but infinitely many possible objects, collisions are mathematically inevitable (pigeonhole principle).\n\nGood hash functions minimize collisions for better performance. Example: `\"FB\".hashCode() == \"Ea\".hashCode()` (both are 2236). HashMap handles this via chaining or tree bins for buckets with many collisions.\n\n---\n\n## 🏁 Conclusion\n\nThe `equals()` and `hashCode()` contract is fundamental to how Java collections work. Master it, and you'll:\n\n- **Avoid subtle bugs** where objects \"disappear\" from collections\n- **Prevent memory leaks** caused by stuck objects\n- **Write correct entity classes** that work properly in Sets and as Map keys\n- **Ace technical interviews** on this frequently-asked topic\n\n**Key principles to remember:**\n\n1. Always override both `equals()` and `hashCode()` together\n2. Use only immutable fields that define object identity\n3. For entities, ID/primary key is usually sufficient\n4. Consider using Records for value objects\n5. When using Comparable, keep it consistent with equals\n\n**Your next step:** Continue to Part 4 (Iterators) to understand how to traverse collections safely, or Part 12 (HashMap Internals) if you're on the Performance track.\n\n---\n\n## 📅 Review Schedule for This Article\n\n| Day | Task | Time |\n|-----|------|------|\n| Day 1 | Review the golden rules and contracts | 5 min |\n| Day 3 | Redo Exercise 1 (Employee equals/hashCode) | 15 min |\n| Day 7 | Answer interview questions without looking | 10 min |\n| Day 14 | Redo Debug This exercise (Memory Leak) | 10 min |\n| Day 30 | Review mental model and quick reference | 5 min |\n\n---\n\n*Next in series: [Part 4: Iterators, Spliterators & Iteration Patterns]*\n","featuredImage","isPublished","isFeatured","subscriptionType","BASIC","publishedAt","2026-06-10T07:19:25.852139Z","createdAt","2026-06-10T07:19:25.853004Z","updatedAt","2026-06-16T21:26:56.086200Z","readingTimeMinutes",24,"estimatedReadingTime","authorId",3,"authorUsername","tomasz_main","categoryName","Java","readingTime","seriesId",5,"seriesOrder","author",{"_31":55,"_99":57,"_100":101,"_102":103,"_104":-5,"_105":-5,"_106":-5,"_107":-5,"_108":-5},"category",{"_31":62,"_72":59,"_35":87,"_75":97,"_98":-5},"tags",[78,79,80,81,82],"series",{"_31":62,"_72":73,"_35":74,"_75":76,"_77":23},"name","Java Collections Compendium: From Fundamentals to Production Mastery","java-collections-compendium","description","A comprehensive 30-part series covering everything about Java Collections Framework. From foundational concepts like generics and equals/hashCode contract, through deep dives into ArrayList, LinkedList, HashMap, TreeMap, ConcurrentHashMap, to modern features like immutable collections, Java 21 sequenced collections, streams & collectors, and production patterns with JPA, Jackson & Spring. Includes real production stories, mental models, exercises, and 50+ interview questions.","isActive",{"_31":94,"_72":95,"_35":96},{"_31":91,"_72":92,"_35":93},{"_31":88,"_72":89,"_35":90},{"_31":86,"_72":59,"_35":87},{"_31":83,"_72":84,"_35":85},323,"Object Identity","object-identity",14,"java",321,"Hashcode","hashcode",320,"Equals","equals",322,"Contract","contract","Category for Java","colorHex","username","firstName","Tomasz","lastName","Jarosz","profilePicture","bio","website","githubUrl","linkedinUrl"]