Fix Javadoc in [NamedParameter]JdbcOperations.queryForObject methods

This commit fixes the Javadoc in all queryForObject(...) methods in JdbcOperations and NamedParameterJdbcOperations regarding what kinds of exceptions are thrown under which conditions. Closes gh-27559 (cherry picked from commit 0853baa)
spring-projects · Oct 19, 2021 · 2bec54e · 2bec54e
1 parent 52e2953
commit 2bec54e
Show file tree

Hide file tree

Showing 2 changed files with 45 additions and 37 deletions.
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/core/JdbcOperations.java b/spring-jdbc/src/main/java/org/springframework/jdbc/core/JdbcOperations.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2021 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,22 +21,21 @@
 import java.util.Map;
 
 import org.springframework.dao.DataAccessException;
-import org.springframework.dao.IncorrectResultSizeDataAccessException;
 import org.springframework.jdbc.support.KeyHolder;
 import org.springframework.jdbc.support.rowset.SqlRowSet;
 import org.springframework.lang.Nullable;
 
 /**
  * Interface specifying a basic set of JDBC operations.
- * Implemented by {@link JdbcTemplate}. Not often used directly, but a useful
+ *
+ * <p>Implemented by {@link JdbcTemplate}. Not often used directly, but a useful
  * option to enhance testability, as it can easily be mocked or stubbed.
  *
  * <p>Alternatively, the standard JDBC infrastructure can be mocked.
  * However, mocking this interface constitutes significantly less work.
  * As an alternative to a mock objects approach to testing data access code,
- * consider the powerful integration testing support provided in the
- * {@code org.springframework.test} package, shipped in
- * {@code spring-test.jar}.
+ * consider the powerful integration testing support provided via the <em>Spring
+ * TestContext Framework</em>, in the {@code spring-test} artifact.
  *
  * @author Rod Johnson
  * @author Juergen Hoeller
@@ -143,8 +142,8 @@ public interface JdbcOperations {
 	 * @param rowMapper a callback that will map one object per row
 	 * @return the single mapped object (may be {@code null} if the given
 	 * {@link RowMapper} returned {@code} null)
-	 * @throws IncorrectResultSizeDataAccessException if the query does not
-	 * return exactly one row
+	 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
+	 * if the query does not return exactly one row
 	 * @throws DataAccessException if there is any problem executing the query
 	 * @see #queryForObject(String, RowMapper, Object...)
 	 */
@@ -163,8 +162,10 @@ public interface JdbcOperations {
 	 * @param sql the SQL query to execute
 	 * @param requiredType the type that the result object is expected to match
 	 * @return the result object of the required type, or {@code null} in case of SQL NULL
-	 * @throws IncorrectResultSizeDataAccessException if the query does not return
-	 * exactly one row, or does not return exactly one column in that row
+	 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
+	 * if the query does not return exactly one row
+	 * @throws org.springframework.jdbc.IncorrectResultSetColumnCountException
+	 * if the query does not return a row containing a single column
 	 * @throws DataAccessException if there is any problem executing the query
 	 * @see #queryForObject(String, Class, Object...)
 	 */
@@ -181,8 +182,8 @@ public interface JdbcOperations {
 	 * mapped to a Map (one entry for each column, using the column name as the key).
 	 * @param sql the SQL query to execute
 	 * @return the result Map (one entry per column, with column name as key)
-	 * @throws IncorrectResultSizeDataAccessException if the query does not
-	 * return exactly one row
+	 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
+	 * if the query does not return exactly one row
 	 * @throws DataAccessException if there is any problem executing the query
 	 * @see #queryForMap(String, Object...)
 	 * @see ColumnMapRowMapper
@@ -528,8 +529,8 @@ <T> List<T> query(String sql, @Nullable PreparedStatementSetter pss, RowMapper<T
 	 * @param rowMapper a callback that will map one object per row
 	 * @return the single mapped object (may be {@code null} if the given
 	 * {@link RowMapper} returned {@code} null)
-	 * @throws IncorrectResultSizeDataAccessException if the query does not
-	 * return exactly one row
+	 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
+	 * if the query does not return exactly one row
 	 * @throws DataAccessException if the query fails
 	 */
 	@Nullable
@@ -548,8 +549,8 @@ <T> T queryForObject(String sql, Object[] args, int[] argTypes, RowMapper<T> row
 	 * @param rowMapper a callback that will map one object per row
 	 * @return the single mapped object (may be {@code null} if the given
 	 * {@link RowMapper} returned {@code} null)
-	 * @throws IncorrectResultSizeDataAccessException if the query does not
-	 * return exactly one row
+	 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
+	 * if the query does not return exactly one row
 	 * @throws DataAccessException if the query fails
 	 */
 	@Nullable
@@ -567,8 +568,8 @@ <T> T queryForObject(String sql, Object[] args, int[] argTypes, RowMapper<T> row
 	 * only the argument value but also the SQL type and optionally the scale
 	 * @return the single mapped object (may be {@code null} if the given
 	 * {@link RowMapper} returned {@code} null)
-	 * @throws IncorrectResultSizeDataAccessException if the query does not
-	 * return exactly one row
+	 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
+	 * if the query does not return exactly one row
 	 * @throws DataAccessException if the query fails
 	 * @since 3.0.1
 	 */
@@ -586,8 +587,10 @@ <T> T queryForObject(String sql, Object[] args, int[] argTypes, RowMapper<T> row
 	 * (constants from {@code java.sql.Types})
 	 * @param requiredType the type that the result object is expected to match
 	 * @return the result object of the required type, or {@code null} in case of SQL NULL
-	 * @throws IncorrectResultSizeDataAccessException if the query does not return
-	 * exactly one row, or does not return exactly one column in that row
+	 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
+	 * if the query does not return exactly one row
+	 * @throws org.springframework.jdbc.IncorrectResultSetColumnCountException
+	 * if the query does not return a row containing a single column
 	 * @throws DataAccessException if the query fails
 	 * @see #queryForObject(String, Class)
 	 * @see java.sql.Types
@@ -608,8 +611,10 @@ <T> T queryForObject(String sql, Object[] args, int[] argTypes, Class<T> require
 	 * only the argument value but also the SQL type and optionally the scale
 	 * @param requiredType the type that the result object is expected to match
 	 * @return the result object of the required type, or {@code null} in case of SQL NULL
-	 * @throws IncorrectResultSizeDataAccessException if the query does not return
-	 * exactly one row, or does not return exactly one column in that row
+	 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
+	 * if the query does not return exactly one row
+	 * @throws org.springframework.jdbc.IncorrectResultSetColumnCountException
+	 * if the query does not return a row containing a single column
 	 * @throws DataAccessException if the query fails
 	 * @see #queryForObject(String, Class)
 	 */
@@ -628,8 +633,10 @@ <T> T queryForObject(String sql, Object[] args, int[] argTypes, Class<T> require
 	 * may also contain {@link SqlParameterValue} objects which indicate not
 	 * only the argument value but also the SQL type and optionally the scale
 	 * @return the result object of the required type, or {@code null} in case of SQL NULL
-	 * @throws IncorrectResultSizeDataAccessException if the query does not return
-	 * exactly one row, or does not return exactly one column in that row
+	 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
+	 * if the query does not return exactly one row
+	 * @throws org.springframework.jdbc.IncorrectResultSetColumnCountException
+	 * if the query does not return a row containing a single column
 	 * @throws DataAccessException if the query fails
 	 * @since 3.0.1
 	 * @see #queryForObject(String, Class)
@@ -647,8 +654,8 @@ <T> T queryForObject(String sql, Object[] args, int[] argTypes, Class<T> require
 	 * @param argTypes the SQL types of the arguments
 	 * (constants from {@code java.sql.Types})
 	 * @return the result Map (one entry per column, with column name as key)
-	 * @throws IncorrectResultSizeDataAccessException if the query does not
-	 * return exactly one row
+	 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
+	 * if the query does not return exactly one row
 	 * @throws DataAccessException if the query fails
 	 * @see #queryForMap(String)
 	 * @see ColumnMapRowMapper
@@ -671,8 +678,8 @@ <T> T queryForObject(String sql, Object[] args, int[] argTypes, Class<T> require
 	 * only the argument value but also the SQL type and optionally the scale
 	 * @return the result Map (one entry for each column, using the
 	 * column name as the key)
-	 * @throws IncorrectResultSizeDataAccessException if the query does not
-	 * return exactly one row
+	 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
+	 * if the query does not return exactly one row
 	 * @throws DataAccessException if the query fails
 	 * @see #queryForMap(String)
 	 * @see ColumnMapRowMapper

diff --git a/.../src/main/java/org/springframework/jdbc/core/namedparam/NamedParameterJdbcOperations.java b/.../src/main/java/org/springframework/jdbc/core/namedparam/NamedParameterJdbcOperations.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2021 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -236,8 +236,7 @@ <T> List<T> query(String sql, Map<String, ?> paramMap, RowMapper<T> rowMapper)
 	 * @return the single mapped object (may be {@code null} if the given
 	 * {@link RowMapper} returned {@code} null)
 	 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
-	 * if the query does not return exactly one row, or does not return exactly
-	 * one column in that row
+	 * if the query does not return exactly one row
 	 * @throws DataAccessException if the query fails
 	 */
 	@Nullable
@@ -255,8 +254,7 @@ <T> T queryForObject(String sql, SqlParameterSource paramSource, RowMapper<T> ro
 	 * @return the single mapped object (may be {@code null} if the given
 	 * {@link RowMapper} returned {@code} null)
 	 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
-	 * if the query does not return exactly one row, or does not return exactly
-	 * one column in that row
+	 * if the query does not return exactly one row
 	 * @throws DataAccessException if the query fails
 	 */
 	@Nullable
@@ -273,10 +271,12 @@ <T> T queryForObject(String sql, Map<String, ?> paramMap, RowMapper<T> rowMapper
 	 * @param requiredType the type that the result object is expected to match
 	 * @return the result object of the required type, or {@code null} in case of SQL NULL
 	 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
-	 * if the query does not return exactly one row, or does not return exactly
-	 * one column in that row
+	 * if the query does not return exactly one row
+	 * @throws org.springframework.jdbc.IncorrectResultSetColumnCountException
+	 * if the query does not return a row containing a single column
 	 * @throws DataAccessException if the query fails
 	 * @see org.springframework.jdbc.core.JdbcTemplate#queryForObject(String, Class)
+	 * @see org.springframework.jdbc.core.SingleColumnRowMapper
 	 */
 	@Nullable
 	<T> T queryForObject(String sql, SqlParameterSource paramSource, Class<T> requiredType)
@@ -293,8 +293,9 @@ <T> T queryForObject(String sql, SqlParameterSource paramSource, Class<T> requir
 	 * @param requiredType the type that the result object is expected to match
 	 * @return the result object of the required type, or {@code null} in case of SQL NULL
 	 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
-	 * if the query does not return exactly one row, or does not return exactly
-	 * one column in that row
+	 * if the query does not return exactly one row
+	 * @throws org.springframework.jdbc.IncorrectResultSetColumnCountException
+	 * if the query does not return a row containing a single column
 	 * @throws DataAccessException if the query fails
 	 * @see org.springframework.jdbc.core.JdbcTemplate#queryForObject(String, Class)
 	 */