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 index 0d0eb2fbfe..acd1c0349f 100644 --- a/spring-jdbc/src/main/java/org/springframework/jdbc/core/JdbcOperations.java +++ b/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 query(String sql, ResultSetExtractor 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 */ List query(String sql, RowMapper 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 @@ 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 * @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 @@ public interface JdbcOperations { * (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 queryForObject(String sql, RowMapper rowMapper, Object... args) throws DataAccessException; @@ -610,6 +618,7 @@ public interface JdbcOperations { * @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 queryForObject(String sql, Class requiredType, Object... args) throws DataAccessException; @@ -709,6 +718,7 @@ public interface JdbcOperations { * 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 */ diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/core/RowMapper.java b/spring-jdbc/src/main/java/org/springframework/jdbc/core/RowMapper.java index 48ac7c8d3e..16823d6257 100644 --- a/spring-jdbc/src/main/java/org/springframework/jdbc/core/RowMapper.java +++ b/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 { * 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) */ diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/core/namedparam/NamedParameterJdbcOperations.java b/spring-jdbc/src/main/java/org/springframework/jdbc/core/namedparam/NamedParameterJdbcOperations.java index 6bccebe542..337c12474f 100644 --- a/spring-jdbc/src/main/java/org/springframework/jdbc/core/namedparam/NamedParameterJdbcOperations.java +++ b/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 @@ public interface NamedParameterJdbcOperations { * @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 @@ public interface NamedParameterJdbcOperations { * @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 @@ public interface NamedParameterJdbcOperations { * list of arguments to bind to the query, expecting a SqlRowSet. *

The results will be mapped to an SqlRowSet which holds the data in a * disconnected fashion. This wrapper will translate any SQLExceptions thrown. - *

Note that that, for the default implementation, JDBC RowSet support needs to + *

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 @@ public interface NamedParameterJdbcOperations { * list of arguments to bind to the query, expecting a SqlRowSet. *

The results will be mapped to an SqlRowSet which holds the data in a * disconnected fashion. This wrapper will translate any SQLExceptions thrown. - *

Note that that, for the default implementation, JDBC RowSet support needs to + *

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). diff --git a/spring-tx/src/main/java/org/springframework/dao/support/DataAccessUtils.java b/spring-tx/src/main/java/org/springframework/dao/support/DataAccessUtils.java index 4d68bd507b..fea6b097b9 100644 --- a/spring-tx/src/main/java/org/springframework/dao/support/DataAccessUtils.java +++ b/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 singleResult(Collection 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 abstract class DataAccessUtils { * has been found in the given Collection */ public static T requiredSingleResult(Collection 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 abstract class DataAccessUtils { * @see org.springframework.util.CollectionUtils#hasUniqueObject */ public static T uniqueResult(Collection 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 abstract class DataAccessUtils { * @see org.springframework.util.CollectionUtils#hasUniqueObject */ public static T requiredUniqueResult(Collection 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 abstract class DataAccessUtils { /** * 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) {