KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > ibatis > sqlmap > client > SqlMapTransactionManager


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