HHH-17955 Javadoc improvements in StatelessSession

Signed-off-by: Gavin King <gavin@hibernate.org>

Author: gavinking

hibernate-core/src/main/java/org/hibernate/StatelessSession.java

@@ -35,11 +35,31 @@
  * and so an operation performed via a stateless session never cascades to
  * associated instances.
  * <p>
+ * 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.
+ * <p>
+ * Similarly, lazy association fetching is an explicit operation. A collection
+ * or proxy may be fetched by calling {@link #fetch(Object)}.
+ * <p>
  * Stateless sessions are vulnerable to data aliasing effects, due to the
  * lack of a first-level cache.
  * <p>
  * On the other hand, for certain kinds of transactions, a stateless session
  * may perform slightly faster than a stateful session.
+ * <p>
+ * Certain rules applying to stateful sessions are relaxed in a stateless
+ * session:
+ * <ul>
+ * <li>it is not necessary to discard a session and its entities after an
+ * exception is thrown by a stateless sessions, and
+ * <li>when an exception is thrown by a stateless session, the current
+ * transaction is not automatically marked for rollback.
+ * </ul>
  *
  * @author Gavin King
  */
@@ -50,7 +70,10 @@ public interface StatelessSession extends SharedSessionContract {
 void close();
 
 /**
- * Insert a row.
+ * Insert a record.
+ * <p>
+ * 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.
+ * <p>
+ * 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,29 +95,41 @@ public interface StatelessSession extends SharedSessionContract {
 Object insert(String entityName, Object entity);
 
 /**
- * Update a row.
+ * Update a record.
+ * <p>
+ * 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.
+ * <p>
+ * 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
  */
 void update(String entityName, Object entity);
 
 /**
- * Delete a row.
+ * Delete a record.
+ * <p>
+ * 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.
+ * <p>
+ * 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> T get(Class<T> 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> T get(Class<T> 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> T get(EntityGraph<T> 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.
  * <p>
  * Warning: this operation in a stateless session is quite sensitive
  * to data aliasing effects and should be used with great care.