1 /*
2 * Copyright 2004-2022 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package com.ibatis.sqlmap.client;
17
18 import com.ibatis.common.util.PaginatedList;
19 import com.ibatis.sqlmap.client.event.RowHandler;
20 import com.ibatis.sqlmap.engine.execution.BatchException;
21
22 import java.sql.SQLException;
23 import java.util.List;
24 import java.util.Map;
25
26 /**
27 * This interface declares all methods involved with executing statements and batches for an SQL Map.
28 *
29 * @see SqlMapSession
30 * @see SqlMapClient
31 */
32 public interface SqlMapExecutor {
33
34 /**
35 * Executes a mapped SQL INSERT statement. Insert is a bit different from other update methods, as it provides
36 * facilities for returning the primary key of the newly inserted row (rather than the effected rows). This
37 * functionality is of course optional.
38 * <p>
39 * The parameter object is generally used to supply the input data for the INSERT values.
40 *
41 * @param id
42 * The name of the statement to execute.
43 * @param parameterObject
44 * The parameter object (e.g. JavaBean, Map, XML etc.).
45 *
46 * @return The primary key of the newly inserted row. This might be automatically generated by the RDBMS, or selected
47 * from a sequence table or other source.
48 *
49 * @throws SQLException
50 * the SQL exception
51 */
52 Object insert(String id, Object parameterObject) throws SQLException;
53
54 /**
55 * Executes a mapped SQL INSERT statement. Insert is a bit different from other update methods, as it provides
56 * facilities for returning the primary key of the newly inserted row (rather than the effected rows). This
57 * functionality is of course optional.
58 * <p>
59 * This overload assumes no parameter is needed.
60 *
61 * @param id
62 * The name of the statement to execute.
63 *
64 * @return The primary key of the newly inserted row. This might be automatically generated by the RDBMS, or selected
65 * from a sequence table or other source.
66 *
67 * @throws SQLException
68 * the SQL exception
69 */
70 Object insert(String id) throws SQLException;
71
72 /**
73 * Executes a mapped SQL UPDATE statement. Update can also be used for any other update statement type, such as
74 * inserts and deletes. Update returns the number of rows effected.
75 * <p>
76 * The parameter object is generally used to supply the input data for the UPDATE values as well as the WHERE clause
77 * parameter(s).
78 *
79 * @param id
80 * The name of the statement to execute.
81 * @param parameterObject
82 * The parameter object (e.g. JavaBean, Map, XML etc.).
83 *
84 * @return The number of rows effected.
85 *
86 * @throws SQLException
87 * the SQL exception
88 */
89 int update(String id, Object parameterObject) throws SQLException;
90
91 /**
92 * Executes a mapped SQL UPDATE statement. Update can also be used for any other update statement type, such as
93 * inserts and deletes. Update returns the number of rows effected.
94 * <p>
95 * This overload assumes no parameter is needed.
96 *
97 * @param id
98 * The name of the statement to execute.
99 *
100 * @return The number of rows effected.
101 *
102 * @throws SQLException
103 * the SQL exception
104 */
105 int update(String id) throws SQLException;
106
107 /**
108 * Executes a mapped SQL DELETE statement. Delete returns the number of rows effected.
109 * <p>
110 * The parameter object is generally used to supply the input data for the WHERE clause parameter(s) of the DELETE
111 * statement.
112 *
113 * @param id
114 * The name of the statement to execute.
115 * @param parameterObject
116 * The parameter object (e.g. JavaBean, Map, XML etc.).
117 *
118 * @return The number of rows effected.
119 *
120 * @throws SQLException
121 * the SQL exception
122 */
123 int delete(String id, Object parameterObject) throws SQLException;
124
125 /**
126 * Executes a mapped SQL DELETE statement. Delete returns the number of rows effected.
127 * <p>
128 * This overload assumes no parameter is needed.
129 *
130 * @param id
131 * The name of the statement to execute.
132 *
133 * @return The number of rows effected.
134 *
135 * @throws SQLException
136 * the SQL exception
137 */
138 int delete(String id) throws SQLException;
139
140 /**
141 * Executes a mapped SQL SELECT statement that returns data to populate a single object instance.
142 * <p>
143 * The parameter object is generally used to supply the input data for the WHERE clause parameter(s) of the SELECT
144 * statement.
145 *
146 * @param id
147 * The name of the statement to execute.
148 * @param parameterObject
149 * The parameter object (e.g. JavaBean, Map, XML etc.).
150 *
151 * @return The single result object populated with the result set data, or null if no result was found
152 *
153 * @throws SQLException
154 * the SQL exception
155 */
156 Object queryForObject(String id, Object parameterObject) throws SQLException;
157
158 /**
159 * Executes a mapped SQL SELECT statement that returns data to populate a single object instance.
160 * <p>
161 * This overload assumes no parameter is needed.
162 *
163 * @param id
164 * The name of the statement to execute.
165 *
166 * @return The single result object populated with the result set data, or null if no result was found
167 *
168 * @throws SQLException
169 * the SQL exception
170 */
171 Object queryForObject(String id) throws SQLException;
172
173 /**
174 * Executes a mapped SQL SELECT statement that returns data to populate the supplied result object.
175 * <p>
176 * The parameter object is generally used to supply the input data for the WHERE clause parameter(s) of the SELECT
177 * statement.
178 *
179 * @param id
180 * The name of the statement to execute.
181 * @param parameterObject
182 * The parameter object (e.g. JavaBean, Map, XML etc.).
183 * @param resultObject
184 * The result object instance that should be populated with result data.
185 *
186 * @return The single result object as supplied by the resultObject parameter, populated with the result set data, or
187 * null if no result was found
188 *
189 * @throws SQLException
190 * the SQL exception
191 */
192 Object queryForObject(String id, Object parameterObject, Object resultObject) throws SQLException;
193
194 /**
195 * Executes a mapped SQL SELECT statement that returns data to populate a number of result objects.
196 * <p>
197 * The parameter object is generally used to supply the input data for the WHERE clause parameter(s) of the SELECT
198 * statement.
199 *
200 * @param id
201 * The name of the statement to execute.
202 * @param parameterObject
203 * The parameter object (e.g. JavaBean, Map, XML etc.).
204 *
205 * @return A List of result objects.
206 *
207 * @throws SQLException
208 * the SQL exception
209 */
210 List queryForList(String id, Object parameterObject) throws SQLException;
211
212 /**
213 * Executes a mapped SQL SELECT statement that returns data to populate a number of result objects.
214 * <p>
215 * This overload assumes no parameter is needed.
216 *
217 * @param id
218 * The name of the statement to execute.
219 *
220 * @return A List of result objects.
221 *
222 * @throws SQLException
223 * the SQL exception
224 */
225 List queryForList(String id) throws SQLException;
226
227 /**
228 * Executes a mapped SQL SELECT statement that returns data to populate a number of result objects within a certain
229 * range.
230 * <p>
231 * The parameter object is generally used to supply the input data for the WHERE clause parameter(s) of the SELECT
232 * statement.
233 *
234 * @param id
235 * The name of the statement to execute.
236 * @param parameterObject
237 * The parameter object (e.g. JavaBean, Map, XML etc.).
238 * @param skip
239 * The number of results to ignore.
240 * @param max
241 * The maximum number of results to return.
242 *
243 * @return A List of result objects.
244 *
245 * @throws SQLException
246 * the SQL exception
247 */
248 List queryForList(String id, Object parameterObject, int skip, int max) throws SQLException;
249
250 /**
251 * Executes a mapped SQL SELECT statement that returns data to populate a number of result objects within a certain
252 * range.
253 * <p>
254 * This overload assumes no parameter is needed.
255 *
256 * @param id
257 * The name of the statement to execute.
258 * @param skip
259 * The number of results to ignore.
260 * @param max
261 * The maximum number of results to return.
262 *
263 * @return A List of result objects.
264 *
265 * @throws SQLException
266 * the SQL exception
267 */
268 List queryForList(String id, int skip, int max) throws SQLException;
269
270 /**
271 * Executes a mapped SQL SELECT statement that returns a number of result objects that will be handled one at a time
272 * by a RowHandler.
273 * <p>
274 * This is generally a good approach to take when dealing with large sets of records (i.e. hundreds, thousands...)
275 * that need to be processed without eating up all of the system resources.
276 * <p>
277 * The parameter object is generally used to supply the input data for the WHERE clause parameter(s) of the SELECT
278 * statement.
279 *
280 * @param id
281 * The name of the statement to execute.
282 * @param parameterObject
283 * The parameter object (e.g. JavaBean, Map, XML etc.).
284 * @param rowHandler
285 * A RowHandler instance
286 *
287 * @throws SQLException
288 * the SQL exception
289 */
290 void queryWithRowHandler(String id, Object parameterObject, RowHandler rowHandler) throws SQLException;
291
292 /**
293 * Executes a mapped SQL SELECT statement that returns a number of result objects that will be handled one at a time
294 * by a RowHandler.
295 * <p>
296 * This is generally a good approach to take when dealing with large sets of records (i.e. hundreds, thousands...)
297 * that need to be processed without eating up all of the system resources.
298 * <p>
299 * This overload assumes no parameter is needed.
300 *
301 * @param id
302 * The name of the statement to execute.
303 * @param rowHandler
304 * A RowHandler instance
305 *
306 * @throws SQLException
307 * the SQL exception
308 */
309 void queryWithRowHandler(String id, RowHandler rowHandler) throws SQLException;
310
311 /**
312 * Executes a mapped SQL SELECT statement that returns data to populate a number of result objects a page at a time.
313 * <p>
314 * The parameter object is generally used to supply the input data for the WHERE clause parameter(s) of the SELECT
315 * statement.
316 *
317 * @param id
318 * The name of the statement to execute.
319 * @param parameterObject
320 * The parameter object (e.g. JavaBean, Map, XML etc.).
321 * @param pageSize
322 * The maximum number of result objects each page can hold.
323 *
324 * @return A PaginatedList of result objects.
325 *
326 * @throws SQLException
327 * the SQL exception
328 *
329 * @deprecated All paginated list features have been deprecated
330 */
331 PaginatedList queryForPaginatedList(String id, Object parameterObject, int pageSize) throws SQLException;
332
333 /**
334 * Executes a mapped SQL SELECT statement that returns data to populate a number of result objects a page at a time.
335 * <p>
336 * This overload assumes no parameter is needed.
337 *
338 * @param id
339 * The name of the statement to execute.
340 * @param pageSize
341 * The maximum number of result objects each page can hold.
342 *
343 * @return A PaginatedList of result objects.
344 *
345 * @throws SQLException
346 * the SQL exception
347 *
348 * @deprecated All paginated list features have been deprecated
349 */
350 PaginatedList queryForPaginatedList(String id, int pageSize) throws SQLException;
351
352 /**
353 * Executes a mapped SQL SELECT statement that returns data to populate a number of result objects that will be keyed
354 * into a Map.
355 * <p>
356 * The parameter object is generally used to supply the input data for the WHERE clause parameter(s) of the SELECT
357 * statement.
358 *
359 * @param id
360 * The name of the statement to execute.
361 * @param parameterObject
362 * The parameter object (e.g. JavaBean, Map, XML etc.).
363 * @param keyProp
364 * The property to be used as the key in the Map.
365 *
366 * @return A Map keyed by keyProp with values being the result object instance.
367 *
368 * @throws SQLException
369 * the SQL exception
370 */
371 Map queryForMap(String id, Object parameterObject, String keyProp) throws SQLException;
372
373 /**
374 * Executes a mapped SQL SELECT statement that returns data to populate a number of result objects from which one
375 * property will be keyed into a Map.
376 * <p>
377 * The parameter object is generally used to supply the input data for the WHERE clause parameter(s) of the SELECT
378 * statement.
379 *
380 * @param id
381 * The name of the statement to execute.
382 * @param parameterObject
383 * The parameter object (e.g. JavaBean, Map, XML etc.).
384 * @param keyProp
385 * The property to be used as the key in the Map.
386 * @param valueProp
387 * The property to be used as the value in the Map.
388 *
389 * @return A Map keyed by keyProp with values of valueProp.
390 *
391 * @throws SQLException
392 * the SQL exception
393 */
394 Map queryForMap(String id, Object parameterObject, String keyProp, String valueProp) throws SQLException;
395
396 /**
397 * Starts a batch in which update statements will be cached before being sent to the database all at once. This can
398 * improve overall performance of updates update when dealing with numerous updates (e.g. inserting 1:M related data).
399 *
400 * @throws SQLException
401 * the SQL exception
402 */
403 void startBatch() throws SQLException;
404
405 /**
406 * Executes (flushes) all statements currently batched.
407 *
408 * @return the number of rows updated in the batch
409 *
410 * @throws SQLException
411 * the SQL exception
412 */
413 int executeBatch() throws SQLException;
414
415 /**
416 * Executes (flushes) all statements currently batched.
417 *
418 * @return a List of BatchResult objects. There will be one element in the list for each sub-batch executed. A
419 * sub-batch is created by adding a statement to the batch that does not equal the prior statement.
420 *
421 * @throws SQLException
422 * if a database access error occurs, or the drive does not support batch statements
423 * @throws BatchException
424 * if the driver throws BatchUpdateException
425 *
426 * @see com.ibatis.sqlmap.engine.execution.BatchException
427 */
428 List executeBatchDetailed() throws SQLException, BatchException;
429 }