Consistent checks in DataAccessUtils (plus nullability hints in javadoc)

Issue: SPR-16225

Author: jhoeller

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

@@ -137,7 +137,8 @@ public interface JdbcOperations {
 	 * {@code null} as argument array.
 	 * @param sql SQL query to execute
 	 * @param rowMapper object that will map one object per row
-	 * @return the single mapped object
+	 * @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 DataAccessException if there is any problem executing the query
@@ -359,6 +360,7 @@ public interface JdbcOperations {
 	 * only the argument value but also the SQL type and optionally the scale
 	 * @return an arbitrary result object, as returned by the ResultSetExtractor
 	 * @throws DataAccessException if the query fails
+	 * @since 3.0.1
 	 */
 	<T> T query(String sql, ResultSetExtractor<T> rse, Object... args) throws DataAccessException;
 
@@ -428,6 +430,7 @@ 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
 	 * @throws DataAccessException if the query fails
+	 * @since 3.0.1
 	 */
 	void query(String sql, RowCallbackHandler rch, Object... args) throws DataAccessException;
 
@@ -501,6 +504,7 @@ public interface JdbcOperations {
 	 * only the argument value but also the SQL type and optionally the scale
 	 * @return the result List, containing mapped objects
 	 * @throws DataAccessException if the query fails
+	 * @since 3.0.1
 	 */
 	<T> List<T> query(String sql, RowMapper<T> rowMapper, Object... args) throws DataAccessException;
 
@@ -514,7 +518,8 @@ public interface JdbcOperations {
 	 * @param argTypes SQL types of the arguments
 	 * (constants from {@code java.sql.Types})
 	 * @param rowMapper object that will map one object per row
-	 * @return the single mapped object
+	 * @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 DataAccessException if the query fails
@@ -532,7 +537,8 @@ <T> T queryForObject(String sql, Object[] args, int[] argTypes, RowMapper<T> row
 	 * may also contain {@link SqlParameterValue} objects which indicate not
 	 * only the argument value but also the SQL type and optionally the scale
 	 * @param rowMapper object that will map one object per row
-	 * @return the single mapped object
+	 * @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 DataAccessException if the query fails
@@ -549,10 +555,12 @@ <T> T queryForObject(String sql, Object[] args, int[] argTypes, RowMapper<T> row
 	 * (leaving it to the PreparedStatement to guess the corresponding SQL type);
 	 * may also contain {@link SqlParameterValue} objects which indicate not
 	 * only the argument value but also the SQL type and optionally the scale
-	 * @return the single mapped object
+	 * @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 DataAccessException if the query fails
+	 * @since 3.0.1
 	 */
 	<T> T queryForObject(String sql, RowMapper<T> rowMapper, Object... args) throws DataAccessException;
 
@@ -610,6 +618,7 @@ <T> T queryForObject(String sql, Object[] args, int[] argTypes, Class<T> require
 	 * @throws IncorrectResultSizeDataAccessException if the query does not return
 	 * exactly one row, or does not return exactly one column in that row
 	 * @throws DataAccessException if the query fails
+	 * @since 3.0.1
 	 * @see #queryForObject(String, Class)
 	 */
 	<T> T queryForObject(String sql, Class<T> requiredType, Object... args) throws DataAccessException;
@@ -709,6 +718,7 @@ <T>List<T> queryForList(String sql, Object[] args, int[] argTypes, Class<T> elem
 	 * only the argument value but also the SQL type and optionally the scale
 	 * @return a List of objects that match the specified element type
 	 * @throws DataAccessException if the query fails
+	 * @since 3.0.1
 	 * @see #queryForList(String, Class)
 	 * @see SingleColumnRowMapper
 	 */

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2017 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.
@@ -53,7 +53,7 @@ public interface RowMapper<T> {
 	 * the ResultSet; it is only supposed to map values of the current row.
 	 * @param rs the ResultSet to map (pre-initialized for the current row)
 	 * @param rowNum the number of the current row
-	 * @return the result object for the current row
+	 * @return the result object for the current row (may be {@code null})
 	 * @throws SQLException if a SQLException is encountered getting
 	 * column values (that is, there's no need to catch SQLException)
 	 */

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2017 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.
@@ -226,7 +226,8 @@ <T> List<T> query(String sql, Map<String, ?> paramMap, RowMapper<T> rowMapper)
 	 * @param sql SQL query to execute
 	 * @param paramSource container of arguments to bind to the query
 	 * @param rowMapper object that will map one object per row
-	 * @return the single mapped object
+	 * @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
@@ -243,7 +244,8 @@ <T> T queryForObject(String sql, SqlParameterSource paramSource, RowMapper<T> ro
 	 * @param paramMap map of parameters to bind to the query
 	 * (leaving it to the PreparedStatement to guess the corresponding SQL type)
 	 * @param rowMapper object that will map one object per row
-	 * @return the single mapped object
+	 * @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
@@ -396,7 +398,7 @@ <T> List<T> queryForList(String sql, Map<String, ?> paramMap, Class<T> elementTy
 	 * list of arguments to bind to the query, expecting a SqlRowSet.
 	 * <p>The results will be mapped to an SqlRowSet which holds the data in a
 	 * disconnected fashion. This wrapper will translate any SQLExceptions thrown.
-	 * <p>Note that that, for the default implementation, JDBC RowSet support needs to
+	 * <p>Note that, for the default implementation, JDBC RowSet support needs to
 	 * be available at runtime: by default, Sun's {@code com.sun.rowset.CachedRowSetImpl}
 	 * class is used, which is part of JDK 1.5+ and also available separately as part of
 	 * Sun's JDBC RowSet Implementations download (rowset.jar).
@@ -416,7 +418,7 @@ <T> List<T> queryForList(String sql, Map<String, ?> paramMap, Class<T> elementTy
 	 * list of arguments to bind to the query, expecting a SqlRowSet.
 	 * <p>The results will be mapped to an SqlRowSet which holds the data in a
 	 * disconnected fashion. This wrapper will translate any SQLExceptions thrown.
-	 * <p>Note that that, for the default implementation, JDBC RowSet support needs to
+	 * <p>Note that, for the default implementation, JDBC RowSet support needs to
 	 * be available at runtime: by default, Sun's {@code com.sun.rowset.CachedRowSetImpl}
 	 * class is used, which is part of JDK 1.5+ and also available separately as part of
 	 * Sun's JDBC RowSet Implementations download (rowset.jar).

spring-tx/src/main/java/org/springframework/dao/support/DataAccessUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2017 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.
@@ -45,12 +45,11 @@ public abstract class DataAccessUtils {
 	 * element has been found in the given Collection
 	 */
 	public static <T> T singleResult(Collection<T> results) throws IncorrectResultSizeDataAccessException {
-		int size = (results != null ? results.size() : 0);
-		if (size == 0) {
+		if (CollectionUtils.isEmpty(results)) {
 			return null;
 		}
 		if (results.size() > 1) {
-			throw new IncorrectResultSizeDataAccessException(1, size);
+			throw new IncorrectResultSizeDataAccessException(1, results.size());
 		}
 		return results.iterator().next();
 	}
@@ -66,12 +65,11 @@ public static <T> T singleResult(Collection<T> results) throws IncorrectResultSi
 	 * has been found in the given Collection
 	 */
 	public static <T> T requiredSingleResult(Collection<T> results) throws IncorrectResultSizeDataAccessException {
-		int size = (results != null ? results.size() : 0);
-		if (size == 0) {
+		if (CollectionUtils.isEmpty(results)) {
 			throw new EmptyResultDataAccessException(1);
 		}
 		if (results.size() > 1) {
-			throw new IncorrectResultSizeDataAccessException(1, size);
+			throw new IncorrectResultSizeDataAccessException(1, results.size());
 		}
 		return results.iterator().next();
 	}
@@ -87,12 +85,11 @@ public static <T> T requiredSingleResult(Collection<T> results) throws Incorrect
 	 * @see org.springframework.util.CollectionUtils#hasUniqueObject
 	 */
 	public static <T> T uniqueResult(Collection<T> results) throws IncorrectResultSizeDataAccessException {
-		int size = (results != null ? results.size() : 0);
-		if (size == 0) {
+		if (CollectionUtils.isEmpty(results)) {
 			return null;
 		}
 		if (!CollectionUtils.hasUniqueObject(results)) {
-			throw new IncorrectResultSizeDataAccessException(1, size);
+			throw new IncorrectResultSizeDataAccessException(1, results.size());
 		}
 		return results.iterator().next();
 	}
@@ -109,12 +106,11 @@ public static <T> T uniqueResult(Collection<T> results) throws IncorrectResultSi
 	 * @see org.springframework.util.CollectionUtils#hasUniqueObject
 	 */
 	public static <T> T requiredUniqueResult(Collection<T> results) throws IncorrectResultSizeDataAccessException {
-		int size = (results != null ? results.size() : 0);
-		if (size == 0) {
+		if (CollectionUtils.isEmpty(results)) {
 			throw new EmptyResultDataAccessException(1);
 		}
 		if (!CollectionUtils.hasUniqueObject(results)) {
-			throw new IncorrectResultSizeDataAccessException(1, size);
+			throw new IncorrectResultSizeDataAccessException(1, results.size());
 		}
 		return results.iterator().next();
 	}
@@ -200,11 +196,11 @@ public static long longResult(Collection<?> results)
 
 	/**
 	 * Return a translated exception if this is appropriate,
-	 * otherwise return the input exception.
-	 * @param rawException exception we may wish to translate
+	 * otherwise return the given exception as-is.
+	 * @param rawException an exception that we may wish to translate
 	 * @param pet PersistenceExceptionTranslator to use to perform the translation
-	 * @return a translated exception if translation is possible, or
-	 * the raw exception if it is not
+	 * @return a translated persistence exception if translation is possible,
+	 * or the raw exception if it is not
 	 */
 	public static RuntimeException translateIfNecessary(
 			RuntimeException rawException, PersistenceExceptionTranslator pet) {