Polish simple JDBC support classes

spring-jdbc/src/main/java/org/springframework/jdbc/core/metadata/GenericTableMetaDataProvider.java

@@ -158,7 +158,7 @@ public class GenericTableMetaDataProvider implements TableMetaDataProvider {
 		}
 		catch (SQLException ex) {
 			if (logger.isWarnEnabled()) {
-				logger.warn("Error retrieving 'DatabaseMetaData.getGeneratedKeys': " + ex.getMessage());
+				logger.warn("Error retrieving 'DatabaseMetaData.supportsGetGeneratedKeys': " + ex.getMessage());
 			}
 		}
 		try {
@@ -226,51 +226,33 @@ public class GenericTableMetaDataProvider implements TableMetaDataProvider {
 	@Override
 	@Nullable
 	public String tableNameToUse(@Nullable String tableName) {
-		if (tableName == null) {
-			return null;
-		}
-		else if (isStoresUpperCaseIdentifiers()) {
-			return tableName.toUpperCase();
-		}
-		else if (isStoresLowerCaseIdentifiers()) {
-			return tableName.toLowerCase();
-		}
-		else {
-			return tableName;
-		}
+		return identifierNameToUse(tableName);
 	}
 
 	@Override
 	@Nullable
 	public String catalogNameToUse(@Nullable String catalogName) {
-		if (catalogName == null) {
-			return null;
-		}
-		else if (isStoresUpperCaseIdentifiers()) {
-			return catalogName.toUpperCase();
-		}
-		else if (isStoresLowerCaseIdentifiers()) {
-			return catalogName.toLowerCase();
-		}
-		else {
-			return catalogName;
-		}
+		return identifierNameToUse(catalogName);
 	}
 
 	@Override
 	@Nullable
 	public String schemaNameToUse(@Nullable String schemaName) {
-		if (schemaName == null) {
+		return identifierNameToUse(schemaName);
+	}
+
+	private String identifierNameToUse(String identifierName) {
+		if (identifierName == null) {
 			return null;
 		}
 		else if (isStoresUpperCaseIdentifiers()) {
-			return schemaName.toUpperCase();
+			return identifierName.toUpperCase();
 		}
 		else if (isStoresLowerCaseIdentifiers()) {
-			return schemaName.toLowerCase();
+			return identifierName.toLowerCase();
 		}
 		else {
-			return schemaName;
+			return identifierName;
 		}
 	}
 
@@ -290,7 +272,7 @@ public class GenericTableMetaDataProvider implements TableMetaDataProvider {
 	}
 
 	/**
-	 * Provide access to default schema for subclasses.
+	 * Provide access to the default schema for subclasses.
 	 */
 	@Nullable
 	protected String getDefaultSchema() {
@@ -298,7 +280,7 @@ public class GenericTableMetaDataProvider implements TableMetaDataProvider {
 	}
 
 	/**
-	 * Provide access to version info for subclasses.
+	 * Provide access to the version info for subclasses.
 	 */
 	@Nullable
 	protected String getDatabaseVersion() {

spring-jdbc/src/main/java/org/springframework/jdbc/core/metadata/TableMetaDataContext.java

@@ -349,26 +349,24 @@ public class TableMetaDataContext {
 
 
 	/**
-	 * Does this database support the JDBC 3.0 feature of retrieving generated keys:
-	 * {@link java.sql.DatabaseMetaData#supportsGetGeneratedKeys()}?
+	 * Does this database support the JDBC 3.0 feature of retrieving generated keys?
+	 * @see java.sql.DatabaseMetaData#supportsGetGeneratedKeys()
 	 */
 	public boolean isGetGeneratedKeysSupported() {
 		return obtainMetaDataProvider().isGetGeneratedKeysSupported();
 	}
 
 	/**
-	 * Does this database support simple query to retrieve generated keys
-	 * when the JDBC 3.0 feature is not supported:
-	 * {@link java.sql.DatabaseMetaData#supportsGetGeneratedKeys()}?
+	 * Does this database support a simple query to retrieve the generated key when
+	 * the JDBC 3.0 feature of retrieving generated keys is not supported?
+	 * @see #isGetGeneratedKeysSupported()
 	 */
 	public boolean isGetGeneratedKeysSimulated() {
 		return obtainMetaDataProvider().isGetGeneratedKeysSimulated();
 	}
 
 	/**
-	 * Does this database support a simple query to retrieve generated keys
-	 * when the JDBC 3.0 feature is not supported:
-	 * {@link java.sql.DatabaseMetaData#supportsGetGeneratedKeys()}?
+	 * Get the simple query to retrieve a generated key.
 	 */
 	@Nullable
 	public String getSimpleQueryForGetGeneratedKey(String tableName, String keyColumnName) {
@@ -376,8 +374,8 @@ public class TableMetaDataContext {
 	}
 
 	/**
-	 * Is a column name String array for retrieving generated keys supported:
-	 * {@link java.sql.Connection#createStruct(String, Object[])}?
+	 * Is a column name String array for retrieving generated keys supported?
+	 * @see java.sql.Connection#createStruct(String, Object[])
 	 */
 	public boolean isGeneratedKeysColumnNameArraySupported() {
 		return obtainMetaDataProvider().isGeneratedKeysColumnNameArraySupported();

spring-jdbc/src/main/java/org/springframework/jdbc/core/metadata/TableMetaDataProvider.java

@@ -24,9 +24,11 @@ import org.springframework.lang.Nullable;
 
 /**
  * Interface specifying the API to be implemented by a class providing table meta-data.
- * This is intended for internal use by the Simple JDBC classes.
+ *
+ * <p>This is intended for internal use by the Simple JDBC classes.
  *
  * @author Thomas Risberg
+ * @author Sam Brannen
  * @since 2.5
  */
 public interface TableMetaDataProvider {
@@ -40,7 +42,8 @@ public interface TableMetaDataProvider {
 
 	/**
 	 * Initialize using provided database meta-data, table and column information.
-	 * This initialization can be turned off by specifying that column meta-data should not be used.
+	 * <p>This initialization can be turned off by specifying that column meta-data
+	 * should not be used.
 	 * @param databaseMetaData used to retrieve database specific information
 	 * @param catalogName name of catalog to use (or {@code null} if none)
 	 * @param schemaName name of schema name to use (or {@code null} if none)
@@ -52,37 +55,41 @@ public interface TableMetaDataProvider {
 
 	/**
 	 * Get the table name formatted based on meta-data information.
-	 * This could include altering the case.
+	 * <p>This could include altering the case.
 	 */
 	@Nullable
 	String tableNameToUse(@Nullable String tableName);
 
 	/**
 	 * Get the catalog name formatted based on meta-data information.
-	 * This could include altering the case.
+	 * <p>This could include altering the case.
 	 */
 	@Nullable
 	String catalogNameToUse(@Nullable String catalogName);
 
 	/**
 	 * Get the schema name formatted based on meta-data information.
-	 * This could include altering the case.
+	 * <p>This could include altering the case.
 	 */
 	@Nullable
 	String schemaNameToUse(@Nullable String schemaName);
 
 	/**
-	 * Provide any modification of the catalog name passed in to match the meta-data currently used.
-	 * The returned value will be used for meta-data lookups.
-	 * This could include altering the case used or providing a base catalog if none is provided.
+	 * Provide any modification of the catalog name passed in to match the meta-data
+	 * currently used.
+	 * <p>The returned value will be used for meta-data lookups.
+	 * <p>This could include altering the case used or providing a base catalog
+	 * if none is provided.
 	 */
 	@Nullable
 	String metaDataCatalogNameToUse(@Nullable String catalogName) ;
 
 	/**
-	 * Provide any modification of the schema name passed in to match the meta-data currently used.
-	 * The returned value will be used for meta-data lookups.
-	 * This could include altering the case used or providing a base schema if none is provided.
+	 * Provide any modification of the schema name passed in to match the meta-data
+	 * currently used.
+	 * <p>The returned value will be used for meta-data lookups.
+	 * <p>This could include altering the case used or providing a base schema
+	 * if none is provided.
 	 */
 	@Nullable
 	String metaDataSchemaNameToUse(@Nullable String schemaName) ;
@@ -93,8 +100,8 @@ public interface TableMetaDataProvider {
 	boolean isTableColumnMetaDataUsed();
 
 	/**
-	 * Does this database support the JDBC 3.0 feature of retrieving generated keys:
-	 * {@link java.sql.DatabaseMetaData#supportsGetGeneratedKeys()}?
+	 * Does this database support the JDBC 3.0 feature of retrieving generated keys?
+	 * @see java.sql.DatabaseMetaData#supportsGetGeneratedKeys()
 	 */
 	boolean isGetGeneratedKeysSupported();
 
@@ -112,8 +119,9 @@ public interface TableMetaDataProvider {
 	String getSimpleQueryForGetGeneratedKey(String tableName, String keyColumnName);
 
 	/**
-	 * Does this database support a column name String array for retrieving generated keys:
-	 * {@link java.sql.Connection#createStruct(String, Object[])}?
+	 * Does this database support a column name String array for retrieving generated
+	 * keys?
+	 * @see java.sql.Connection#createStruct(String, Object[])
 	 */
 	boolean isGeneratedKeysColumnNameArraySupported();
 

spring-jdbc/src/main/java/org/springframework/jdbc/core/simple/AbstractJdbcInsert.java

@@ -57,6 +57,7 @@ import org.springframework.util.Assert;
  *
  * @author Thomas Risberg
  * @author Juergen Hoeller
+ * @author Sam Brannen
  * @since 2.5
  */
 public abstract class AbstractJdbcInsert {
@@ -91,7 +92,7 @@ public abstract class AbstractJdbcInsert {
 
 	/**
 	 * Constructor to be used when initializing using a {@link DataSource}.
-	 * @param dataSource the DataSource to be used
+	 * @param dataSource the {@code DataSource} to be used
 	 */
 	protected AbstractJdbcInsert(DataSource dataSource) {
 		this.jdbcTemplate = new JdbcTemplate(dataSource);
@@ -99,7 +100,7 @@ public abstract class AbstractJdbcInsert {
 
 	/**
 	 * Constructor to be used when initializing using a {@link JdbcTemplate}.
-	 * @param jdbcTemplate the JdbcTemplate to use
+	 * @param jdbcTemplate the {@code JdbcTemplate} to use
 	 */
 	protected AbstractJdbcInsert(JdbcTemplate jdbcTemplate) {
 		Assert.notNull(jdbcTemplate, "JdbcTemplate must not be null");
@@ -207,7 +208,7 @@ public abstract class AbstractJdbcInsert {
 
 	/**
 	 * Specify whether the parameter meta-data for the call should be used.
-	 * The default is {@code true}.
+	 * <p>The default is {@code true}.
 	 */
 	public void setAccessTableColumnMetaData(boolean accessTableColumnMetaData) {
 		this.tableMetaDataContext.setAccessTableColumnMetaData(accessTableColumnMetaData);
@@ -215,7 +216,7 @@ public abstract class AbstractJdbcInsert {
 
 	/**
 	 * Specify whether the default for including synonyms should be changed.
-	 * The default is {@code false}.
+	 * <p>The default is {@code false}.
 	 */
 	public void setOverrideIncludeSynonymsDefault(boolean override) {
 		this.tableMetaDataContext.setOverrideIncludeSynonymsDefault(override);

spring-jdbc/src/main/java/org/springframework/jdbc/core/simple/SimpleJdbcInsert.java

@@ -26,24 +26,26 @@ import org.springframework.jdbc.core.namedparam.SqlParameterSource;
 import org.springframework.jdbc.support.KeyHolder;
 
 /**
- * A SimpleJdbcInsert is a multithreaded, reusable object providing easy (batch) 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.
+ * A {@code SimpleJdbcInsert} is a multi-threaded, reusable object providing easy
+ * (batch) 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 {@code Map} containing the column
+ * names and the column values.
  *
- * <p>The meta-data processing is based on the DatabaseMetaData provided by the
- * JDBC driver. As long as the JDBC driver can provide the names of the columns
+ * <p>The meta-data processing is based on the {@code DatabaseMetaData} provided
+ * by the JDBC driver. As long as the JDBC driver can provide the names of the columns
  * for a specified table then we can rely on this auto-detection feature. If that
  * is not the case, then the column names must be specified explicitly.
  *
  * <p>The actual (batch) insert is handled using Spring's {@link JdbcTemplate}.
  *
  * <p>Many of the configuration methods return the current instance of the
- * SimpleJdbcInsert to provide the ability to chain multiple ones together
- * in a "fluent" interface style.
+ * {@code SimpleJdbcInsert} to provide the ability to chain multiple ones together
+ * in a "fluent" API style.
  *
  * @author Thomas Risberg
  * @author Juergen Hoeller
+ * @author Sam Brannen
  * @since 2.5
  * @see java.sql.DatabaseMetaData
  * @see org.springframework.jdbc.core.JdbcTemplate
@@ -51,8 +53,8 @@ import org.springframework.jdbc.support.KeyHolder;
 public class SimpleJdbcInsert extends AbstractJdbcInsert implements SimpleJdbcInsertOperations {
 
 	/**
-	 * Constructor that takes one parameter with the JDBC DataSource to use when creating the
-	 * JdbcTemplate.
+	 * Constructor that accepts the JDBC {@link DataSource} to use when creating
+	 * the {@link JdbcTemplate}.
 	 * @param dataSource the {@code DataSource} to use
 	 * @see org.springframework.jdbc.core.JdbcTemplate#setDataSource
 	 */
@@ -61,7 +63,7 @@ public class SimpleJdbcInsert extends AbstractJdbcInsert implements SimpleJdbcIn
 	}
 
 	/**
-	 * Alternative Constructor that takes one parameter with the JdbcTemplate to be used.
+	 * Alternative constructor that accepts the {@link JdbcTemplate} to be used.
 	 * @param jdbcTemplate the {@code JdbcTemplate} to use
 	 * @see org.springframework.jdbc.core.JdbcTemplate#setDataSource
 	 */

spring-jdbc/src/main/java/org/springframework/jdbc/core/simple/SimpleJdbcInsertOperations.java

@@ -23,10 +23,12 @@ import org.springframework.jdbc.support.KeyHolder;
 
 /**
  * Interface specifying the API for a Simple JDBC Insert implemented by {@link SimpleJdbcInsert}.
- * This interface is not often used directly, but provides the option to enhance testability,
+ *
+ * <p>This interface is not often used directly, but provides the option to enhance testability,
  * as it can easily be mocked or stubbed.
  *
  * @author Thomas Risberg
+ * @author Sam Brannen
  * @since 2.5
  */
 public interface SimpleJdbcInsertOperations {
@@ -34,49 +36,49 @@ public interface SimpleJdbcInsertOperations {
 	/**
 	 * Specify the table name to be used for the insert.
 	 * @param tableName the name of the stored table
-	 * @return the instance of this SimpleJdbcInsert
+	 * @return this {@code SimpleJdbcInsert} (for method chaining)
 	 */
 	SimpleJdbcInsertOperations withTableName(String tableName);
 
 	/**
 	 * Specify the schema name, if any, to be used for the insert.
 	 * @param schemaName the name of the schema
-	 * @return the instance of this SimpleJdbcInsert
+	 * @return this {@code SimpleJdbcInsert} (for method chaining)
 	 */
 	SimpleJdbcInsertOperations withSchemaName(String schemaName);
 
 	/**
 	 * Specify the catalog name, if any, to be used for the insert.
 	 * @param catalogName the name of the catalog
-	 * @return the instance of this SimpleJdbcInsert
+	 * @return this {@code SimpleJdbcInsert} (for method chaining)
 	 */
 	SimpleJdbcInsertOperations withCatalogName(String catalogName);
 
 	/**
 	 * Specify the column names that the insert statement should be limited to use.
 	 * @param columnNames one or more column names
-	 * @return the instance of this SimpleJdbcInsert
+	 * @return this {@code SimpleJdbcInsert} (for method chaining)
 	 */
 	SimpleJdbcInsertOperations usingColumns(String... columnNames);
 
 	/**
-	 * Specify the names of any columns that have auto generated keys.
+	 * Specify the names of any columns that have auto-generated keys.
 	 * @param columnNames one or more column names
-	 * @return the instance of this SimpleJdbcInsert
+	 * @return this {@code SimpleJdbcInsert} (for method chaining)
 	 */
 	SimpleJdbcInsertOperations usingGeneratedKeyColumns(String... columnNames);
 
 	/**
 	 * Turn off any processing of column meta-data information obtained via JDBC.
-	 * @return the instance of this SimpleJdbcInsert
+	 * @return this {@code SimpleJdbcInsert} (for method chaining)
 	 */
 	SimpleJdbcInsertOperations withoutTableColumnMetaDataAccess();
 
 	/**
 	 * Include synonyms for the column meta-data lookups via JDBC.
 	 * <p>Note: This is only necessary to include for Oracle since other databases
-	 * supporting synonyms seems to include the synonyms automatically.
-	 * @return the instance of this SimpleJdbcInsert
+	 * supporting synonyms seem to include the synonyms automatically.
+	 * @return this {@code SimpleJdbcInsert} (for method chaining)
 	 */
 	SimpleJdbcInsertOperations includeSynonymsForTableColumnMetaData();