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}