1 /*
2 * Copyright 2009-2021 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 * http://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.
28 * Through this interface you can execute commands, get mappers and 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 * @param <T> the returned object type
37 * @param statement
38 * the statement
39 * @return Mapped object
40 */
41 <T> T selectOne(String statement);
42
43 /**
44 * Retrieve a single row mapped from the statement key and parameter.
45 * @param <T> the returned object type
46 * @param statement Unique identifier matching the statement to use.
47 * @param parameter A parameter object to pass to the statement.
48 * @return Mapped object
49 */
50 <T> T selectOne(String statement, Object parameter);
51
52 /**
53 * Retrieve a list of mapped objects from the statement key.
54 * @param <E> the returned list element type
55 * @param statement Unique identifier matching the statement to use.
56 * @return List of mapped object
57 */
58 <E> List<E> selectList(String statement);
59
60 /**
61 * Retrieve a list of mapped objects from the statement key and parameter.
62 * @param <E> the returned list element type
63 * @param statement Unique identifier matching the statement to use.
64 * @param parameter A parameter object to pass to the statement.
65 * @return List of mapped object
66 */
67 <E> List<E> selectList(String statement, Object parameter);
68
69 /**
70 * Retrieve a list of mapped objects from the statement key and parameter,
71 * within the specified row bounds.
72 * @param <E> the returned list element type
73 * @param statement Unique identifier matching the statement to use.
74 * @param parameter A parameter object to pass to the statement.
75 * @param rowBounds Bounds to limit object retrieval
76 * @return List of mapped object
77 */
78 <E> List<E> selectList(String statement, Object parameter, RowBounds rowBounds);
79
80 /**
81 * The selectMap is a special case in that it is designed to convert a list
82 * of results into a Map based on one of the properties in the resulting
83 * objects.
84 * Eg. Return a of Map[Integer,Author] for selectMap("selectAuthors","id")
85 * @param <K> the returned Map keys type
86 * @param <V> the returned Map values type
87 * @param statement Unique identifier matching the statement to use.
88 * @param mapKey The property to use as key for each value in the list.
89 * @return Map containing key pair data.
90 */
91 <K, V> Map<K, V> selectMap(String statement, String mapKey);
92
93 /**
94 * The selectMap is a special case in that it is designed to convert a list
95 * of results into a Map based on one of the properties in the resulting
96 * objects.
97 * @param <K> the returned Map keys type
98 * @param <V> the returned Map values type
99 * @param statement Unique identifier matching the statement to use.
100 * @param parameter A parameter object to pass to the statement.
101 * @param mapKey The property to use as key for each value in the list.
102 * @return Map containing key pair data.
103 */
104 <K, V> Map<K, V> selectMap(String statement, Object parameter, String mapKey);
105
106 /**
107 * The selectMap is a special case in that it is designed to convert a list
108 * of results into a Map based on one of the properties in the resulting
109 * objects.
110 * @param <K> the returned Map keys type
111 * @param <V> the returned Map values type
112 * @param statement Unique identifier matching the statement to use.
113 * @param parameter A parameter object to pass to the statement.
114 * @param mapKey The property to use as key for each value in the list.
115 * @param rowBounds Bounds to limit object retrieval
116 * @return Map containing key pair data.
117 */
118 <K, V> Map<K, V> selectMap(String statement, Object parameter, String mapKey, RowBounds rowBounds);
119
120 /**
121 * A Cursor offers the same results as a List, except it fetches data lazily using an Iterator.
122 * @param <T> the returned cursor element type.
123 * @param statement Unique identifier matching the statement to use.
124 * @return Cursor of mapped objects
125 */
126 <T> Cursor<T> selectCursor(String statement);
127
128 /**
129 * A Cursor offers the same results as a List, except it fetches data lazily using an Iterator.
130 * @param <T> the returned cursor element type.
131 * @param statement Unique identifier matching the statement to use.
132 * @param parameter A parameter object to pass to the statement.
133 * @return Cursor of mapped objects
134 */
135 <T> Cursor<T> selectCursor(String statement, Object parameter);
136
137 /**
138 * A Cursor offers the same results as a List, except it fetches data lazily using an Iterator.
139 * @param <T> the returned cursor element type.
140 * @param statement Unique identifier matching the statement to use.
141 * @param parameter A parameter object to pass to the statement.
142 * @param rowBounds Bounds to limit object retrieval
143 * @return Cursor of mapped objects
144 */
145 <T> Cursor<T> selectCursor(String statement, Object parameter, RowBounds rowBounds);
146
147 /**
148 * Retrieve a single row mapped from the statement key and parameter
149 * using a {@code ResultHandler}.
150 * @param statement Unique identifier matching the statement to use.
151 * @param parameter A parameter object to pass to the statement.
152 * @param handler ResultHandler that will handle each retrieved row
153 */
154 void select(String statement, Object parameter, ResultHandler handler);
155
156 /**
157 * Retrieve a single row mapped from the statement
158 * using a {@code ResultHandler}.
159 * @param statement Unique identifier matching the statement to use.
160 * @param handler ResultHandler that will handle each retrieved row
161 */
162 void select(String statement, ResultHandler handler);
163
164 /**
165 * Retrieve a single row mapped from the statement key and parameter using a {@code ResultHandler} and
166 * {@code RowBounds}.
167 *
168 * @param statement
169 * Unique identifier matching the statement to use.
170 * @param parameter
171 * the parameter
172 * @param rowBounds
173 * RowBound instance to limit the query results
174 * @param handler
175 * ResultHandler that will handle each retrieved row
176 */
177 void select(String statement, Object parameter, RowBounds rowBounds, ResultHandler handler);
178
179 /**
180 * Execute an insert statement.
181 * @param statement Unique identifier matching the statement to execute.
182 * @return int The number of rows affected by the insert.
183 */
184 int insert(String statement);
185
186 /**
187 * Execute an insert statement with the given parameter object. Any generated
188 * autoincrement values or selectKey entries will modify the given parameter
189 * object properties. Only the number of rows affected will be returned.
190 * @param statement Unique identifier matching the statement to execute.
191 * @param parameter A parameter object to pass to the statement.
192 * @return int The number of rows affected by the insert.
193 */
194 int insert(String statement, Object parameter);
195
196 /**
197 * Execute an update statement. The number of rows affected will be returned.
198 * @param statement Unique identifier matching the statement to execute.
199 * @return int The number of rows affected by the update.
200 */
201 int update(String statement);
202
203 /**
204 * Execute an update statement. The number of rows affected will be returned.
205 * @param statement Unique identifier matching the statement to execute.
206 * @param parameter A parameter object to pass to the statement.
207 * @return int The number of rows affected by the update.
208 */
209 int update(String statement, Object parameter);
210
211 /**
212 * Execute a delete statement. The number of rows affected will be returned.
213 * @param statement Unique identifier matching the statement to execute.
214 * @return int The number of rows affected by the delete.
215 */
216 int delete(String statement);
217
218 /**
219 * Execute a delete statement. The number of rows affected will be returned.
220 * @param statement Unique identifier matching the statement to execute.
221 * @param parameter A parameter object to pass to the statement.
222 * @return int The number of rows affected by the delete.
223 */
224 int delete(String statement, Object parameter);
225
226 /**
227 * Flushes batch statements and commits database connection.
228 * Note that database connection will not be committed if no updates/deletes/inserts were called.
229 * To force the commit call {@link SqlSession#commit(boolean)}
230 */
231 void commit();
232
233 /**
234 * Flushes batch statements and commits database connection.
235 * @param force forces connection commit
236 */
237 void commit(boolean force);
238
239 /**
240 * Discards pending batch statements and rolls database connection back.
241 * Note that database connection will not be rolled back if no updates/deletes/inserts were called.
242 * To force the rollback call {@link SqlSession#rollback(boolean)}
243 */
244 void rollback();
245
246 /**
247 * Discards pending batch statements and rolls database connection back.
248 * Note that database connection will not be rolled back if no updates/deletes/inserts were called.
249 * @param force forces connection rollback
250 */
251 void rollback(boolean force);
252
253 /**
254 * Flushes batch statements.
255 * @return BatchResult list of updated records
256 * @since 3.0.6
257 */
258 List<BatchResult> flushStatements();
259
260 /**
261 * Closes the session.
262 */
263 @Override
264 void close();
265
266 /**
267 * Clears local session cache.
268 */
269 void clearCache();
270
271 /**
272 * Retrieves current configuration.
273 * @return Configuration
274 */
275 Configuration getConfiguration();
276
277 /**
278 * Retrieves a mapper.
279 * @param <T> the mapper type
280 * @param type Mapper interface class
281 * @return a mapper bound to this SqlSession
282 */
283 <T> T getMapper(Class<T> type);
284
285 /**
286 * Retrieves inner database connection.
287 * @return Connection
288 */
289 Connection getConnection();
290 }