Document JDBC driver requirement for KeyHolder-based update methods

Closes gh-31486

Author: jhoeller

spring-jdbc/src/main/java/org/springframework/jdbc/core/JdbcOperations.java

@@ -933,12 +933,14 @@ <T> List<T> queryForList(String sql, Object[] args, int[] argTypes, Class<T> ele
 	 * <p>Note that the given PreparedStatementCreator has to create a statement
 	 * with activated extraction of generated keys (a JDBC 3.0 feature). This can
 	 * either be done directly or through using a PreparedStatementCreatorFactory.
+	 * <p>This method requires support for generated keys in the JDBC driver.
 	 * @param psc a callback that provides SQL and any necessary parameters
 	 * @param generatedKeyHolder a KeyHolder that will hold the generated keys
 	 * @return the number of rows affected
 	 * @throws DataAccessException if there is any problem issuing the update
 	 * @see PreparedStatementCreatorFactory
 	 * @see org.springframework.jdbc.support.GeneratedKeyHolder
+	 * @see java.sql.DatabaseMetaData#supportsGetGeneratedKeys()
 	 */
 	int update(PreparedStatementCreator psc, KeyHolder generatedKeyHolder) throws DataAccessException;
 
@@ -1004,7 +1006,8 @@ <T> List<T> queryForList(String sql, Object[] args, int[] argTypes, Class<T> ele
 	 * <p>Note that the given PreparedStatementCreator has to create a statement
 	 * with activated extraction of generated keys (a JDBC 3.0 feature). This can
 	 * either be done directly or through using a PreparedStatementCreatorFactory.
-	 * <p>Will fall back to separate updates on a single PreparedStatement
+	 * <p>This method requires support for generated keys in the JDBC driver.
+	 * It will fall back to separate updates on a single PreparedStatement
 	 * if the JDBC driver does not support batch updates.
 	 * @param psc a callback that creates a PreparedStatement given a Connection
 	 * @param pss object to set parameters on the PreparedStatement
@@ -1016,6 +1019,7 @@ <T> List<T> queryForList(String sql, Object[] args, int[] argTypes, Class<T> ele
 	 * @throws DataAccessException if there is any problem issuing the update
 	 * @since 6.1
 	 * @see org.springframework.jdbc.support.GeneratedKeyHolder
+	 * @see java.sql.DatabaseMetaData#supportsGetGeneratedKeys()
 	 */
 	int[] batchUpdate(PreparedStatementCreator psc, BatchPreparedStatementSetter pss,
 			KeyHolder generatedKeyHolder) throws DataAccessException;

spring-jdbc/src/main/java/org/springframework/jdbc/core/namedparam/NamedParameterJdbcOperations.java

@@ -506,20 +506,23 @@ <T> List<T> queryForList(String sql, Map<String, ?> paramMap, Class<T> elementTy
 	/**
 	 * Issue an update via a prepared statement, binding the given arguments,
 	 * returning generated keys.
+	 * <p>This method requires support for generated keys in the JDBC driver.
 	 * @param sql the SQL containing named parameters
 	 * @param paramSource container of arguments and SQL types to bind to the query
 	 * @param generatedKeyHolder a {@link KeyHolder} that will hold the generated keys
 	 * @return the number of rows affected
 	 * @throws DataAccessException if there is any problem issuing the update
 	 * @see MapSqlParameterSource
 	 * @see org.springframework.jdbc.support.GeneratedKeyHolder
+	 * @see java.sql.DatabaseMetaData#supportsGetGeneratedKeys()
 	 */
 	int update(String sql, SqlParameterSource paramSource, KeyHolder generatedKeyHolder)
 			throws DataAccessException;
 
 	/**
 	 * Issue an update via a prepared statement, binding the given arguments,
 	 * returning generated keys.
+	 * <p>This method requires support for generated keys in the JDBC driver.
 	 * @param sql the SQL containing named parameters
 	 * @param paramSource container of arguments and SQL types to bind to the query
 	 * @param generatedKeyHolder a {@link KeyHolder} that will hold the generated keys
@@ -528,6 +531,7 @@ int update(String sql, SqlParameterSource paramSource, KeyHolder generatedKeyHol
 	 * @throws DataAccessException if there is any problem issuing the update
 	 * @see MapSqlParameterSource
 	 * @see org.springframework.jdbc.support.GeneratedKeyHolder
+	 * @see java.sql.DatabaseMetaData#supportsGetGeneratedKeys()
 	 */
 	int update(String sql, SqlParameterSource paramSource, KeyHolder generatedKeyHolder, String[] keyColumnNames)
 			throws DataAccessException;
@@ -558,6 +562,7 @@ int update(String sql, SqlParameterSource paramSource, KeyHolder generatedKeyHol
 	/**
 	 * Execute a batch using the supplied SQL statement with the batch of supplied
 	 * arguments, returning generated keys.
+	 * <p>This method requires support for generated keys in the JDBC driver.
 	 * @param sql the SQL statement to execute
 	 * @param batchArgs the array of {@link SqlParameterSource} containing the batch of
 	 * arguments for the query
@@ -568,12 +573,14 @@ int update(String sql, SqlParameterSource paramSource, KeyHolder generatedKeyHol
 	 * @throws DataAccessException if there is any problem issuing the update
 	 * @since 6.1
 	 * @see org.springframework.jdbc.support.GeneratedKeyHolder
+	 * @see java.sql.DatabaseMetaData#supportsGetGeneratedKeys()
 	 */
 	int[] batchUpdate(String sql, SqlParameterSource[] batchArgs, KeyHolder generatedKeyHolder);
 
 	/**
 	 * Execute a batch using the supplied SQL statement with the batch of supplied arguments,
 	 * returning generated keys.
+	 * <p>This method requires support for generated keys in the JDBC driver.
 	 * @param sql the SQL statement to execute
 	 * @param batchArgs the array of {@link SqlParameterSource} containing the batch of
 	 * arguments for the query
@@ -585,7 +592,9 @@ int update(String sql, SqlParameterSource paramSource, KeyHolder generatedKeyHol
 	 * @throws DataAccessException if there is any problem issuing the update
 	 * @since 6.1
 	 * @see org.springframework.jdbc.support.GeneratedKeyHolder
+	 * @see java.sql.DatabaseMetaData#supportsGetGeneratedKeys()
 	 */
 	int[] batchUpdate(String sql, SqlParameterSource[] batchArgs, KeyHolder generatedKeyHolder,
 			String[] keyColumnNames);
+
 }

spring-jdbc/src/main/java/org/springframework/jdbc/core/simple/JdbcClient.java

@@ -282,20 +282,24 @@ interface StatementSpec {
 
 		/**
 		 * Execute the provided SQL statement as an update.
+		 * <p>This method requires support for generated keys in the JDBC driver.
 		 * @param generatedKeyHolder a KeyHolder that will hold the generated keys
 		 * (typically a {@link org.springframework.jdbc.support.GeneratedKeyHolder})
 		 * @return the number of rows affected
 		 * @see java.sql.PreparedStatement#executeUpdate()
+		 * @see java.sql.DatabaseMetaData#supportsGetGeneratedKeys()
 		 */
 		int update(KeyHolder generatedKeyHolder);
 
 		/**
 		 * Execute the provided SQL statement as an update.
+		 * <p>This method requires support for generated keys in the JDBC driver.
 		 * @param generatedKeyHolder a KeyHolder that will hold the generated keys
 		 * (typically a {@link org.springframework.jdbc.support.GeneratedKeyHolder})
 		 * @param keyColumnNames names of the columns that will have keys generated for them
 		 * @return the number of rows affected
 		 * @see java.sql.PreparedStatement#executeUpdate()
+		 * @see java.sql.DatabaseMetaData#supportsGetGeneratedKeys()
 		 */
 		int update(KeyHolder generatedKeyHolder, String... keyColumnNames);
 	}