Consistent Map<String, ?> declarations and use of LinkedHashMap for incoming JDBC operation parameters

Issue: SPR-12462

Author: jhoeller

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2011 the original author or authors.
+ * Copyright 2002-2014 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.
@@ -65,28 +65,25 @@ public class CallMetaDataContext {
 	/** List of SqlParameter objects to be used in call execution */
 	private List<SqlParameter> callParameters = new ArrayList<SqlParameter>();
 
-	/** Default name to use for the return value in the output map */
-	private String defaultFunctionReturnName = "return";
-
 	/** Actual name to use for the return value in the output map */
-	private String actualFunctionReturnName = null;
+	private String actualFunctionReturnName;
 
 	/** Set of in parameter names to exclude use for any not listed */
 	private Set<String> limitedInParameterNames = new HashSet<String>();
 
 	/** List of SqlParameter names for out parameters */
 	private List<String> outParameterNames = new ArrayList<String>();
 
-	/** should we access call parameter meta data info or not */
-	private boolean accessCallParameterMetaData = true;
+	/** Indicates whether this is a procedure or a function **/
+	private boolean function = false;
 
-	/** indicates whether this is a procedure or a function **/
-	private boolean function;
+	/** Indicates whether this procedure's return value should be included  **/
+	private boolean returnValueRequired = false;
 
-	/** indicates whether this procedure's return value should be included  **/
-	private boolean returnValueRequired;
+	/** Should we access call parameter meta data info or not */
+	private boolean accessCallParameterMetaData = true;
 
-	/** the provider of call meta data */
+	/** The provider of call meta data */
 	private CallMetaDataProvider metaDataProvider;
 
 
@@ -101,7 +98,7 @@ public void setFunctionReturnName(String functionReturnName) {
 	 * Get the name used for the return value of the function.
 	 */
 	public String getFunctionReturnName() {
-		return this.actualFunctionReturnName != null ? this.actualFunctionReturnName : this.defaultFunctionReturnName;
+		return (this.actualFunctionReturnName != null ? this.actualFunctionReturnName : "return");
 	}
 
 	/**
@@ -571,15 +568,15 @@ public String createCallString() {
 		// and the catalog name since the cataog is used for the package name
 		if (this.metaDataProvider.isSupportsSchemasInProcedureCalls() &&
 				!this.metaDataProvider.isSupportsCatalogsInProcedureCalls()) {
-			schemaNameToUse = this.metaDataProvider.catalogNameToUse(this.getCatalogName());
-			catalogNameToUse = this.metaDataProvider.schemaNameToUse(this.getSchemaName());
+			schemaNameToUse = this.metaDataProvider.catalogNameToUse(getCatalogName());
+			catalogNameToUse = this.metaDataProvider.schemaNameToUse(getSchemaName());
 		}
 		else {
-			catalogNameToUse = this.metaDataProvider.catalogNameToUse(this.getCatalogName());
-			schemaNameToUse = this.metaDataProvider.schemaNameToUse(this.getSchemaName());
+			catalogNameToUse = this.metaDataProvider.catalogNameToUse(getCatalogName());
+			schemaNameToUse = this.metaDataProvider.schemaNameToUse(getSchemaName());
 		}
-		String procedureNameToUse = this.metaDataProvider.procedureNameToUse(this.getProcedureName());
-		if (this.isFunction() || this.isReturnValueRequired()) {
+		String procedureNameToUse = this.metaDataProvider.procedureNameToUse(getProcedureName());
+		if (isFunction() || isReturnValueRequired()) {
 			callString = "{? = call " +
 					(StringUtils.hasLength(catalogNameToUse) ? catalogNameToUse + "." : "") +
 					(StringUtils.hasLength(schemaNameToUse) ? schemaNameToUse + "." : "") +

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

@@ -17,8 +17,8 @@
 package org.springframework.jdbc.core.metadata;
 
 import java.util.ArrayList;
-import java.util.HashMap;
-import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
@@ -39,6 +39,7 @@
  * and execution of operations on a database table.
  *
  * @author Thomas Risberg
+ * @author Juergen Hoeller
  * @since 2.5
  */
 public class TableMetaDataContext {
@@ -217,7 +218,7 @@ protected List<String> reconcileColumnsToUse(List<String> declaredColumns, Strin
 		if (declaredColumns.size() > 0) {
 			return new ArrayList<String>(declaredColumns);
 		}
-		Set<String> keys = new HashSet<String>(generatedKeyNames.length);
+		Set<String> keys = new LinkedHashSet<String>(generatedKeyNames.length);
 		for (String key : generatedKeyNames) {
 			keys.add(key.toUpperCase());
 		}
@@ -274,9 +275,9 @@ public List<Object> matchInParameterValuesWithInsertColumns(SqlParameterSource p
 	 * Match the provided column names and values with the list of columns used.
 	 * @param inParameters the parameter names and values
 	 */
-	public List<Object> matchInParameterValuesWithInsertColumns(Map<String, Object> inParameters) {
+	public List<Object> matchInParameterValuesWithInsertColumns(Map<String, ?> inParameters) {
 		List<Object> values = new ArrayList<Object>();
-		Map<String, Object> source = new HashMap<String, Object>();
+		Map<String, Object> source = new LinkedHashMap<String, Object>(inParameters.size());
 		for (String key : inParameters.keySet()) {
 			source.put(key.toLowerCase(), inParameters.get(key));
 		}
@@ -292,7 +293,7 @@ public List<Object> matchInParameterValuesWithInsertColumns(Map<String, Object>
 	 * @return the insert string to be used
 	 */
 	public String createInsertString(String... generatedKeyNames) {
-		HashSet<String> keys = new HashSet<String>(generatedKeyNames.length);
+		Set<String> keys = new LinkedHashSet<String>(generatedKeyNames.length);
 		for (String key : generatedKeyNames) {
 			keys.add(key.toUpperCase());
 		}
@@ -342,7 +343,8 @@ public String createInsertString(String... generatedKeyNames) {
 	public int[] createInsertTypes() {
 		int[] types = new int[this.getTableColumns().size()];
 		List<TableParameterMetaData> parameters = this.metaDataProvider.getTableParameterMetaData();
-		Map<String, TableParameterMetaData> parameterMap = new HashMap<String, TableParameterMetaData>(parameters.size());
+		Map<String, TableParameterMetaData> parameterMap =
+				new LinkedHashMap<String, TableParameterMetaData>(parameters.size());
 		for (TableParameterMetaData tpmd : parameters) {
 			parameterMap.put(tpmd.getParameterName().toUpperCase(), tpmd);
 		}

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2014 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.
@@ -17,7 +17,7 @@
 package org.springframework.jdbc.core.namedparam;
 
 import java.util.Collections;
-import java.util.HashMap;
+import java.util.LinkedHashMap;
 import java.util.Map;
 
 import org.springframework.jdbc.core.SqlParameterValue;
@@ -29,8 +29,8 @@
  * <p>This class is intended for passing in a simple Map of parameter values
  * to the methods of the {@link NamedParameterJdbcTemplate} class.
  *
- * <p>The {@code addValue} methods on this class will make adding several
- * values easier. The methods return a reference to the {@link MapSqlParameterSource}
+ * <p>The {@code addValue} methods on this class will make adding several values
+ * easier. The methods return a reference to the {@link MapSqlParameterSource}
  * itself, so you can chain several method calls together within a single statement.
  *
  * @author Thomas Risberg
@@ -43,7 +43,7 @@
  */
 public class MapSqlParameterSource extends AbstractSqlParameterSource {
 
-	private final Map<String, Object> values = new HashMap<String, Object>();
+	private final Map<String, Object> values = new LinkedHashMap<String, Object>();
 
 
 	/**

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

@@ -43,6 +43,7 @@
  * This class provides the base SPI for {@link SimpleJdbcCall}.
  *
  * @author Thomas Risberg
+ * @author Juergen Hoeller
  * @since 2.5
  */
 public abstract class AbstractJdbcCall {
@@ -63,17 +64,16 @@ public abstract class AbstractJdbcCall {
 	private final Map<String, RowMapper<?>> declaredRowMappers = new LinkedHashMap<String, RowMapper<?>>();
 
 	/**
-	 * Has this operation been compiled? Compilation means at
-	 * least checking that a DataSource and sql have been provided,
-	 * but subclasses may also implement their own custom validation.
+	 * Has this operation been compiled? Compilation means at least checking
+	 * that a DataSource or JdbcTemplate has been provided.
 	 */
 	private boolean compiled = false;
 
 	/** The generated string used for call statement */
 	private String callString;
 
 	/**
-	 * Object enabling us to create CallableStatementCreators
+	 * A delegate enabling us to create CallableStatementCreators
 	 * efficiently, based on this class's declared parameters.
 	 */
 	private CallableStatementCreatorFactory callableStatementFactory;
@@ -92,6 +92,7 @@ protected AbstractJdbcCall(DataSource dataSource) {
 	 * @param jdbcTemplate the JdbcTemplate to use
 	 */
 	protected AbstractJdbcCall(JdbcTemplate jdbcTemplate) {
+		Assert.notNull(jdbcTemplate, "JdbcTemplate must not be null");
 		this.jdbcTemplate = jdbcTemplate;
 	}
 
@@ -161,6 +162,7 @@ public String getSchemaName() {
 
 	/**
 	 * Specify whether this call is a function call.
+	 * The default is {@code false}.
 	 */
 	public void setFunction(boolean function) {
 		this.callMetaDataContext.setFunction(function);
@@ -174,7 +176,8 @@ public boolean isFunction() {
 	}
 
 	/**
-	 * Specify whether the call requires a rerurn value.
+	 * Specify whether the call requires a return value.
+	 * The default is {@code false}.
 	 */
 	public void setReturnValueRequired(boolean returnValueRequired) {
 		this.callMetaDataContext.setReturnValueRequired(returnValueRequired);
@@ -188,7 +191,8 @@ public boolean isReturnValueRequired() {
 	}
 
 	/**
-	 * Specify whether the parameter metadata for the call should be used. The default is true.
+	 * Specify whether the parameter metadata for the call should be used.
+	 * The default is {@code true}.
 	 */
 	public void setAccessCallParameterMetaData(boolean accessCallParameterMetaData) {
 		this.callMetaDataContext.setAccessCallParameterMetaData(accessCallParameterMetaData);
@@ -211,10 +215,10 @@ protected CallableStatementCreatorFactory getCallableStatementFactory() {
 
 	/**
 	 * Add a declared parameter to the list of parameters for the call.
-	 * Only parameters declared as {@code SqlParameter} and {@code SqlInOutParameter}
-	 * will be used to provide input values. This is different from the {@code StoredProcedure} class
-	 * which for backwards compatibility reasons allows input values to be provided for parameters declared
-	 * as {@code SqlOutParameter}.
+	 * <p>Only parameters declared as {@code SqlParameter} and {@code SqlInOutParameter} will
+	 * be used to provide input values. This is different from the {@code StoredProcedure}
+	 * class which - for backwards compatibility reasons - allows input values to be provided
+	 * for parameters declared as {@code SqlOutParameter}.
 	 * @param parameter the {@link SqlParameter} to add
 	 */
 	public void addDeclaredParameter(SqlParameter parameter) {
@@ -247,9 +251,9 @@ public void addDeclaredRowMapper(String parameterName, RowMapper<?> rowMapper) {
 	//-------------------------------------------------------------------------
 
 	/**
-	 * Compile this JdbcCall using provided parameters and meta data plus other settings.  This
-	 * finalizes the configuration for this object and subsequent attempts to compile are ignored.
-	 * This will be implicitly called the first time an un-compiled call is executed.
+	 * Compile this JdbcCall using provided parameters and meta data plus other settings.
+	 * <p>This finalizes the configuration for this object and subsequent attempts to compile are
+	 * ignored. This will be implicitly called the first time an un-compiled call is executed.
 	 * @throws org.springframework.dao.InvalidDataAccessApiUsageException if the object hasn't
 	 * been correctly initialized, for example if no DataSource has been provided
 	 */
@@ -267,19 +271,21 @@ public synchronized final void compile() throws InvalidDataAccessApiUsageExcepti
 			compileInternal();
 			this.compiled = true;
 			if (logger.isDebugEnabled()) {
-				logger.debug("SqlCall for " + (isFunction() ? "function" : "procedure") + " [" + getProcedureName() + "] compiled");
+				logger.debug("SqlCall for " + (isFunction() ? "function" : "procedure") +
+						" [" + getProcedureName() + "] compiled");
 			}
 		}
 	}
 
 	/**
-	 * Method to perform the actual compilation.  Subclasses can override this template method to perform
-	 * their own compilation.  Invoked after this base class's compilation is complete.
+	 * Delegate method to perform the actual compilation.
+	 * <p>Subclasses can override this template method to perform their own compilation.
+	 * Invoked after this base class's compilation is complete.
 	 */
 	protected void compileInternal() {
 		this.callMetaDataContext.initializeMetaData(getJdbcTemplate().getDataSource());
 
-		// iterate over the declared RowMappers and register the corresponding SqlParameter
+		// Iterate over the declared RowMappers and register the corresponding SqlParameter
 		for (Map.Entry<String, RowMapper<?>> entry : this.declaredRowMappers.entrySet()) {
 			SqlParameter resultSetParameter =
 					this.callMetaDataContext.createReturnResultSetParameter(entry.getKey(), entry.getValue());
@@ -332,7 +338,7 @@ protected void checkCompiled() {
 	//-------------------------------------------------------------------------
 
 	/**
-	 * Method that provides execution of the call using the passed in {@link SqlParameterSource}
+	 * Delegate method that executes the call using the passed-in {@link SqlParameterSource}.
 	 * @param parameterSource parameter names and values to be used in call
 	 * @return Map of out parameters
 	 */
@@ -343,18 +349,19 @@ protected Map<String, Object> doExecute(SqlParameterSource parameterSource) {
 	}
 
 	/**
-	 * Method that provides execution of the call using the passed in array of parameters
-	 * @param args array of parameter values; order must match the order declared for the stored procedure
+	 * Delegate method that executes the call using the passed-in array of parameters.
+	 * @param args array of parameter values. The order of values must match the order
+	 * declared for the stored procedure.
 	 * @return Map of out parameters
 	 */
-	protected Map<String, Object> doExecute(Object[] args) {
+	protected Map<String, Object> doExecute(Object... args) {
 		checkCompiled();
 		Map<String, ?> params = matchInParameterValuesWithCallParameters(args);
 		return executeCallInternal(params);
 	}
 
 	/**
-	 * Method that provides execution of the call using the passed in Map of parameters
+	 * Delegate method that executes the call using the passed-in Map of parameters.
 	 * @param args Map of parameter name and values
 	 * @return Map of out parameters
 	 */
@@ -365,7 +372,7 @@ protected Map<String, Object> doExecute(Map<String, ?> args) {
 	}
 
 	/**
-	 * Method to perform the actual call processing
+	 * Delegate method to perform the actual call processing.
 	 */
 	private Map<String, Object> executeCallInternal(Map<String, ?> args) {
 		CallableStatementCreator csc = getCallableStatementFactory().newCallableStatementCreator(args);
@@ -391,8 +398,8 @@ protected String getScalarOutParameterName() {
 	}
 
 	/**
-	 * Get a List of all the call parameters to be used for call. This includes any parameters added
-	 * based on meta data processing.
+	 * Get a List of all the call parameters to be used for call.
+	 * This includes any parameters added based on meta data processing.
 	 */
 	protected List<SqlParameter> getCallParameters() {
 		return this.callMetaDataContext.getCallParameters();