Polishing

spring-jdbc/src/main/java/org/springframework/jdbc/support/AbstractFallbackSQLExceptionTranslator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -95,7 +95,7 @@ public abstract class AbstractFallbackSQLExceptionTranslator implements SQLExcep
 	 * is allowed to return {@code null} to indicate that no exception match has
 	 * been found and that fallback translation should kick in.
 	 * @param task readable text describing the task being attempted
-	 * @param sql SQL query or update that caused the problem (if known)
+	 * @param sql the SQL query or update that caused the problem (if known)
 	 * @param ex the offending {@code SQLException}
 	 * @return the DataAccessException, wrapping the {@code SQLException};
 	 * or {@code null} if no exception match found
@@ -114,7 +114,7 @@ public abstract class AbstractFallbackSQLExceptionTranslator implements SQLExcep
 	 * @return the message {@code String} to use
 	 */
 	protected String buildMessage(String task, @Nullable String sql, SQLException ex) {
-		return task + "; " + (sql != null ? "SQL [" + sql : "]; " + "") + ex.getMessage();
+		return task + "; " + (sql != null ? ("SQL [" + sql + "]; ") : "") + ex.getMessage();
 	}
 
 }

spring-jdbc/src/main/java/org/springframework/jdbc/support/GeneratedKeyHolder.java

@@ -26,12 +26,12 @@ import org.springframework.dao.InvalidDataAccessApiUsageException;
 import org.springframework.lang.Nullable;
 
 /**
- * Default implementation of the {@link KeyHolder} interface, to be used for
+ * The standard implementation of the {@link KeyHolder} interface, to be used for
  * holding auto-generated keys (as potentially returned by JDBC insert statements).
  *
- * <p>Create an instance of this class for each insert operation, and pass
- * it to the corresponding {@link org.springframework.jdbc.core.JdbcTemplate}
- * or {org.springframework.jdbc.object.SqlUpdate} methods.
+ * <p>Create an instance of this class for each insert operation, and pass it
+ * to the corresponding {@link org.springframework.jdbc.core.JdbcTemplate} or
+ * {@link org.springframework.jdbc.object.SqlUpdate} methods.
  *
  * @author Thomas Risberg
  * @author Juergen Hoeller
@@ -92,10 +92,11 @@ public class GeneratedKeyHolder implements KeyHolder {
 		if (this.keyList.isEmpty()) {
 			return null;
 		}
-		if (this.keyList.size() > 1)
+		if (this.keyList.size() > 1) {
 			throw new InvalidDataAccessApiUsageException(
 					"The getKeys method should only be used when keys for a single row are returned.  " +
 					"The current key list contains keys for multiple rows: " + this.keyList);
+		}
 		return this.keyList.get(0);
 	}
 

spring-jdbc/src/main/java/org/springframework/jdbc/support/KeyHolder.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -52,17 +52,17 @@ public interface KeyHolder {
 	 * multiple entries as well. If this method encounters multiple entries in
 	 * either the map or the list meaning that multiple keys were returned,
 	 * then an InvalidDataAccessApiUsageException is thrown.
-	 * @return the generated key
-	 * @throws InvalidDataAccessApiUsageException if multiple keys are encountered.
+	 * @return the generated key as a number
+	 * @throws InvalidDataAccessApiUsageException if multiple keys are encountered
 	 */
 	@Nullable
 	Number getKey() throws InvalidDataAccessApiUsageException;
 
 	/**
-	 * Retrieve the first map of keys. If there are multiple entries in the list
-	 * (meaning that multiple rows had keys returned), then an
-	 * InvalidDataAccessApiUsageException is thrown.
-	 * @return the Map of generated keys
+	 * Retrieve the first map of keys.
+	 * <p>If there are multiple entries in the list (meaning that multiple rows
+	 * had keys returned), then an InvalidDataAccessApiUsageException is thrown.
+	 * @return the Map of generated keys for a single row
 	 * @throws InvalidDataAccessApiUsageException if keys for multiple rows are encountered
 	 */
 	@Nullable
@@ -70,10 +70,10 @@ public interface KeyHolder {
 
 	/**
 	 * Return a reference to the List that contains the keys.
-	 * Can be used for extracting keys for multiple rows (an unusual case),
+	 * <p>Can be used for extracting keys for multiple rows (an unusual case),
 	 * and also for adding new maps of keys.
-	 * @return the List for the generated keys, with each entry being a Map
-	 * of column names and key values
+	 * @return the List for the generated keys, with each entry representing
+	 * an individual row through a Map of column names and key values
 	 */
 	List<Map<String, Object>> getKeyList();
 

spring-jdbc/src/main/java/org/springframework/jdbc/support/SQLErrorCodeSQLExceptionTranslator.java

@@ -90,7 +90,7 @@ public class SQLErrorCodeSQLExceptionTranslator extends AbstractFallbackSQLExcep
 	 * Create a SQL error code translator for the given DataSource.
 	 * Invoking this constructor will cause a Connection to be obtained
 	 * from the DataSource to get the meta-data.
-	 * @param dataSource DataSource to use to find meta-data and establish
+	 * @param dataSource the DataSource to use to find meta-data and establish
 	 * which error codes are usable
 	 * @see SQLErrorCodesFactory
 	 */
@@ -127,7 +127,7 @@ public class SQLErrorCodeSQLExceptionTranslator extends AbstractFallbackSQLExcep
 	 * Set the DataSource for this translator.
 	 * <p>Setting this property will cause a Connection to be obtained from
 	 * the DataSource to get the meta-data.
-	 * @param dataSource DataSource to use to find meta-data and establish
+	 * @param dataSource the DataSource to use to find meta-data and establish
 	 * which error codes are usable
 	 * @see SQLErrorCodesFactory#getErrorCodes(javax.sql.DataSource)
 	 * @see java.sql.DatabaseMetaData#getDatabaseProductName()
@@ -180,9 +180,9 @@ public class SQLErrorCodeSQLExceptionTranslator extends AbstractFallbackSQLExcep
 		}
 
 		// First, try custom translation from overridden method.
-		DataAccessException dex = customTranslate(task, sql, sqlEx);
-		if (dex != null) {
-			return dex;
+		DataAccessException dae = customTranslate(task, sql, sqlEx);
+		if (dae != null) {
+			return dae;
 		}
 
 		// Next, try the custom SQLException translator, if available.
@@ -288,15 +288,15 @@ public class SQLErrorCodeSQLExceptionTranslator extends AbstractFallbackSQLExcep
 	}
 
 	/**
-	 * Subclasses can override this method to attempt a custom mapping from SQLException
-	 * to DataAccessException.
+	 * Subclasses can override this method to attempt a custom mapping from
+	 * {@link SQLException} to {@link DataAccessException}.
 	 * @param task readable text describing the task being attempted
-	 * @param sql SQL query or update that caused the problem. May be {@code null}.
+	 * @param sql the SQL query or update that caused the problem (may be {@code null})
 	 * @param sqlEx the offending SQLException
-	 * @return null if no custom translation was possible, otherwise a DataAccessException
-	 * resulting from custom translation. This exception should include the sqlEx parameter
-	 * as a nested root cause. This implementation always returns null, meaning that
-	 * the translator always falls back to the default error codes.
+	 * @return {@code null} if no custom translation applies, otherwise a {@link DataAccessException}
+	 * resulting from custom translation. This exception should include the {@code sqlEx} parameter
+	 * as a nested root cause. This implementation always returns {@code null}, meaning that the
+	 * translator always falls back to the default error codes.
 	 */
 	@Nullable
 	protected DataAccessException customTranslate(String task, @Nullable String sql, SQLException sqlEx) {
@@ -304,16 +304,16 @@ public class SQLErrorCodeSQLExceptionTranslator extends AbstractFallbackSQLExcep
 	}
 
 	/**
-	 * Create a custom DataAccessException, based on a given exception
-	 * class from a CustomSQLErrorCodesTranslation definition.
+	 * Create a custom {@link DataAccessException}, based on a given exception
+	 * class from a {@link CustomSQLErrorCodesTranslation} definition.
 	 * @param task readable text describing the task being attempted
-	 * @param sql SQL query or update that caused the problem. May be {@code null}.
+	 * @param sql the SQL query or update that caused the problem (may be {@code null})
 	 * @param sqlEx the offending SQLException
 	 * @param exceptionClass the exception class to use, as defined in the
-	 * CustomSQLErrorCodesTranslation definition
-	 * @return null if the custom exception could not be created, otherwise
-	 * the resulting DataAccessException. This exception should include the
-	 * sqlEx parameter as a nested root cause.
+	 * {@link CustomSQLErrorCodesTranslation} definition
+	 * @return {@code null} if the custom exception could not be created, otherwise
+	 * the resulting {@link DataAccessException}. This exception should include the
+	 * {@code sqlEx} parameter as a nested root cause.
 	 * @see CustomSQLErrorCodesTranslation#setExceptionClass
 	 */
 	@Nullable

spring-jdbc/src/main/java/org/springframework/jdbc/support/SQLExceptionTranslator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -46,7 +46,7 @@ public interface SQLExceptionTranslator {
 	 * check (and subsequent cast) is considered reliable when expecting JDBC-based
 	 * access to have happened.
 	 * @param task readable text describing the task being attempted
-	 * @param sql SQL query or update that caused the problem (if known)
+	 * @param sql the SQL query or update that caused the problem (if known)
 	 * @param ex the offending {@code SQLException}
 	 * @return the DataAccessException wrapping the {@code SQLException},
 	 * or {@code null} if no translation could be applied