1 /*
2 * Copyright 2009-2023 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 org.apache.ibatis.session;
17
18 import java.io.Closeable;
19 import java.sql.Connection;
20 import java.util.List;
21 import java.util.Map;
22
23 import org.apache.ibatis.cursor.Cursor;
24 import org.apache.ibatis.executor.BatchResult;
25
26 /**
27 * The primary Java interface for working with MyBatis. Through this interface you can execute commands, get mappers and
28 * manage transactions.
29 *
30 * @author Clinton Begin
31 */
32 public interface SqlSession extends Closeable {
33
34 /**
35 * Retrieve a single row mapped from the statement key.
36 *
37 * @param <T>
38 * the returned object type
39 * @param statement
40 * the statement
41 *
42 * @return Mapped object
43 */
44 <T> T selectOne(String statement);
45
46 /**
47 * Retrieve a single row mapped from the statement key and parameter.
48 *
49 * @param <T>
50 * the returned object type
51 * @param statement
52 * Unique identifier matching the statement to use.
53 * @param parameter
54 * A parameter object to pass to the statement.
55 *
56 * @return Mapped object
57 */
58 <T> T selectOne(String statement, Object parameter);
59
60 /**
61 * Retrieve a list of mapped objects from the statement key.
62 *
63 * @param <E>
64 * the returned list element type
65 * @param statement
66 * Unique identifier matching the statement to use.
67 *
68 * @return List of mapped object
69 */
70 <E> List<E> selectList(String statement);
71
72 /**
73 * Retrieve a list of mapped objects from the statement key and parameter.
74 *
75 * @param <E>
76 * the returned list element type
77 * @param statement
78 * Unique identifier matching the statement to use.
79 * @param parameter
80 * A parameter object to pass to the statement.
81 *
82 * @return List of mapped object
83 */
84 <E> List<E> selectList(String statement, Object parameter);
85
86 /**
87 * Retrieve a list of mapped objects from the statement key and parameter, within the specified row bounds.
88 *
89 * @param <E>
90 * the returned list element type
91 * @param statement
92 * Unique identifier matching the statement to use.
93 * @param parameter
94 * A parameter object to pass to the statement.
95 * @param rowBounds
96 * Bounds to limit object retrieval
97 *
98 * @return List of mapped object
99 */
100 <E> List<E> selectList(String statement, Object parameter, RowBounds rowBounds);
101
102 /**
103 * The selectMap is a special case in that it is designed to convert a list of results into a Map based on one of the
104 * properties in the resulting objects. Eg. Return a of Map[Integer,Author] for selectMap("selectAuthors","id")
105 *
106 * @param <K>
107 * the returned Map keys type
108 * @param <V>
109 * the returned Map values type
110 * @param statement
111 * Unique identifier matching the statement to use.
112 * @param mapKey
113 * The property to use as key for each value in the list.
114 *
115 * @return Map containing key pair data.
116 */
117 <K, V> Map<K, V> selectMap(String statement, String mapKey);
118
119 /**
120 * The selectMap is a special case in that it is designed to convert a list of results into a Map based on one of the
121 * properties in the resulting objects.
122 *
123 * @param <K>
124 * the returned Map keys type
125 * @param <V>
126 * the returned Map values type
127 * @param statement
128 * Unique identifier matching the statement to use.
129 * @param parameter
130 * A parameter object to pass to the statement.
131 * @param mapKey
132 * The property to use as key for each value in the list.
133 *
134 * @return Map containing key pair data.
135 */
136 <K, V> Map<K, V> selectMap(String statement, Object parameter, String mapKey);
137
138 /**
139 * The selectMap is a special case in that it is designed to convert a list of results into a Map based on one of the
140 * properties in the resulting objects.
141 *
142 * @param <K>
143 * the returned Map keys type
144 * @param <V>
145 * the returned Map values type
146 * @param statement
147 * Unique identifier matching the statement to use.
148 * @param parameter
149 * A parameter object to pass to the statement.
150 * @param mapKey
151 * The property to use as key for each value in the list.
152 * @param rowBounds
153 * Bounds to limit object retrieval
154 *
155 * @return Map containing key pair data.
156 */
157 <K, V> Map<K, V> selectMap(String statement, Object parameter, String mapKey, RowBounds rowBounds);
158
159 /**
160 * A Cursor offers the same results as a List, except it fetches data lazily using an Iterator.
161 *
162 * @param <T>
163 * the returned cursor element type.
164 * @param statement
165 * Unique identifier matching the statement to use.
166 *
167 * @return Cursor of mapped objects
168 */
169 <T> Cursor<T> selectCursor(String statement);
170
171 /**
172 * A Cursor offers the same results as a List, except it fetches data lazily using an Iterator.
173 *
174 * @param <T>
175 * the returned cursor element type.
176 * @param statement
177 * Unique identifier matching the statement to use.
178 * @param parameter
179 * A parameter object to pass to the statement.
180 *
181 * @return Cursor of mapped objects
182 */
183 <T> Cursor<T> selectCursor(String statement, Object parameter);
184
185 /**
186 * A Cursor offers the same results as a List, except it fetches data lazily using an Iterator.
187 *
188 * @param <T>
189 * the returned cursor element type.
190 * @param statement
191 * Unique identifier matching the statement to use.
192 * @param parameter
193 * A parameter object to pass to the statement.
194 * @param rowBounds
195 * Bounds to limit object retrieval
196 *
197 * @return Cursor of mapped objects
198 */
199 <T> Cursor<T> selectCursor(String statement, Object parameter, RowBounds rowBounds);
200
201 /**
202 * Retrieve a single row mapped from the statement key and parameter using a {@code ResultHandler}.
203 *
204 * @param statement
205 * Unique identifier matching the statement to use.
206 * @param parameter
207 * A parameter object to pass to the statement.
208 * @param handler
209 * ResultHandler that will handle each retrieved row
210 */
211 void select(String statement, Object parameter, ResultHandler handler);
212
213 /**
214 * Retrieve a single row mapped from the statement using a {@code ResultHandler}.
215 *
216 * @param statement
217 * Unique identifier matching the statement to use.
218 * @param handler
219 * ResultHandler that will handle each retrieved row
220 */
221 void select(String statement, ResultHandler handler);
222
223 /**
224 * Retrieve a single row mapped from the statement key and parameter using a {@code ResultHandler} and
225 * {@code RowBounds}.
226 *
227 * @param statement
228 * Unique identifier matching the statement to use.
229 * @param parameter
230 * the parameter
231 * @param rowBounds
232 * RowBound instance to limit the query results
233 * @param handler
234 * ResultHandler that will handle each retrieved row
235 */
236 void select(String statement, Object parameter, RowBounds rowBounds, ResultHandler handler);
237
238 /**
239 * Execute an insert statement.
240 *
241 * @param statement
242 * Unique identifier matching the statement to execute.
243 *
244 * @return int The number of rows affected by the insert.
245 */
246 int insert(String statement);
247
248 /**
249 * Execute an insert statement with the given parameter object. Any generated autoincrement values or selectKey
250 * entries will modify the given parameter object properties. Only the number of rows affected will be returned.
251 *
252 * @param statement
253 * Unique identifier matching the statement to execute.
254 * @param parameter
255 * A parameter object to pass to the statement.
256 *
257 * @return int The number of rows affected by the insert.
258 */
259 int insert(String statement, Object parameter);
260
261 /**
262 * Execute an update statement. The number of rows affected will be returned.
263 *
264 * @param statement
265 * Unique identifier matching the statement to execute.
266 *
267 * @return int The number of rows affected by the update.
268 */
269 int update(String statement);
270
271 /**
272 * Execute an update statement. The number of rows affected will be returned.
273 *
274 * @param statement
275 * Unique identifier matching the statement to execute.
276 * @param parameter
277 * A parameter object to pass to the statement.
278 *
279 * @return int The number of rows affected by the update.
280 */
281 int update(String statement, Object parameter);
282
283 /**
284 * Execute a delete statement. The number of rows affected will be returned.
285 *
286 * @param statement
287 * Unique identifier matching the statement to execute.
288 *
289 * @return int The number of rows affected by the delete.
290 */
291 int delete(String statement);
292
293 /**
294 * Execute a delete statement. The number of rows affected will be returned.
295 *
296 * @param statement
297 * Unique identifier matching the statement to execute.
298 * @param parameter
299 * A parameter object to pass to the statement.
300 *
301 * @return int The number of rows affected by the delete.
302 */
303 int delete(String statement, Object parameter);
304
305 /**
306 * Flushes batch statements and commits database connection. Note that database connection will not be committed if no
307 * updates/deletes/inserts were called. To force the commit call {@link SqlSession#commit(boolean)}
308 */
309 void commit();
310
311 /**
312 * Flushes batch statements and commits database connection.
313 *
314 * @param force
315 * forces connection commit
316 */
317 void commit(boolean force);
318
319 /**
320 * Discards pending batch statements and rolls database connection back. Note that database connection will not be
321 * rolled back if no updates/deletes/inserts were called. To force the rollback call
322 * {@link SqlSession#rollback(boolean)}
323 */
324 void rollback();
325
326 /**
327 * Discards pending batch statements and rolls database connection back. Note that database connection will not be
328 * rolled back if no updates/deletes/inserts were called.
329 *
330 * @param force
331 * forces connection rollback
332 */
333 void rollback(boolean force);
334
335 /**
336 * Flushes batch statements.
337 *
338 * @return BatchResult list of updated records
339 *
340 * @since 3.0.6
341 */
342 List<BatchResult> flushStatements();
343
344 /**
345 * Closes the session.
346 */
347 @Override
348 void close();
349
350 /**
351 * Clears local session cache.
352 */
353 void clearCache();
354
355 /**
356 * Retrieves current configuration.
357 *
358 * @return Configuration
359 */
360 Configuration getConfiguration();
361
362 /**
363 * Retrieves a mapper.
364 *
365 * @param <T>
366 * the mapper type
367 * @param type
368 * Mapper interface class
369 *
370 * @return a mapper bound to this SqlSession
371 */
372 <T> T getMapper(Class<T> type);
373
374 /**
375 * Retrieves inner database connection.
376 *
377 * @return Connection
378 */
379 Connection getConnection();
380 }