Fix and improve Javadoc in spring-jdbc

marcwrobel · sbrannen · commit bca104798b31 · 2022-07-13T13:42:48.000+02:00
Closes gh-28796
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/core/ArgumentPreparedStatementSetter.java b/spring-jdbc/src/main/java/org/springframework/jdbc/core/ArgumentPreparedStatementSetter.java
@@ -54,7 +54,7 @@ public void setValues(PreparedStatement ps) throws SQLException {
 
 	/**
 	 * Set the value for prepared statements specified parameter index using the passed in value.
-	 * This method can be overridden by sub-classes if needed.
+	 * This method can be overridden by subclasses if needed.
 	 * @param ps the PreparedStatement
 	 * @param parameterPosition index of the parameter position
 	 * @param argValue the value to set
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/core/ArgumentTypePreparedStatementSetter.java b/spring-jdbc/src/main/java/org/springframework/jdbc/core/ArgumentTypePreparedStatementSetter.java
@@ -87,7 +87,7 @@ public void setValues(PreparedStatement ps) throws SQLException {
 
 	/**
 	 * Set the value for the prepared statement's specified parameter position using the passed in
-	 * value and type. This method can be overridden by sub-classes if needed.
+	 * value and type. This method can be overridden by subclasses if needed.
 	 * @param ps the PreparedStatement
 	 * @param parameterPosition index of the parameter position
 	 * @param argType the argument type
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/core/CallableStatementCreatorFactory.java b/spring-jdbc/src/main/java/org/springframework/jdbc/core/CallableStatementCreatorFactory.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2022 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.
@@ -109,7 +109,7 @@ public void setUpdatableResults(boolean updatableResults) {
 
 
 	/**
-	 * Return a new CallableStatementCreator instance given this parameters.
+	 * Return a new CallableStatementCreator instance given these parameters.
 	 * @param params list of parameters (may be {@code null})
 	 */
 	public CallableStatementCreator newCallableStatementCreator(@Nullable Map<String, ?> params) {
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/core/ColumnMapRowMapper.java b/spring-jdbc/src/main/java/org/springframework/jdbc/core/ColumnMapRowMapper.java
@@ -84,7 +84,7 @@ protected String getColumnKey(String columnName) {
 	 * Retrieve a JDBC object value for the specified column.
 	 * <p>The default implementation uses the {@code getObject} method.
 	 * Additionally, this implementation includes a "hack" to get around Oracle
-	 * returning a non standard object for their TIMESTAMP data type.
+	 * returning a non-standard object for their TIMESTAMP data type.
 	 * @param rs the ResultSet holding the data
 	 * @param index the column index
 	 * @return the Object returned
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
@@ -234,7 +234,7 @@ public interface JdbcOperations {
 	 * Each element in the list will be of the form returned by this interface's
 	 * {@code queryForMap} methods.
 	 * @param sql the SQL query to execute
-	 * @return an List that contains a Map per row
+	 * @return a List that contains a Map per row
 	 * @throws DataAccessException if there is any problem executing the query
 	 * @see #queryForList(String, Object...)
 	 */
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/core/JdbcTemplate.java b/spring-jdbc/src/main/java/org/springframework/jdbc/core/JdbcTemplate.java
@@ -111,7 +111,7 @@ public class JdbcTemplate extends JdbcAccessor implements JdbcOperations {
 	private static final String RETURN_UPDATE_COUNT_PREFIX = "#update-count-";
 
 
-	/** If this variable is false, we will throw exceptions on SQL warnings. */
+	/** If this variable is {@code false}, we will throw exceptions on SQL warnings. */
 	private boolean ignoreWarnings = true;
 
 	/**
@@ -149,7 +149,7 @@ public class JdbcTemplate extends JdbcAccessor implements JdbcOperations {
 
 	/**
 	 * If this variable is set to true then execution of a CallableStatement will return
-	 * the results in a Map that uses case insensitive names for the parameters.
+	 * the results in a Map that uses case-insensitive names for the parameters.
 	 */
 	private boolean resultsMapCaseInsensitive = false;
 
@@ -187,7 +187,7 @@ public JdbcTemplate(DataSource dataSource, boolean lazyInit) {
 
 
 	/**
-	 * Set whether or not we want to ignore SQLWarnings.
+	 * Set whether we want to ignore SQLWarnings.
 	 * <p>Default is "true", swallowing and logging all warnings. Switch this flag
 	 * to "false" to make the JdbcTemplate throw an SQLWarningException instead.
 	 * @see java.sql.SQLWarning
@@ -199,7 +199,7 @@ public void setIgnoreWarnings(boolean ignoreWarnings) {
 	}
 
 	/**
-	 * Return whether or not we ignore SQLWarnings.
+	 * Return whether we ignore SQLWarnings.
 	 */
 	public boolean isIgnoreWarnings() {
 		return this.ignoreWarnings;
@@ -303,15 +303,15 @@ public boolean isSkipUndeclaredResults() {
 
 	/**
 	 * Set whether execution of a CallableStatement will return the results in a Map
-	 * that uses case insensitive names for the parameters.
+	 * that uses case-insensitive names for the parameters.
 	 */
 	public void setResultsMapCaseInsensitive(boolean resultsMapCaseInsensitive) {
 		this.resultsMapCaseInsensitive = resultsMapCaseInsensitive;
 	}
 
 	/**
 	 * Return whether execution of a CallableStatement will return the results in a Map
-	 * that uses case insensitive names for the parameters.
+	 * that uses case-insensitive names for the parameters.
 	 */
 	public boolean isResultsMapCaseInsensitive() {
 		return this.resultsMapCaseInsensitive;
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/core/metadata/CallMetaDataContext.java b/spring-jdbc/src/main/java/org/springframework/jdbc/core/metadata/CallMetaDataContext.java
@@ -478,7 +478,7 @@ else if (meta.getParameterType() == DatabaseMetaData.procedureColumnInOut) {
 	 */
 	public Map<String, Object> matchInParameterValuesWithCallParameters(SqlParameterSource parameterSource) {
 		// For parameter source lookups we need to provide case-insensitive lookup support
-		// since the database meta-data is not necessarily providing case sensitive parameter names.
+		// since the database meta-data is not necessarily providing case-sensitive parameter names.
 		Map<String, String> caseInsensitiveParameterNames =
 				SqlParameterSourceUtils.extractCaseInsensitiveParameterNames(parameterSource);
 
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/core/namedparam/NamedParameterJdbcTemplate.java b/spring-jdbc/src/main/java/org/springframework/jdbc/core/namedparam/NamedParameterJdbcTemplate.java
@@ -406,7 +406,7 @@ protected PreparedStatementCreator getPreparedStatementCreator(String sql, SqlPa
 	 * @param sql the SQL statement to execute
 	 * @param paramSource container of arguments to bind
 	 * @param customizer callback for setting further properties on the
-	 * {@link PreparedStatementCreatorFactory} in use), applied before the
+	 * {@link PreparedStatementCreatorFactory} in use, applied before the
 	 * actual {@code newPreparedStatementCreator} call
 	 * @return the corresponding {@link PreparedStatementCreator}
 	 * @since 5.0.5
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/core/namedparam/ParsedSql.java b/spring-jdbc/src/main/java/org/springframework/jdbc/core/namedparam/ParsedSql.java
@@ -69,7 +69,7 @@ void addNamedParameter(String parameterName, int startIndex, int endIndex) {
 	}
 
 	/**
-	 * Return all of the parameters (bind variables) in the parsed SQL statement.
+	 * Return all the parameters (bind variables) in the parsed SQL statement.
 	 * Repeated occurrences of the same parameter name are included here.
 	 */
 	List<String> getParameterNames() {
@@ -81,7 +81,7 @@ List<String> getParameterNames() {
 	 * @param parameterPosition the position of the parameter
 	 * (as index in the parameter names List)
 	 * @return the start index and end index, combined into
-	 * a int array of length 2
+	 * an int array of length 2
 	 */
 	int[] getParameterIndexes(int parameterPosition) {
 		return this.parameterIndexes.get(parameterPosition);
@@ -104,29 +104,29 @@ int getNamedParameterCount() {
 	}
 
 	/**
-	 * Set the count of all of the unnamed parameters in the SQL statement.
+	 * Set the count of all the unnamed parameters in the SQL statement.
 	 */
 	void setUnnamedParameterCount(int unnamedParameterCount) {
 		this.unnamedParameterCount = unnamedParameterCount;
 	}
 
 	/**
-	 * Return the count of all of the unnamed parameters in the SQL statement.
+	 * Return the count of all the unnamed parameters in the SQL statement.
 	 */
 	int getUnnamedParameterCount() {
 		return this.unnamedParameterCount;
 	}
 
 	/**
-	 * Set the total count of all of the parameters in the SQL statement.
+	 * Set the total count of all the parameters in the SQL statement.
 	 * Repeated occurrences of the same parameter name do count here.
 	 */
 	void setTotalParameterCount(int totalParameterCount) {
 		this.totalParameterCount = totalParameterCount;
 	}
 
 	/**
-	 * Return the total count of all of the parameters in the SQL statement.
+	 * Return the total count of all the parameters in the SQL statement.
 	 * Repeated occurrences of the same parameter name do count here.
 	 */
 	int getTotalParameterCount() {
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/core/namedparam/SqlParameterSourceUtils.java b/spring-jdbc/src/main/java/org/springframework/jdbc/core/namedparam/SqlParameterSourceUtils.java
@@ -106,9 +106,9 @@ public static Object getTypedValue(SqlParameterSource source, String parameterNa
 	}
 
 	/**
-	 * Create a Map of case insensitive parameter names together with the original name.
+	 * Create a Map of case-insensitive parameter names together with the original name.
 	 * @param parameterSource the source of parameter names
-	 * @return the Map that can be used for case insensitive matching of parameter names
+	 * @return the Map that can be used for case-insensitive matching of parameter names
 	 */
 	public static Map<String, String> extractCaseInsensitiveParameterNames(SqlParameterSource parameterSource) {
 		Map<String, String> caseInsensitiveParameterNames = new HashMap<>();
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/core/simple/SimpleJdbcCall.java b/spring-jdbc/src/main/java/org/springframework/jdbc/core/simple/SimpleJdbcCall.java
@@ -28,7 +28,7 @@
 import org.springframework.jdbc.core.namedparam.SqlParameterSource;
 
 /**
- * A SimpleJdbcCall is a multi-threaded, reusable object representing a call
+ * A SimpleJdbcCall is a multithreaded, reusable object representing a call
  * to a stored procedure or a stored function. It provides meta-data processing
  * to simplify the code needed to access basic stored procedures/functions.
  * All you need to provide is the name of the procedure/function and a Map
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/core/simple/SimpleJdbcInsert.java b/spring-jdbc/src/main/java/org/springframework/jdbc/core/simple/SimpleJdbcInsert.java
@@ -26,7 +26,7 @@
 import org.springframework.jdbc.support.KeyHolder;
 
 /**
- * A SimpleJdbcInsert is a multi-threaded, reusable object providing easy insert
+ * A SimpleJdbcInsert is a multithreaded, reusable object providing easy insert
  * capabilities for a table. It provides meta-data processing to simplify the code
  * needed to construct a basic insert statement. All you need to provide is the
  * name of the table and a Map containing the column names and the column values.
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/DataSourceTransactionManager.java b/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/DataSourceTransactionManager.java
@@ -195,7 +195,7 @@ protected DataSource obtainDataSource() {
 
 	/**
 	 * Specify whether to enforce the read-only nature of a transaction
-	 * (as indicated by {@link TransactionDefinition#isReadOnly()}
+	 * (as indicated by {@link TransactionDefinition#isReadOnly()})
 	 * through an explicit statement on the transactional connection:
 	 * "SET TRANSACTION READ ONLY" as understood by Oracle, MySQL and Postgres.
 	 * <p>The exact treatment, including any SQL statement executed on the connection,
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/DriverManagerDataSource.java b/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/DriverManagerDataSource.java
@@ -34,7 +34,7 @@
  * connection pool, implementing the same standard interface, but creating new
  * Connections on every call.
  *
- * <p>Useful for test or standalone environments outside of a Java EE container, either
+ * <p>Useful for test or standalone environments outside a Java EE container, either
  * as a DataSource bean in a corresponding ApplicationContext or in conjunction with
  * a simple JNDI environment. Pool-assuming {@code Connection.close()} calls will
  * simply close the Connection, so any DataSource-aware persistence code should work.
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/SmartDataSource.java b/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/SmartDataSource.java
@@ -25,7 +25,7 @@
  * implemented by special DataSources that return JDBC Connections
  * in an unwrapped fashion.
  *
- * <p>Classes using this interface can query whether or not the Connection
+ * <p>Classes using this interface can query whether the Connection
  * should be closed after an operation. Spring's DataSourceUtils and
  * JdbcTemplate classes automatically perform such a check.
  *
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/UserCredentialsDataSourceAdapter.java b/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/UserCredentialsDataSourceAdapter.java
@@ -122,7 +122,7 @@ public void setSchema(String schema) {
 
 
 	/**
-	 * Set user credententials for this proxy and the current thread.
+	 * Set user credentials for this proxy and the current thread.
 	 * The given username and password will be applied to all subsequent
 	 * {@code getConnection()} calls on this DataSource proxy.
 	 * <p>This will override any statically specified user credentials,
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/embedded/EmbeddedDatabaseFactory.java b/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/embedded/EmbeddedDatabaseFactory.java
@@ -209,7 +209,7 @@ protected void initDatabase() {
 	}
 
 	/**
-	 * Hook to shutdown the embedded database. Subclasses may call this method
+	 * Hook to shut down the embedded database. Subclasses may call this method
 	 * to force shutdown.
 	 * <p>After calling, {@link #getDataSource()} returns {@code null}.
 	 * <p>Does nothing if no embedded database has been initialized.
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/embedded/EmbeddedDatabaseFactoryBean.java b/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/embedded/EmbeddedDatabaseFactoryBean.java
@@ -34,7 +34,7 @@
  * proxy since the {@link FactoryBean} will manage the initialization and destruction
  * lifecycle of the embedded database instance.
  *
- * <p>Implements {@link DisposableBean} to shutdown the embedded database when the
+ * <p>Implements {@link DisposableBean} to shut down the embedded database when the
  * managing Spring container is being closed.
  *
  * @author Keith Donald
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/init/ScriptUtils.java b/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/init/ScriptUtils.java
@@ -161,9 +161,9 @@ public static void executeSqlScript(Connection connection, EncodedResource resou
 	 * configured and ready to use
 	 * @param resource the resource (potentially associated with a specific encoding)
 	 * to load the SQL script from
-	 * @param continueOnError whether or not to continue without throwing an exception
+	 * @param continueOnError whether to continue without throwing an exception
 	 * in the event of an error
-	 * @param ignoreFailedDrops whether or not to continue in the event of specifically
+	 * @param ignoreFailedDrops whether to continue in the event of specifically
 	 * an error on a {@code DROP} statement
 	 * @param commentPrefix the prefix that identifies single-line comments in the
 	 * SQL script (typically "--")
@@ -200,9 +200,9 @@ public static void executeSqlScript(Connection connection, EncodedResource resou
 	 * configured and ready to use
 	 * @param resource the resource (potentially associated with a specific encoding)
 	 * to load the SQL script from
-	 * @param continueOnError whether or not to continue without throwing an exception
+	 * @param continueOnError whether to continue without throwing an exception
 	 * in the event of an error
-	 * @param ignoreFailedDrops whether or not to continue in the event of specifically
+	 * @param ignoreFailedDrops whether to continue in the event of specifically
 	 * an error on a {@code DROP} statement
 	 * @param commentPrefixes the prefixes that identify single-line comments in the
 	 * SQL script (typically "--")
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/lookup/DataSourceLookupFailureException.java b/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/lookup/DataSourceLookupFailureException.java
@@ -39,7 +39,7 @@ public DataSourceLookupFailureException(String msg) {
 	/**
 	 * Constructor for DataSourceLookupFailureException.
 	 * @param msg the detail message
-	 * @param cause the root cause (usually from using a underlying
+	 * @param cause the root cause (usually from using an underlying
 	 * lookup API such as JNDI)
 	 */
 	public DataSourceLookupFailureException(String msg, Throwable cause) {
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/object/RdbmsOperation.java b/spring-jdbc/src/main/java/org/springframework/jdbc/object/RdbmsOperation.java
@@ -37,7 +37,7 @@
 import org.springframework.util.Assert;
 
 /**
- * An "RDBMS operation" is a multi-threaded, reusable object representing a query,
+ * An "RDBMS operation" is a multithreaded, reusable object representing a query,
  * update, or stored procedure call. An RDBMS operation is <b>not</b> a command,
  * as a command is not reusable. However, execute methods may take commands as
  * arguments. Subclasses should be JavaBeans, allowing easy configuration.
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/object/SqlCall.java b/spring-jdbc/src/main/java/org/springframework/jdbc/object/SqlCall.java
@@ -49,7 +49,7 @@ public abstract class SqlCall extends RdbmsOperation {
 
 	/**
 	 * Flag used to indicate that the sql for this call should be used exactly as
-	 * it is defined. No need to add the escape syntax and parameter place holders.
+	 * it is defined. No need to add the escape syntax and parameter placeholders.
 	 */
 	private boolean sqlReadyForUse = false;
 
@@ -184,7 +184,7 @@ public String getCallString() {
 
 	/**
 	 * Return a CallableStatementCreator to perform an operation
-	 * with this parameters.
+	 * with these parameters.
 	 * @param inParams parameters. May be {@code null}.
 	 */
 	protected CallableStatementCreator newCallableStatementCreator(@Nullable Map<String, ?> inParams) {
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/object/UpdatableSqlQuery.java b/spring-jdbc/src/main/java/org/springframework/jdbc/object/UpdatableSqlQuery.java
@@ -71,13 +71,13 @@ protected RowMapper<T> newRowMapper(@Nullable Object[] parameters, @Nullable Map
 	 * ResultSet and optionally create object of the result type.
 	 * @param rs the ResultSet we're working through
 	 * @param rowNum row number (from 0) we're up to
-	 * @param context passed to the execute() method.
+	 * @param context passed to the {@code execute()} method.
 	 * It can be {@code null} if no contextual information is need.  If you
 	 * need to pass in data for each row, you can pass in a HashMap with
 	 * the primary key of the row being the key for the HashMap.  That way
 	 * it is easy to locate the updates for each row
 	 * @return an object of the result type
-	 * @throws SQLException if there's an error updateing data.
+	 * @throws SQLException if there's an error updating data.
 	 * Subclasses can simply not catch SQLExceptions, relying on the
 	 * framework to clean up.
 	 */
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/support/JdbcUtils.java b/spring-jdbc/src/main/java/org/springframework/jdbc/support/JdbcUtils.java
@@ -501,7 +501,7 @@ public static String resolveTypeName(int sqlType) {
 	 * <p><i>columnLabel - the label for the column specified with the SQL AS clause.
 	 * If the SQL AS clause was not specified, then the label is the name of the column</i>.
 	 * @param resultSetMetaData the current meta-data to use
-	 * @param columnIndex the index of the column for the look up
+	 * @param columnIndex the index of the column for the lookup
 	 * @return the column name to use
 	 * @throws SQLException in case of lookup failure
 	 */
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/support/incrementer/MySQLMaxValueIncrementer.java b/spring-jdbc/src/main/java/org/springframework/jdbc/support/incrementer/MySQLMaxValueIncrementer.java
@@ -73,7 +73,7 @@ public class MySQLMaxValueIncrementer extends AbstractColumnMaxValueIncrementer
 	/** The max id to serve. */
 	private long maxId = 0;
 
-	/** Whether or not to use a new connection for the incrementer. */
+	/** Whether to use a new connection for the incrementer. */
 	private boolean useNewConnection = true;
 
 
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/support/rowset/SqlRowSet.java b/spring-jdbc/src/main/java/org/springframework/jdbc/support/rowset/SqlRowSet.java
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/support/rowset/SqlRowSetMetaData.java b/spring-jdbc/src/main/java/org/springframework/jdbc/support/rowset/SqlRowSetMetaData.java
diff --git a/spring-jdbc/src/test/java/org/springframework/jdbc/support/SQLExceptionSubclassTranslatorTests.java b/spring-jdbc/src/test/java/org/springframework/jdbc/support/SQLExceptionSubclassTranslatorTests.java
