HHH-17955 Javadoc improvements in StatelessSession

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

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.
  * <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,14 +95,20 @@ 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
@@ -84,14 +116,20 @@ public interface StatelessSession extends SharedSessionContract {
 	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.