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