001/* 002 * Copyright 2002-2015 the original author or authors. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * https://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package org.springframework.jdbc.core.simple; 018 019import java.util.Map; 020 021import org.springframework.jdbc.core.RowMapper; 022import org.springframework.jdbc.core.SqlParameter; 023import org.springframework.jdbc.core.namedparam.SqlParameterSource; 024 025/** 026 * Interface specifying the API for a Simple JDBC Call implemented by {@link SimpleJdbcCall}. 027 * This interface is not often used directly, but provides the option to enhance testability, 028 * as it can easily be mocked or stubbed. 029 * 030 * @author Thomas Risberg 031 * @author Stephane Nicoll 032 * @since 2.5 033 */ 034public interface SimpleJdbcCallOperations { 035 036 /** 037 * Specify the procedure name to be used - this implies that we will be calling a stored procedure. 038 * @param procedureName the name of the stored procedure 039 * @return the instance of this SimpleJdbcCall 040 */ 041 SimpleJdbcCallOperations withProcedureName(String procedureName); 042 043 /** 044 * Specify the procedure name to be used - this implies that we will be calling a stored function. 045 * @param functionName the name of the stored function 046 * @return the instance of this SimpleJdbcCall 047 */ 048 SimpleJdbcCallOperations withFunctionName(String functionName); 049 050 /** 051 * Optionally, specify the name of the schema that contins the stored procedure. 052 * @param schemaName the name of the schema 053 * @return the instance of this SimpleJdbcCall 054 */ 055 SimpleJdbcCallOperations withSchemaName(String schemaName); 056 057 /** 058 * Optionally, specify the name of the catalog that contins the stored procedure. 059 * <p>To provide consistency with the Oracle DatabaseMetaData, this is used to specify the 060 * package name if the procedure is declared as part of a package. 061 * @param catalogName the catalog or package name 062 * @return the instance of this SimpleJdbcCall 063 */ 064 SimpleJdbcCallOperations withCatalogName(String catalogName); 065 066 /** 067 * Indicates the procedure's return value should be included in the results returned. 068 * @return the instance of this SimpleJdbcCall 069 */ 070 SimpleJdbcCallOperations withReturnValue(); 071 072 /** 073 * Specify one or more parameters if desired. These parameters will be supplemented with 074 * any parameter information retrieved from the database meta-data. 075 * <p>Note that only parameters declared as {@code SqlParameter} and {@code SqlInOutParameter} 076 * will be used to provide input values. This is different from the {@code StoredProcedure} 077 * class which - for backwards compatibility reasons - allows input values to be provided 078 * for parameters declared as {@code SqlOutParameter}. 079 * @param sqlParameters the parameters to use 080 * @return the instance of this SimpleJdbcCall 081 */ 082 SimpleJdbcCallOperations declareParameters(SqlParameter... sqlParameters); 083 084 /** Not used yet */ 085 SimpleJdbcCallOperations useInParameterNames(String... inParameterNames); 086 087 /** 088 * Used to specify when a ResultSet is returned by the stored procedure and you want it 089 * mapped by a {@link RowMapper}. The results will be returned using the parameter name 090 * specified. Multiple ResultSets must be declared in the correct order. 091 * <p>If the database you are using uses ref cursors then the name specified must match 092 * the name of the parameter declared for the procedure in the database. 093 * @param parameterName the name of the returned results and/or the name of the ref cursor parameter 094 * @param rowMapper the RowMapper implementation that will map the data returned for each row 095 * */ 096 SimpleJdbcCallOperations returningResultSet(String parameterName, RowMapper<?> rowMapper); 097 098 /** 099 * Turn off any processing of parameter meta-data information obtained via JDBC. 100 * @return the instance of this SimpleJdbcCall 101 */ 102 SimpleJdbcCallOperations withoutProcedureColumnMetaDataAccess(); 103 104 /** 105 * Indicates that parameters should be bound by name. 106 * @return the instance of this SimpleJdbcCall 107 * @since 4.2 108 */ 109 SimpleJdbcCallOperations withNamedBinding(); 110 111 112 /** 113 * Execute the stored function and return the results obtained as an Object of the 114 * specified return type. 115 * @param returnType the type of the value to return 116 * @param args optional array containing the in parameter values to be used in the call. 117 * Parameter values must be provided in the same order as the parameters are defined 118 * for the stored procedure. 119 */ 120 <T> T executeFunction(Class<T> returnType, Object... args); 121 122 /** 123 * Execute the stored function and return the results obtained as an Object of the 124 * specified return type. 125 * @param returnType the type of the value to return 126 * @param args Map containing the parameter values to be used in the call 127 */ 128 <T> T executeFunction(Class<T> returnType, Map<String, ?> args); 129 130 /** 131 * Execute the stored function and return the results obtained as an Object of the 132 * specified return type. 133 * @param returnType the type of the value to return 134 * @param args MapSqlParameterSource containing the parameter values to be used in the call 135 */ 136 <T> T executeFunction(Class<T> returnType, SqlParameterSource args); 137 138 /** 139 * Execute the stored procedure and return the single out parameter as an Object 140 * of the specified return type. In the case where there are multiple out parameters, 141 * the first one is returned and additional out parameters are ignored. 142 * @param returnType the type of the value to return 143 * @param args optional array containing the in parameter values to be used in the call. 144 * Parameter values must be provided in the same order as the parameters are defined for 145 * the stored procedure. 146 */ 147 <T> T executeObject(Class<T> returnType, Object... args); 148 149 /** 150 * Execute the stored procedure and return the single out parameter as an Object 151 * of the specified return type. In the case where there are multiple out parameters, 152 * the first one is returned and additional out parameters are ignored. 153 * @param returnType the type of the value to return 154 * @param args Map containing the parameter values to be used in the call 155 */ 156 <T> T executeObject(Class<T> returnType, Map<String, ?> args); 157 158 /** 159 * Execute the stored procedure and return the single out parameter as an Object 160 * of the specified return type. In the case where there are multiple out parameters, 161 * the first one is returned and additional out parameters are ignored. 162 * @param returnType the type of the value to return 163 * @param args MapSqlParameterSource containing the parameter values to be used in the call 164 */ 165 <T> T executeObject(Class<T> returnType, SqlParameterSource args); 166 167 /** 168 * Execute the stored procedure and return a map of output params, keyed by name 169 * as in parameter declarations. 170 * @param args optional array containing the in parameter values to be used in the call. 171 * Parameter values must be provided in the same order as the parameters are defined for 172 * the stored procedure. 173 * @return Map of output params 174 */ 175 Map<String, Object> execute(Object... args); 176 177 /** 178 * Execute the stored procedure and return a map of output params, keyed by name 179 * as in parameter declarations. 180 * @param args Map containing the parameter values to be used in the call 181 * @return Map of output params 182 */ 183 Map<String, Object> execute(Map<String, ?> args); 184 185 /** 186 * Execute the stored procedure and return a map of output params, keyed by name 187 * as in parameter declarations. 188 * @param args SqlParameterSource containing the parameter values to be used in the call 189 * @return Map of output params 190 */ 191 Map<String, Object> execute(SqlParameterSource args); 192 193}