/*
* Copyright 2002-2015 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.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.jdbc.core.simple;
import java.util.Map;
import org.springframework.jdbc.core.RowMapper;
import org.springframework.jdbc.core.SqlParameter;
import org.springframework.jdbc.core.namedparam.SqlParameterSource;
/**
* Interface specifying the API for a Simple JDBC Call implemented by {@link SimpleJdbcCall}.
* 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 Stephane Nicoll
* @since 2.5
*/
public interface SimpleJdbcCallOperations {
/**
* Specify the procedure name to be used - this implies that we will be calling a stored procedure.
* @param procedureName the name of the stored procedure
* @return the instance of this SimpleJdbcCall
*/
SimpleJdbcCallOperations withProcedureName(String procedureName);
/**
* Specify the procedure name to be used - this implies that we will be calling a stored function.
* @param functionName the name of the stored function
* @return the instance of this SimpleJdbcCall
*/
SimpleJdbcCallOperations withFunctionName(String functionName);
/**
* Optionally, specify the name of the schema that contins the stored procedure.
* @param schemaName the name of the schema
* @return the instance of this SimpleJdbcCall
*/
SimpleJdbcCallOperations withSchemaName(String schemaName);
/**
* Optionally, specify the name of the catalog that contins the stored procedure.
* <p>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.
* @param catalogName the catalog or package name
* @return the instance of this SimpleJdbcCall
*/
SimpleJdbcCallOperations withCatalogName(String catalogName);
/**
* Indicates the procedure's return value should be included in the results returned.
* @return the instance of this SimpleJdbcCall
*/
SimpleJdbcCallOperations withReturnValue();
/**
* Specify one or more parameters if desired. These parameters will be supplemented with
* any parameter information retrieved from the database meta data.
* <p>Note that 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 sqlParameters the parameters to use
* @return the instance of this SimpleJdbcCall
*/
SimpleJdbcCallOperations declareParameters(SqlParameter... sqlParameters);
/** Not used yet */
SimpleJdbcCallOperations useInParameterNames(String... inParameterNames);
/**
* Used to specify when a ResultSet is returned by the stored procedure and you want it
* mapped by a {@link RowMapper}. The results will be returned using the parameter name
* specified. Multiple ResultSets must be declared in the correct order.
* <p>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.
* @param parameterName the name of the returned results and/or the name of the ref cursor parameter
* @param rowMapper the RowMapper implementation that will map the data returned for each row
* */
SimpleJdbcCallOperations returningResultSet(String parameterName, RowMapper<?> rowMapper);
/**
* Turn off any processing of parameter meta data information obtained via JDBC.
* @return the instance of this SimpleJdbcCall
*/
SimpleJdbcCallOperations withoutProcedureColumnMetaDataAccess();
/**
* Indicates that parameters should be bound by name.
* @return the instance of this SimpleJdbcCall
* @since 4.2
*/
SimpleJdbcCallOperations withNamedBinding();
/**
* Execute the stored function and return the results obtained as an Object of the
* specified return type.
* @param returnType the type of the value to return
* @param 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.
*/
<T> T executeFunction(Class<T> returnType, Object... args);
/**
* Execute the stored function and return the results obtained as an Object of the
* specified return type.
* @param returnType the type of the value to return
* @param args Map containing the parameter values to be used in the call
*/
<T> T executeFunction(Class<T> returnType, Map<String, ?> args);
/**
* Execute the stored function and return the results obtained as an Object of the
* specified return type.
* @param returnType the type of the value to return
* @param args MapSqlParameterSource containing the parameter values to be used in the call
*/
<T> T executeFunction(Class<T> returnType, SqlParameterSource args);
/**
* 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.
* @param returnType the type of the value to return
* @param 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.
*/
<T> T executeObject(Class<T> returnType, Object... args);
/**
* 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.
* @param returnType the type of the value to return
* @param args Map containing the parameter values to be used in the call
*/
<T> T executeObject(Class<T> returnType, Map<String, ?> args);
/**
* 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.
* @param returnType the type of the value to return
* @param args MapSqlParameterSource containing the parameter values to be used in the call
*/
<T> T executeObject(Class<T> returnType, SqlParameterSource args);
/**
* Execute the stored procedure and return a map of output params, keyed by name
* as in parameter declarations.
* @param 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.
* @return Map of output params
*/
Map<String, Object> execute(Object... args);
/**
* Execute the stored procedure and return a map of output params, keyed by name
* as in parameter declarations.
* @param args Map containing the parameter values to be used in the call
* @return Map of output params
*/
Map<String, Object> execute(Map<String, ?> args);
/**
* Execute the stored procedure and return a map of output params, keyed by name
* as in parameter declarations.
* @param args SqlParameterSource containing the parameter values to be used in the call
* @return Map of output params
*/
Map<String, Object> execute(SqlParameterSource args);
}