Why does Hibernate insist that a composite identifier class implement equals() and hashCode(), and what concretely goes wrong at runtime when the implementation is missing, incomplete, or based on mutable state?

## Where equality is used A persistence context is fundamentally a `Map<EntityKey, Object>`, where `EntityKey` combines the entity name and the identifier value. Everything that has to answer "do I already have this row?" goes through that map: - `find()` / `getReference()` — first-level cache lookup before hitting the database. - Loading a `@ManyToOne` — resolving the target by id. - `merge()` — locating the managed copy for a detached instance. - Flush-time deduplication and cascade traversal. - Second-level cache and query cache — the cached region is keyed by identifier. With a simple `@Id Long id`, `Long.equals` and `Long.hashCode` do the right thing and nobody thinks about it. With a composite key, **you** supply the equality contract, and Hibernate is only as correct as your implementation. ## Failure modes **Missing implementation (identity equality).** Every freshly constructed key is unequal to every other, so the identity map never hits: ```java OrderLine a = em.find(OrderLine.class, new OrderLineId(1L, 2L)); // SELECT OrderLine b = em.find(OrderLine.class, new OrderLineId(1L, 2L)); // SELECT again a == b; // false — two managed instances for one row ``` That second instance is the dangerous part: two managed objects representing one row can both be dirty, producing conflicting UPDATEs at flush, and `merge` of a detached copy may raise `NonUniqueObjectException`. It also makes `hashCode`-based collections in your own code behave unpredictably. **Partial implementation.** Comparing only `orderId` and ignoring `productId` makes distinct rows equal. Now the identity map returns the *wrong* entity for a key, `@ElementCollection` sets collapse elements, and second-level cache entries shadow each other — a silent data-corruption class of bug, far worse than the extra-SELECT case. **Mutable key state.** If a key attribute changes after the object has been placed in a hash map — including Hibernate's internal maps — its bucket no longer matches its hash, so lookups miss even though `equals` would return true. Concretely: `line.getId().setProductId(99)` after `persist` leaves the persistence context indexing the entity under the old hash while the database row still carries the old PK. Hibernate does not support changing a primary key; a key change is a delete plus an insert. **hashCode inconsistent with equals.** Any pair where `a.equals(b)` but `a.hashCode() != b.hashCode()` breaks every hash structure. Generated code from an IDE is fine as long as you generate both from the same field set. ## Writing it correctly ```java @Embeddable public class OrderLineId implements Serializable { @Column(name = "order_id") private Long orderId; @Column(name = "product_id") private Long productId; protected OrderLineId() {} public OrderLineId(Long orderId, Long productId) { this.orderId = Objects.requireNonNull(orderId); this.productId = Objects.requireNonNull(productId); } @Override public boolean equals(Object o) { if (this == o) return true; if (!(o instanceof OrderLineId that)) return false; return Objects.equals(orderId, that.orderId) && Objects.equals(productId, that.productId); } @Override public int hashCode() { return Objects.hash(orderId, productId); } } ``` Checklist: all key attributes included; `Serializable`; no-arg constructor (may be `protected`) for the provider; no setters, so the key is effectively immutable; `getClass()` or a pattern-matching `instanceof` — be aware that a strict `getClass()` check is safest for id classes because they are never proxied, unlike entities. On Hibernate 6 a **Java record** is a legal `@EmbeddedId` type and gives you a correct `equals`/`hashCode`, immutability, and a canonical constructor for free — the tidiest option when your toolchain allows it. ## Related but distinct Equality of the *entity* itself (whether `OrderLine.equals` should compare ids or business keys) is a separate discussion; here the contract is narrower and non-negotiable: the identifier class must behave like a value with structural equality over the full key.