001: /*
002: * Copyright 2004 Clinton Begin
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package com.ibatis.sqlmap.client;
017:
018: import javax.sql.DataSource;
019: import java.sql.Connection;
020: import java.sql.SQLException;
021:
022: /**
023: * This interface declares methods for demarcating SQL Map transactions.
024: *
025: * @see SqlMapSession
026: * @see SqlMapClient
027: */
028: public interface SqlMapTransactionManager {
029:
030: /**
031: * Demarcates the beginning of a transaction scope. Transactions must be properly
032: * committed or rolled back to be effective. Use the following pattern when working
033: * with transactions:
034: * <pre>
035: * try {
036: * sqlMap.startTransaction();
037: * // do work
038: * sqlMap.commitTransaction();
039: * } finally {
040: * sqlMap.endTransaction();
041: * }
042: * </pre>
043: * <p/>
044: * Always call endTransaction() once startTransaction() has been called.
045: *
046: * @throws java.sql.SQLException If an error occurs while starting the transaction, or
047: * the transaction could not be started.
048: */
049: public void startTransaction() throws SQLException;
050:
051: /**
052: * Demarcates the beginning of a transaction scope using the specified transaction
053: * isolation. Transactions must be properly committed or rolled back to be effective.
054: * Use the following pattern when working with transactions:
055: * <pre>
056: * try {
057: * sqlMap.startTransaction(Connection.TRANSACTION_REPEATABLE_READ);
058: * // do work
059: * sqlMap.commitTransaction();
060: * } finally {
061: * sqlMap.endTransaction();
062: * }
063: * </pre>
064: * <p/>
065: * Always call endTransaction() once startTransaction() has been called.
066: *
067: * @throws java.sql.SQLException If an error occurs while starting the transaction, or
068: * the transaction could not be started.
069: */
070: public void startTransaction(int transactionIsolation)
071: throws SQLException;
072:
073: /**
074: * Commits the currently started transaction.
075: *
076: * @throws SQLException If an error occurs while committing the transaction, or
077: * the transaction could not be committed.
078: */
079: public void commitTransaction() throws SQLException;
080:
081: /**
082: * Ends a transaction and rolls back if necessary. If the transaction has
083: * been started, but not committed, it will be rolled back upon calling
084: * endTransaction().
085: *
086: * @throws SQLException If an error occurs during rollback or the transaction could
087: * not be ended.
088: */
089: public void endTransaction() throws SQLException;
090:
091: /**
092: * Allows the developer to easily use an externally supplied connection
093: * when executing statements.
094: * <p/>
095: * <b>Important:</b> Using a user supplied connection basically sidesteps the transaction manager,
096: * so you are responsible for appropriately. Here's a (very) simple example (throws SQLException):
097: * <pre>
098: * try {
099: * Connection connection = dataSource.getConnection();
100: * sqlMap.setUserConnection(connection);
101: * // do work
102: * connection.commit();
103: * } catch (SQLException e) {
104: * try {
105: * if (connection != null) commit.rollback();
106: * } catch (SQLException ignored) {
107: * // generally ignored
108: * }
109: * throw e; // rethrow the exception
110: * } finally {
111: * try {
112: * if (connection != null) connection.close();
113: * } catch (SQLException ignored) {
114: * // generally ignored
115: * }
116: * }
117: * </pre>
118: *
119: * @param connnection
120: * @throws SQLException
121: */
122: public void setUserConnection(Connection connnection)
123: throws SQLException;
124:
125: /**
126: * Returns the current user supplied connection as set by setUserConnection().
127: * <p/>
128: * TODO : DEPRECATED
129: *
130: * @return The current user supplied connection.
131: * @throws SQLException
132: * @deprecated Use getCurrentConnection() instead.
133: */
134: public Connection getUserConnection() throws SQLException;
135:
136: /**
137: * Returns the current connection in use. If no connection exists null will
138: * be returned. There may be no connection if no transaction has been started,
139: * and if no user provided connection has been set.
140: *
141: * @return The current connection or null.
142: * @throws SQLException
143: */
144: public Connection getCurrentConnection() throws SQLException;
145:
146: /**
147: * Returns the DataSource instance currently being used by the SqlMapSession.
148: *
149: * @return The DataSource instance currently being used by the SqlMapSession.
150: */
151: public DataSource getDataSource();
152:
153: }
|