diff --git a/hibernate-core/src/main/java/org/hibernate/StatelessSession.java b/hibernate-core/src/main/java/org/hibernate/StatelessSession.java index b001025e7f..1538fd2703 100644 --- a/hibernate-core/src/main/java/org/hibernate/StatelessSession.java +++ b/hibernate-core/src/main/java/org/hibernate/StatelessSession.java @@ -35,11 +35,31 @@ import org.hibernate.graph.GraphSemantic; * and so an operation performed via a stateless session never cascades to * associated instances. *

+ * The basic operations of a stateless session are {@link #get(Class, Object)}, + * {@link #insert(Object)}, {@link #update(Object)}, {@link #delete(Object)}, + * and {@link #upsert(Object)}. These operations are always performed + * synchronously, resulting in immediate access to the database. Notice that + * update is an explicit operation. There is no "flush" operation for a + * stateless session, and so modifications to entities are never automatically + * detected and made persistent. + *

+ * Similarly, lazy association fetching is an explicit operation. A collection + * or proxy may be fetched by calling {@link #fetch(Object)}. + *

* Stateless sessions are vulnerable to data aliasing effects, due to the * lack of a first-level cache. *

* On the other hand, for certain kinds of transactions, a stateless session * may perform slightly faster than a stateful session. + *

+ * Certain rules applying to stateful sessions are relaxed in a stateless + * session: + *

* * @author Gavin King */ @@ -50,7 +70,10 @@ public interface StatelessSession extends SharedSessionContract { void close(); /** - * Insert a row. + * Insert a record. + *

+ * The {@link jakarta.persistence.PostPersist} callback will be + * triggered if the operation is successful. * * @param entity a new transient instance * @@ -59,7 +82,10 @@ public interface StatelessSession extends SharedSessionContract { Object insert(Object entity); /** - * Insert a row. + * Insert a record. + *

+ * The {@link jakarta.persistence.PostPersist} callback will be + * triggered if the operation is successful. * * @param entityName The entityName for the entity to be inserted * @param entity a new transient instance @@ -69,14 +95,20 @@ public interface StatelessSession extends SharedSessionContract { Object insert(String entityName, Object entity); /** - * Update a row. + * Update a record. + *

+ * The {@link jakarta.persistence.PostUpdate} callback will be + * triggered if the operation is successful. * * @param entity a detached entity instance */ void update(Object entity); /** - * Update a row. + * Update a record. + *

+ * The {@link jakarta.persistence.PostUpdate} callback will be + * triggered if the operation is successful. * * @param entityName The entityName for the entity to be updated * @param entity a detached entity instance @@ -84,14 +116,20 @@ public interface StatelessSession extends SharedSessionContract { void update(String entityName, Object entity); /** - * Delete a row. + * Delete a record. + *

+ * The {@link jakarta.persistence.PostRemove} callback will be + * triggered if the operation is successful. * * @param entity a detached entity instance */ void delete(Object entity); /** - * Delete a row. + * Delete a record. + *

+ * The {@link jakarta.persistence.PostRemove} callback will be + * triggered if the operation is successful. * * @param entityName The entityName for the entity to be deleted * @param entity a detached entity instance @@ -122,7 +160,7 @@ public interface StatelessSession extends SharedSessionContract { void upsert(String entityName, Object entity); /** - * Retrieve a row. + * Retrieve a record. * * @param entityName The name of the entity to retrieve * @param id The id of the entity to retrieve @@ -132,7 +170,7 @@ public interface StatelessSession extends SharedSessionContract { Object get(String entityName, Object id); /** - * Retrieve a row. + * Retrieve a record. * * @param entityClass The class of the entity to retrieve * @param id The id of the entity to retrieve @@ -142,7 +180,7 @@ public interface StatelessSession extends SharedSessionContract { T get(Class entityClass, Object id); /** - * Retrieve a row, obtaining the specified lock mode. + * Retrieve a record, obtaining the specified lock mode. * * @param entityName The name of the entity to retrieve * @param id The id of the entity to retrieve @@ -153,7 +191,7 @@ public interface StatelessSession extends SharedSessionContract { Object get(String entityName, Object id, LockMode lockMode); /** - * Retrieve a row, obtaining the specified lock mode. + * Retrieve a record, obtaining the specified lock mode. * * @param entityClass The class of the entity to retrieve * @param id The id of the entity to retrieve @@ -164,7 +202,7 @@ public interface StatelessSession extends SharedSessionContract { T get(Class entityClass, Object id, LockMode lockMode); /** - * Retrieve a row, fetching associations specified by the + * Retrieve a record, fetching associations specified by the * given {@link EntityGraph}. * * @param graph The {@link EntityGraph} @@ -179,7 +217,7 @@ public interface StatelessSession extends SharedSessionContract { T get(EntityGraph graph, GraphSemantic graphSemantic, Object id); /** - * Retrieve a row, fetching associations specified by the + * Retrieve a record, fetching associations specified by the * given {@link EntityGraph}, and obtaining the specified * lock mode. * @@ -228,7 +266,7 @@ public interface StatelessSession extends SharedSessionContract { void refresh(String entityName, Object entity, LockMode lockMode); /** - * Fetch an association that's configured for lazy loading. + * Fetch an association or collection that's configured for lazy loading. *

* Warning: this operation in a stateless session is quite sensitive * to data aliasing effects and should be used with great care.