From e3076966c7b85a64e5969f5eb77e34e5a744a5d9 Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Wed, 13 Mar 2024 22:45:24 +0100
Subject: [PATCH] even more javadoc for Expectation

---
 .../java/org/hibernate/jdbc/Expectation.java  | 62 ++++++++++++++-----
 1 file changed, 48 insertions(+), 14 deletions(-)

diff --git a/hibernate-core/src/main/java/org/hibernate/jdbc/Expectation.java b/hibernate-core/src/main/java/org/hibernate/jdbc/Expectation.java
index 9f9e6be9d6..2ce11631cb 100644
--- a/hibernate-core/src/main/java/org/hibernate/jdbc/Expectation.java
+++ b/hibernate-core/src/main/java/org/hibernate/jdbc/Expectation.java
@@ -49,46 +49,78 @@ import static org.hibernate.jdbc.Expectations.toCallableStatement;
 public interface Expectation {
 
 	/**
-	 * Is it acceptable to combine this expectation with statement batching?
+	 * Is it acceptable to combine this expectation with JDBC
+	 * {@linkplain PreparedStatement#executeBatch() statement batching}?
+	 * If this method returns {@code false}, the use of batch updates
+	 * is disabled.
 	 *
-	 * @return True if batching can be combined with this expectation; false otherwise.
+	 * @return True if batching can be combined with this expectation;
+	 *         false otherwise.
+	 *
+	 * @see PreparedStatement#executeBatch()
 	 */
 	default boolean canBeBatched() {
 		return true;
 	}
 
 	/**
-	 * The number of parameters this expectation implies.  E.g.,
-	 * {@link OutParameter} requires a single OUT parameter for
-	 * reading back the number of affected rows.
+	 * The number of JDBC parameters this expectation uses. For example,
+	 * {@link OutParameter} requires a single OUT parameter for reading
+	 * back the number of affected rows.
 	 */
 	default int getNumberOfParametersUsed() {
 		return 0;
 	}
 
 	/**
-	 * Perform verification of the outcome of the RDBMS operation based on
-	 * the type of expectation defined.
+	 * Perform verification of the outcome of the JDBC operation based
+	 * on the type of expectation defined, after execution of the given
+	 * {@link PreparedStatement}. When a SQL statement is executed via
+	 * {@link PreparedStatement#executeUpdate()}, {@code verifyOutcome()}
+	 * is called exactly once. When {@link PreparedStatement#executeBatch()}
+	 * is used to execute a batch update, this method is called once for
+	 * each element of the batch.
+	 * <ul>
+	 * <li>The argument to {@code rowCount} is usually the number of
+	 *     table rows affected by execution of the SQL statement via
+	 *     {@code executeUpdate()}. However, in the case where
+	 *     {@code executeBatch()} is used to execute a batch update,
+	 *     it might be {@link PreparedStatement#EXECUTE_FAILED} or
+	 *     {@link PreparedStatement#SUCCESS_NO_INFO}.
+	 * <li>The argument to {@code batchPosition} is negative unless
+	 *     {@code executeBatch()} is used to execute a batch update,
+	 *     in which case it is the position within the batch of the
+	 *     row count being verified.
+	 * </ul>
 	 *
-	 * @param rowCount The RDBMS reported "number of rows affected".
+	 * @param rowCount The RDBMS reported "number of rows affected"
 	 * @param statement The statement representing the operation
-	 * @param batchPosition The position in the batch (if batching)
-	 * @param sql The SQL backing the prepared statement, for logging purposes
-	 * @throws SQLException Exception from the JDBC driver
+	 * @param batchPosition The position in the batch (if batching),
+	 *                      or {@code -1} if not part of a batch
+	 * @param sql The SQL backing the prepared statement, for error
+	 *            reporting and logging purposes
+	 * @throws SQLException Exception from the JDBC driver.
 	 * @throws HibernateException Problem processing the outcome.
+	 *
+	 * @see PreparedStatement#executeUpdate()
+	 * @see PreparedStatement#executeBatch()
 	 */
 	void verifyOutcome(int rowCount, PreparedStatement statement, int batchPosition, String sql)
 			throws SQLException, HibernateException;
 
 	/**
-	 * Perform any special statement preparation.
+	 * Perform any special statement preparation, for example,
+	 * registration of OUT parameters.
 	 *
 	 * @param statement The statement to be prepared
 	 * @return The number of bind positions consumed (if any)
 	 * @throws SQLException Exception from the JDBC driver
 	 * @throws HibernateException Problem performing preparation.
+	 *
+	 * @see CallableStatement#registerOutParameter(int, int)
 	 */
-	default int prepare(PreparedStatement statement) throws SQLException, HibernateException {
+	default int prepare(PreparedStatement statement)
+			throws SQLException, HibernateException {
 		return 0;
 	}
 
@@ -96,7 +128,9 @@ public interface Expectation {
 	 * Check that this implementation is compatible with the kind of
 	 * {@link PreparedStatement} it will be called with. Implementors
 	 * should throw a {@link MappingException} if the configuration
-	 * is not supported.
+	 * is not supported. This operation is called when Hibernate
+	 * starts up, so that incompatibilities are detected and reported
+	 * as early as possible.
 	 *
 	 * @param callable true if this {@code Expectation} will be called
 	 *                 with a {@link CallableStatement}.