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 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 public 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 public 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 public 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 public 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 public void setUserConnection(Connection connnection) throws SQLException;
130
131 /**
132 * Returns the current user supplied connection as set by setUserConnection().
133 * <p>
134 * TODO : DEPRECATED
135 *
136 * @return The current user supplied connection.
137 *
138 * @throws SQLException
139 * the SQL exception
140 *
141 * @deprecated Use getCurrentConnection() instead.
142 */
143 public Connection getUserConnection() throws SQLException;
144
145 /**
146 * Returns the current connection in use. If no connection exists null will be returned. There may be no connection if
147 * no transaction has been started, and if no user provided connection has been set.
148 *
149 * @return The current connection or null.
150 *
151 * @throws SQLException
152 * the SQL exception
153 */
154 public Connection getCurrentConnection() throws SQLException;
155
156 /**
157 * Returns the DataSource instance currently being used by the SqlMapSession.
158 *
159 * @return The DataSource instance currently being used by the SqlMapSession.
160 */
161 public DataSource getDataSource();
162
163 }