Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

talk about lock() and refresh() in javadoc preamble for Session 

Signed-off-by: Gavin King <gavin@hibernate.org>
This commit is contained in:
Gavin King 2024-04-18 10:20:36 +02:00
parent 5948ad1245
commit e0e603a072
1 changed files with 18 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
hibernate-core/src/main/java/org/hibernate/Session.java
View File

@ -11,6 +11,7 @@ import java.util.function.Consumer;
import jakarta.persistence.CacheRetrieveMode;
import jakarta.persistence.CacheStoreMode;
import jakarta.persistence.LockModeType;
import jakarta.persistence.PessimisticLockScope;
import org.hibernate.graph.RootGraph;
import org.hibernate.jdbc.Work;
@ -75,6 +76,9 @@ import jakarta.persistence.criteria.CriteriaUpdate;
* detached instance to the persistent state are now deprecated, and clients should now
* migrate to the use of {@code merge()}.
* <p>
* The persistent state of a managed entity may be refreshed from the database, discarding
* all modifications to the object held in memory, by calling {@link #refresh(Object)}.
* <p>
* From {@linkplain FlushMode time to time}, a {@linkplain #flush() flush operation} is
* triggered, and the session synchronizes state held in memory with persistent state
* held in the database by executing SQL {@code insert}, {@code update}, and {@code delete}
@ -82,6 +86,20 @@ import jakarta.persistence.criteria.CriteriaUpdate;
* of the {@code Session} interface. If synchronous execution of SQL is desired, the
* {@link StatelessSession} allows this.
* <p>
* Each managed instance has an associated {@link LockMode}. By default, the session
* obtains only {@link LockMode#READ} on an entity instance it reads from the database
* and {@link LockMode#WRITE} on an entity instance it writes to the database. This
* behavior is appropriate for programs which use optimistic locking.
* <ul>
* <li>A different lock level may be obtained by explicitly specifying the mode using
* {@link #get(Class, Object, LockMode)}, {@link #find(Class, Object, LockModeType)},
* {@link #refresh(Object, LockMode)}, {@link #refresh(Object, LockModeType)}, or
* {@link org.hibernate.query.SelectionQuery#setLockMode(LockModeType)}.
* <li>The lock level of a managed instance already held by the session may be upgraded
* to a more restrictive lock level by calling {@link #lock(Object, LockMode)} or
* {@link #lock(Object, LockModeType)}.
* </ul>
* <p>
* A persistence context holds hard references to all its entities and prevents them
* from being garbage collected. Therefore, a {@code Session} is a short-lived object,
* and must be discarded as soon as a logical transaction ends. In extreme cases,