1 /*
2 * Copyright 2004-2025 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 java.sql.Connection;
19 import java.sql.SQLException;
20
21 import javax.sql.DataSource;
22
23 /**
24 * This interface declares methods for demarcating SQL Map transactions.
25 *
26 * @see SqlMapSession
27 * @see SqlMapClient
28 */
29 public interface SqlMapTransactionManager {
30
31 /**
32 * Demarcates the beginning of a transaction scope. Transactions must be properly committed or rolled back to be
33 * effective. Use the following pattern when working with transactions:
34 *
35 * <pre>
36 * try {
37 * sqlMap.startTransaction();
38 * // do work
39 * sqlMap.commitTransaction();
40 * } finally {
41 * sqlMap.endTransaction();
42 * }
43 * </pre>
44 * <p>
45 * Always call endTransaction() once startTransaction() has been called.
46 *
47 * @throws SQLException
48 * the SQL exception
49 */
50 void startTransaction() throws SQLException;
51
52 /**
53 * Demarcates the beginning of a transaction scope using the specified transaction isolation. Transactions must be
54 * properly committed or rolled back to be effective. Use the following pattern when working with transactions:
55 *
56 * <pre>
57 * try {
58 * sqlMap.startTransaction(Connection.TRANSACTION_REPEATABLE_READ);
59 * // do work
60 * sqlMap.commitTransaction();
61 * } finally {
62 * sqlMap.endTransaction();
63 * }
64 * </pre>
65 * <p>
66 * Always call endTransaction() once startTransaction() has been called.
67 *
68 * @param transactionIsolation
69 * the transaction isolation
70 *
71 * @throws SQLException
72 * the SQL exception
73 */
74 void startTransaction(int transactionIsolation) throws SQLException;
75
76 /**
77 * Commits the currently started transaction.
78 *
79 * @throws SQLException
80 * If an error occurs while committing the transaction, or the transaction could not be committed.
81 */
82 void commitTransaction() throws SQLException;
83
84 /**
85 * Ends a transaction and rolls back if necessary. If the transaction has been started, but not committed, it will be
86 * rolled back upon calling endTransaction().
87 *
88 * @throws SQLException
89 * If an error occurs during rollback or the transaction could not be ended.
90 */
91 void endTransaction() throws SQLException;
92
93 /**
94 * Allows the developer to easily use an externally supplied connection when executing statements.
95 * <p>
96 * <b>Important:</b> Using a user supplied connection basically sidesteps the transaction manager, so you are
97 * responsible for appropriately. Here's a (very) simple example (throws SQLException):
98 *
99 * <pre>
100 * try {
101 * Connection connection = dataSource.getConnection();
102 * sqlMap.setUserConnection(connection);
103 * // do work
104 * connection.commit();
105 * } catch (SQLException e) {
106 * try {
107 * if (connection != null)
108 * commit.rollback();
109 * } catch (SQLException ignored) {
110 * // generally ignored
111 * }
112 * throw e; // rethrow the exception
113 * } finally {
114 * try {
115 * if (connection != null)
116 * connection.close();
117 * } catch (SQLException ignored) {
118 * // generally ignored
119 * }
120 * }
121 * </pre>
122 *
123 * @param connnection
124 * the new user connection
125 *
126 * @throws SQLException
127 * the SQL exception
128 */
129 void setUserConnection(Connection connnection) throws SQLException;
130
131 /**
132 * Returns the current user supplied connection as set by setUserConnection().
133 *
134 * @return The current user supplied connection.
135 *
136 * @throws SQLException
137 * the SQL exception
138 *
139 * @deprecated Use getCurrentConnection() instead.
140 */
141 @Deprecated
142 Connection getUserConnection() throws SQLException;
143
144 /**
145 * Returns the current connection in use. If no connection exists null will be returned. There may be no connection if
146 * no transaction has been started, and if no user provided connection has been set.
147 *
148 * @return The current connection or null.
149 *
150 * @throws SQLException
151 * the SQL exception
152 */
153 Connection getCurrentConnection() throws SQLException;
154
155 /**
156 * Returns the DataSource instance currently being used by the SqlMapSession.
157 *
158 * @return The DataSource instance currently being used by the SqlMapSession.
159 */
160 DataSource getDataSource();
161
162 }