From a48aad56c1aef5d225068dd81b41c0ece69a9159 Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Wed, 26 Mar 2025 13:47:22 +0100
Subject: [PATCH] discuss persistent identity in the javadoc

---
 .../src/main/java/org/hibernate/Session.java     | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/hibernate-core/src/main/java/org/hibernate/Session.java b/hibernate-core/src/main/java/org/hibernate/Session.java
index 1aaa7abe3f3c..6bb79f3e6348 100644
--- a/hibernate-core/src/main/java/org/hibernate/Session.java
+++ b/hibernate-core/src/main/java/org/hibernate/Session.java
@@ -44,7 +44,17 @@
  *     {@code Session}.
  * </ul>
  * <p>
- * At any given time, an instance may be associated with at most one open session.
+ * Each persistent instance has a <em>persistent identity</em> determined by its type
+ * and identifier value. There may be at most one persistent instance with a given
+ * persistent identity associated with a given session. Normally, a persistent identity
+ * is assigned when an {@linkplain #persist(Object) instance is made persistent}, but
+ * when the entity identifier is {@linkplain org.hibernate.generator.OnExecutionGenerator
+ * generated by the database}, assignment of the persistent identity is delayed until
+ * the state of the entity is actually inserted in the database.
+ * <p>
+ * An instance of an entity class may be associated with at most one open session.
+ * Distinct sessions represent state with the same persistent identity using distinct
+ * persistent instances of the mapped entity class.
  * <p>
  * Any instance returned by {@link #get(Class, Object)}, {@link #find(Class, Object)},
  * or by a query is persistent. A persistent instance might hold references to other
@@ -59,8 +69,8 @@
  * <p>
  * A transient instance may be made persistent by calling {@link #persist(Object)}.
  * A persistent instance may be made detached by calling {@link #detach(Object)}.
- * A persistent instance may be marked for removal, and eventually made transient, by
- * calling {@link #remove(Object)}.
+ * A persistent instance may be marked for removal, and eventually made transient,
+ * by calling {@link #remove(Object)}.
  * <p>
  * Persistent instances are held in a managed state by the persistence context. Any
  * change to the state of a persistent instance is automatically detected and eventually