org.springframework.jdbc.core.simple

Class SimpleJdbcCall

java.lang.Object

org.springframework.jdbc.core.simple.AbstractJdbcCall

org.springframework.jdbc.core.simple.SimpleJdbcCall

All Implemented Interfaces:

SimpleJdbcCallOperations

public class SimpleJdbcCall
extends AbstractJdbcCall
implements SimpleJdbcCallOperations

A SimpleJdbcCall is a multi-threaded, 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 containing the parameters when you execute the call. The names of the supplied parameters will be matched up with in and out parameters declared when the stored procedure was created.

The meta data processing is based on the DatabaseMetaData provided by the JDBC driver. Since we rely on the JDBC driver, this "auto-detection" can only be used for databases that are known to provide accurate meta data. These currently include Derby, MySQL, Microsoft SQL Server, Oracle, DB2, Sybase and PostgreSQL. For any other databases you are required to declare all parameters explicitly. You can of course declare all parameters explicitly even if the database provides the necessary meta data. In that case your declared parameters will take precedence. You can also turn off any meta data processing if you want to use parameter names that do not match what is declared during the stored procedure compilation.

The actual insert is being handled using Spring's JdbcTemplate.

Many of the configuration methods return the current instance of the SimpleJdbcCall to provide the ability to chain multiple ones together in a "fluent" interface style.

Since:

2.5

Author:

Thomas Risberg

See Also:

DatabaseMetaData, JdbcTemplate

Field Summary

Fields inherited from class org.springframework.jdbc.core.simple.AbstractJdbcCall

logger

Constructor Summary

Constructors

Constructor and Description
SimpleJdbcCall(javax.sql.DataSource dataSource) Constructor that takes one parameter with the JDBC DataSource to use when creating the JdbcTemplate.
SimpleJdbcCall(JdbcTemplate jdbcTemplate) Alternative Constructor that takes one parameter with the JdbcTemplate to be used.

Method Summary

Methods

Modifier and Type	Method and Description
SimpleJdbcCall	declareParameters(SqlParameter... sqlParameters) Specify one or more parameters if desired.
java.util.Map<java.lang.String,java.lang.Object>	execute(java.util.Map<java.lang.String,?> args) Execute the stored procedure and return a map of output params, keyed by name as in parameter declarations..
java.util.Map<java.lang.String,java.lang.Object>	execute(java.lang.Object... args) Execute the stored procedure and return a map of output params, keyed by name as in parameter declarations.
java.util.Map<java.lang.String,java.lang.Object>	execute(SqlParameterSource parameterSource) Execute the stored procedure and return a map of output params, keyed by name as in parameter declarations..
<T> T	executeFunction(java.lang.Class<T> returnType, java.util.Map<java.lang.String,?> args) Execute the stored function and return the results obtained as an Object of the specified return type.
<T> T	executeFunction(java.lang.Class<T> returnType, java.lang.Object... args) Execute the stored function and return the results obtained as an Object of the specified return type.
<T> T	executeFunction(java.lang.Class<T> returnType, SqlParameterSource args) Execute the stored function and return the results obtained as an Object of the specified return type.
<T> T	executeObject(java.lang.Class<T> returnType, java.util.Map<java.lang.String,?> args) Execute the stored procedure and return the single out parameter as an Object of the specified return type.
<T> T	executeObject(java.lang.Class<T> returnType, java.lang.Object... args) Execute the stored procedure and return the single out parameter as an Object of the specified return type.
<T> T	executeObject(java.lang.Class<T> returnType, SqlParameterSource args) Execute the stored procedure and return the single out parameter as an Object of the specified return type.
SimpleJdbcCall	returningResultSet(java.lang.String parameterName, ParameterizedRowMapper rowMapper) Deprecated. in favor of returningResultSet(String, org.springframework.jdbc.core.RowMapper)
SimpleJdbcCall	returningResultSet(java.lang.String parameterName, RowMapper rowMapper) Used to specify when a ResultSet is returned by the stored procedure and you want it mapped by a RowMapper.
SimpleJdbcCall	useInParameterNames(java.lang.String... inParameterNames) Not used yet
SimpleJdbcCall	withCatalogName(java.lang.String catalogName) Optionally, specify the name of the catalog that contins the stored procedure.
SimpleJdbcCall	withFunctionName(java.lang.String functionName) Specify the procedure name to be used - this implies that we will be calling a stored function.
SimpleJdbcCall	withoutProcedureColumnMetaDataAccess() Turn off any processing of parameter meta data information obtained via JDBC.
SimpleJdbcCall	withProcedureName(java.lang.String procedureName) Specify the procedure name to be used - this implies that we will be calling a stored procedure.
SimpleJdbcCall	withReturnValue() Indicates the procedure's return value should be included in the results returned.
SimpleJdbcCall	withSchemaName(java.lang.String schemaName) Optionally, specify the name of the schema that contins the stored procedure.

Methods inherited from class org.springframework.jdbc.core.simple.AbstractJdbcCall

addDeclaredParameter, addDeclaredRowMapper, addDeclaredRowMapper, checkCompiled, compile, compileInternal, doExecute, doExecute, doExecute, getCallableStatementFactory, getCallParameters, getCallString, getCatalogName, getInParameterNames, getJdbcTemplate, getProcedureName, getScalarOutParameterName, getSchemaName, isCompiled, isFunction, isReturnValueRequired, matchInParameterValuesWithCallParameters, matchInParameterValuesWithCallParameters, onCompileInternal, setAccessCallParameterMetaData, setCatalogName, setFunction, setInParameterNames, setProcedureName, setReturnValueRequired, setSchemaName

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SimpleJdbcCall

public SimpleJdbcCall(javax.sql.DataSource dataSource)

Constructor that takes one parameter with the JDBC DataSource to use when creating the JdbcTemplate.

Parameters:

dataSource - the DataSource to use

See Also:

JdbcAccessor.setDataSource(javax.sql.DataSource)

SimpleJdbcCall

public SimpleJdbcCall(JdbcTemplate jdbcTemplate)

Alternative Constructor that takes one parameter with the JdbcTemplate to be used.

Parameters:

jdbcTemplate - the JdbcTemplate to use

See Also:

JdbcAccessor.setDataSource(javax.sql.DataSource)

Method Detail

withProcedureName

public SimpleJdbcCall withProcedureName(java.lang.String procedureName)

Description copied from interface: SimpleJdbcCallOperations

Specify the procedure name to be used - this implies that we will be calling a stored procedure.

Specified by:

withProcedureName in interface SimpleJdbcCallOperations

Parameters:

procedureName - the name of the stored procedure

Returns:

the instance of this SimpleJdbcCall

withFunctionName

public SimpleJdbcCall withFunctionName(java.lang.String functionName)

Description copied from interface: SimpleJdbcCallOperations

Specify the procedure name to be used - this implies that we will be calling a stored function.

Specified by:

withFunctionName in interface SimpleJdbcCallOperations

Parameters:

functionName - the name of the stored function

Returns:

the instance of this SimpleJdbcCall

withSchemaName

public SimpleJdbcCall withSchemaName(java.lang.String schemaName)

Description copied from interface: SimpleJdbcCallOperations

Optionally, specify the name of the schema that contins the stored procedure.

Specified by:

withSchemaName in interface SimpleJdbcCallOperations

Parameters:

schemaName - the name of the schema

Returns:

the instance of this SimpleJdbcCall

withCatalogName

public SimpleJdbcCall withCatalogName(java.lang.String catalogName)

Description copied from interface: SimpleJdbcCallOperations

Optionally, specify the name of the catalog that contins the stored procedure. To provide consistency with the Oracle DatabaseMetaData, this is used to specify the package name if the procedure is declared as part of a package.

Specified by:

withCatalogName in interface SimpleJdbcCallOperations

Parameters:

catalogName - the catalog or package name

Returns:

the instance of this SimpleJdbcCall

withReturnValue

public SimpleJdbcCall withReturnValue()

Description copied from interface: SimpleJdbcCallOperations

Indicates the procedure's return value should be included in the results returned.

Specified by:

withReturnValue in interface SimpleJdbcCallOperations

Returns:

the instance of this SimpleJdbcCall

declareParameters

public SimpleJdbcCall declareParameters(SqlParameter... sqlParameters)

Description copied from interface: SimpleJdbcCallOperations

Specify one or more parameters if desired. These parameters will be supplemented with any parameter information retrieved from the database meta data. Note that only parameters declared as SqlParameter and SqlInOutParameter will be used to provide input values. This is different from the StoredProcedure class which for backwards compatibility reasons allows input values to be provided for parameters declared as SqlOutParameter.

Specified by:

declareParameters in interface SimpleJdbcCallOperations

Parameters:

sqlParameters - the parameters to use

Returns:

the instance of this SimpleJdbcCall

useInParameterNames

public SimpleJdbcCall useInParameterNames(java.lang.String... inParameterNames)

Description copied from interface: SimpleJdbcCallOperations

Not used yet

Specified by:

useInParameterNames in interface SimpleJdbcCallOperations

returningResultSet

public SimpleJdbcCall returningResultSet(java.lang.String parameterName,
                                RowMapper rowMapper)

Description copied from interface: SimpleJdbcCallOperations

Used to specify when a ResultSet is returned by the stored procedure and you want it mapped by a RowMapper. The results will be returned using the parameter name specified. Multiple ResultSets must be declared in the correct order. If the database you are using uses ref cursors then the name specified must match the name of the parameter declared for the procedure in the database.

Specified by:

returningResultSet in interface SimpleJdbcCallOperations

Parameters:

parameterName - the name of the returned results and/or the name of the ref cursor parameter

rowMapper - the RowMapper implementation that will map the data returned for each row

returningResultSet

@Deprecated
public SimpleJdbcCall returningResultSet(java.lang.String parameterName,
                                           ParameterizedRowMapper rowMapper)

Deprecated. in favor of returningResultSet(String, org.springframework.jdbc.core.RowMapper)

Description copied from interface: SimpleJdbcCallOperations

Used to specify when a ResultSet is returned by the stored procedure and you want it mapped by a RowMapper. The results will be returned using the parameter name specified. Multiple ResultSets must be declared in the correct order. If the database you are using uses ref cursors then the name specified must match the name of the parameter declared for the procedure in the database.

Specified by:

returningResultSet in interface SimpleJdbcCallOperations

withoutProcedureColumnMetaDataAccess

public SimpleJdbcCall withoutProcedureColumnMetaDataAccess()

Description copied from interface: SimpleJdbcCallOperations

Turn off any processing of parameter meta data information obtained via JDBC.

Specified by:

withoutProcedureColumnMetaDataAccess in interface SimpleJdbcCallOperations

Returns:

the instance of this SimpleJdbcCall

executeFunction

public <T> T executeFunction(java.lang.Class<T> returnType,
                    java.lang.Object... args)

Description copied from interface: SimpleJdbcCallOperations

Execute the stored function and return the results obtained as an Object of the specified return type.

Specified by:

executeFunction in interface SimpleJdbcCallOperations

Parameters:

returnType - the type of the value to return

args - optional array containing the in parameter values to be used in the call. Parameter values must be provided in the same order as the parameters are defined for the stored procedure.

executeFunction

public <T> T executeFunction(java.lang.Class<T> returnType,
                    java.util.Map<java.lang.String,?> args)

Description copied from interface: SimpleJdbcCallOperations

Execute the stored function and return the results obtained as an Object of the specified return type.

Specified by:

executeFunction in interface SimpleJdbcCallOperations

Parameters:

returnType - the type of the value to return

args - Map containing the parameter values to be used in the call.

executeFunction

public <T> T executeFunction(java.lang.Class<T> returnType,
                    SqlParameterSource args)

Description copied from interface: SimpleJdbcCallOperations

Execute the stored function and return the results obtained as an Object of the specified return type.

Specified by:

executeFunction in interface SimpleJdbcCallOperations

Parameters:

returnType - the type of the value to return

args - MapSqlParameterSource containing the parameter values to be used in the call.

executeObject

public <T> T executeObject(java.lang.Class<T> returnType,
                  java.lang.Object... args)

Description copied from interface: SimpleJdbcCallOperations

Execute the stored procedure and return the single out parameter as an Object of the specified return type. In the case where there are multiple out parameters, the first one is returned and additional out parameters are ignored.

Specified by:

executeObject in interface SimpleJdbcCallOperations

Parameters:

returnType - the type of the value to return

args - optional array containing the in parameter values to be used in the call. Parameter values must be provided in the same order as the parameters are defined for the stored procedure.

executeObject

public <T> T executeObject(java.lang.Class<T> returnType,
                  java.util.Map<java.lang.String,?> args)

Description copied from interface: SimpleJdbcCallOperations

Execute the stored procedure and return the single out parameter as an Object of the specified return type. In the case where there are multiple out parameters, the first one is returned and additional out parameters are ignored.

Specified by:

executeObject in interface SimpleJdbcCallOperations

Parameters:

returnType - the type of the value to return

args - Map containing the parameter values to be used in the call.

executeObject

public <T> T executeObject(java.lang.Class<T> returnType,
                  SqlParameterSource args)

Description copied from interface: SimpleJdbcCallOperations

Execute the stored procedure and return the single out parameter as an Object of the specified return type. In the case where there are multiple out parameters, the first one is returned and additional out parameters are ignored.

Specified by:

executeObject in interface SimpleJdbcCallOperations

Parameters:

returnType - the type of the value to return

args - MapSqlParameterSource containing the parameter values to be used in the call.

execute

public java.util.Map<java.lang.String,java.lang.Object> execute(java.lang.Object... args)

Description copied from interface: SimpleJdbcCallOperations

Execute the stored procedure and return a map of output params, keyed by name as in parameter declarations.

Specified by:

execute in interface SimpleJdbcCallOperations

Parameters:

args - optional array containing the in parameter values to be used in the call. Parameter values must be provided in the same order as the parameters are defined for the stored procedure.

Returns:

map of output params.

execute

public java.util.Map<java.lang.String,java.lang.Object> execute(java.util.Map<java.lang.String,?> args)

Description copied from interface: SimpleJdbcCallOperations

Execute the stored procedure and return a map of output params, keyed by name as in parameter declarations..

Specified by:

execute in interface SimpleJdbcCallOperations

Parameters:

args - Map containing the parameter values to be used in the call.

Returns:

map of output params.

execute

public java.util.Map<java.lang.String,java.lang.Object> execute(SqlParameterSource parameterSource)

Description copied from interface: SimpleJdbcCallOperations

Execute the stored procedure and return a map of output params, keyed by name as in parameter declarations..

Specified by:

execute in interface SimpleJdbcCallOperations

Parameters:

parameterSource - SqlParameterSource containing the parameter values to be used in the call.

Returns:

map of output params.