When should a class be compared by identity (==) versus by logical equality (equals()), and how does that map to entity vs value object modeling?

## Two questions, two tools Java gives you `==` (identity: *same object?*) and `equals()` (logical equality: *same value?*). Choosing which to honor for a given class is really a **domain-modeling decision**, captured by the classic distinction between **entities** and **value objects** (from Domain-Driven Design). ## Value objects — compare by value A **value object** is defined *entirely by its attributes*. It has no identity of its own; any two instances with the same data are interchangeable. - Examples: `Money(amount, currency)`, a `LocalDate`, a `Color(r,g,b)`, a coordinate `Point(x,y)`. - `Money(5, USD)` is the *same* as any other `Money(5, USD)` — you'd never care *which* object you hold. For value objects you should **override `equals()` and `hashCode()`** to compare by state, and ideally make them **immutable** (so their identity-vs-value question can never drift). Java **records** do exactly this automatically: ```java record Money(BigDecimal amount, Currency currency) {} // equals/hashCode/toString generated from the components ``` ## Entities — compare by identity An **entity** has an identity that is *independent of its attributes* and persists over time and state changes. - A `User` is the same user before and after changing its name, email, or password. - Two `User` objects representing **different people** must **never** be equal, even if every current field happens to match (two people both named "Jane Doe"). So an entity's notion of "same" is **identity**, not field-by-field value. Concretely: - **In-memory, transient** entities are often left with the **default identity `equals()`** (`==`), which is correct: each object *is* its own identity. - **Persistent** entities (e.g. JPA) are usually compared by a **stable business key or surrogate id**, because the same database row may be loaded into different object instances across sessions, and you want those to be "equal". Comparing *all* fields is wrong (mutable fields change), and using the auto-generated id naively is risky before it's assigned. ## Why getting it wrong hurts Hash-based and sorted collections rely on `equals()`/`hashCode()`: 1. **Value object with default (identity) equals()** → two logically-equal instances are treated as different, so a `HashMap` lookup with a freshly-built key *misses*, and a `HashSet` stores duplicates. 2. **Entity with naive value-based equals() over all fields** → two distinct real-world entities with coincidentally-equal fields **collide** (one disappears from a `Set`), and an entity's hash **changes** when a mutable field changes, corrupting its position in a hash structure (the "mutable key" hazard). ## How Java nudges you - **Records** = built-in value semantics → reach for them for value objects. - **Enums** are singletons; comparing them with `==` is both correct and idiomatic (each constant is a unique identity). - **JPA/Hibernate** guidance: implement `equals`/`hashCode` on a stable key, not on all mutable fields, precisely because an entity's equality is about identity, not current state. ## Decision checklist - *Is the object interchangeable with any other holding the same data?* → **value object**, override `equals()`/`hashCode()`, prefer immutable / a record. - *Does it have a lifecycle and a distinct identity regardless of its fields?* → **entity**, compare by identity or a stable id, not by all fields. - *Do I literally need "the same object"?* (caching, sentinels, enums) → use `==`.