Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Fix Javadoc in [NamedParameter]JdbcOperations.queryForObject methods

Browse Source 
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 0853baaa3f)
This commit is contained in:
Sam Brannen
2021-10-14 15:15:23 +02:00
committed by Juergen Hoeller
parent 52e2953de9
commit 2bec54e7b3
2 changed files with 45 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -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.List;
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 @@ 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 the query fails
*/
@Nullable
@@ -548,8 +549,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 the query fails
*/
@Nullable
@@ -567,8 +568,8 @@ public interface JdbcOperations {
* 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 @@ public interface JdbcOperations {
* (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 @@ public interface JdbcOperations {
* 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 @@ public interface JdbcOperations {
* 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 @@ public interface JdbcOperations {
* @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 @@ public interface JdbcOperations {
* 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

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

@@ -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 @@ public interface NamedParameterJdbcOperations {
* @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 @@ public interface NamedParameterJdbcOperations {
* @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 @@ public interface NamedParameterJdbcOperations {
* @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 @@ public interface NamedParameterJdbcOperations {
* @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)
*/