File indexing completed on 2024-12-01 13:00:34
0001 /* This file is part of the KDE project 0002 Copyright (C) 2003-2017 Jarosław Staniek <staniek@kde.org> 0003 0004 This program is free software; you can redistribute it and/or 0005 modify it under the terms of the GNU Library General Public 0006 License as published by the Free Software Foundation; either 0007 version 2 of the License, or (at your option) any later version. 0008 0009 This program is distributed in the hope that it will be useful, 0010 but WITHOUT ANY WARRANTY; without even the implied warranty of 0011 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0012 Library General Public License for more details. 0013 0014 You should have received a copy of the GNU Library General Public License 0015 along with this program; see the file COPYING. If not, write to 0016 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 0017 * Boston, MA 02110-1301, USA. 0018 */ 0019 0020 #ifndef KDB_TRANSACTIONGUARD_H 0021 #define KDB_TRANSACTIONGUARD_H 0022 0023 #include "KDbTransaction.h" 0024 0025 /** 0026 * @brief KDbTransactionGuard class is a convenience class that simplifies handling transactions 0027 * 0028 * KDbTransactionGuard can be used in two ways: 0029 * - start a new transaction in constructor and call commit or allow to rollback on destruction, 0030 * - use already started transaction and call commit or allow to rollback on destruction. 0031 * 0032 * In either case if the guarded transaction is committed or rolled back outside the 0033 * KDbTransactionGuard object in the meantime, nothing happens on KDbTransactionGuard's destruction. 0034 * 0035 * Example usage: 0036 * <code> 0037 * void MyClass::myMethod() 0038 * { 0039 * KDbTransaction transaction = connection->beginTransaction(); 0040 * KDbTransactionGuard tg(transaction); 0041 * // <-- Some code that operates within the transaction here 0042 * if (failure_condition) 0043 * return; // After this return tg will be destroyed; connection->rollbackTransaction() 0044 * // will be called automatically 0045 * // success_condition: 0046 * tg.commit(); 0047 * // Now tg won't do anything because transaction no longer exists 0048 * } 0049 * </code> 0050 */ 0051 class KDB_EXPORT KDbTransactionGuard 0052 { 0053 public: 0054 /** 0055 * @brief Starts a new transaction for given connection and guards it 0056 * 0057 * When the new guard object is created a new transaction is started for connection @a 0058 * connection using KDbConnection::beginTransaction(). Started KDbTransaction handle is 0059 * available via transaction(). Unassigned guard is created if @a connection is @c nullptr or 0060 * if beginTransaction() fails. 0061 */ 0062 explicit KDbTransactionGuard(KDbConnection *connection); 0063 0064 /** 0065 * @brief Creates a new guard for already started transaction 0066 * 0067 * If transaction is not started i.e. @a transaction is null or not active, it will not be 0068 * guarded. 0069 * 0070 * setTransaction() can be used later to assign active transaction. 0071 */ 0072 explicit KDbTransactionGuard(const KDbTransaction& transaction); 0073 0074 /** 0075 * @brief Creates a new guard without assigning transaction 0076 * 0077 * setTransaction() can be used later to assign active transaction. 0078 */ 0079 KDbTransactionGuard(); 0080 0081 /** 0082 * @brief Roll backs not committed transaction unless doNothing() was called before 0083 * 0084 * If doNothing() was called, transaction is left unaffected. 0085 */ 0086 ~KDbTransactionGuard(); 0087 0088 /** 0089 * @brief Assigns transaction to this guard 0090 * 0091 * Previously assigned transaction will be unassigned from this guard without commiting or 0092 * rolling back. 0093 */ 0094 void setTransaction(const KDbTransaction& transaction); 0095 0096 /** 0097 * @brief Commits the guarded transaction 0098 * 0099 * This is an equivalent of transaction().connection()->commitTransaction(transaction(), options) 0100 * provided for convenience. 0101 * 0102 * @c false is also returned if transaction().connection() is @c nullptr. 0103 */ 0104 bool commit(KDbTransaction::CommitOptions options = KDbTransaction::CommitOptions()); 0105 0106 /** 0107 * @brief Rolls back the guarded transaction 0108 * 0109 * This is an equivalent of transaction().connection()->rollbackTransaction(transaction(), options) 0110 * provided for convenience. 0111 * 0112 * @c false is also returned if transaction().connection() is @c nullptr. 0113 * 0114 * @since 3.1 0115 */ 0116 bool rollback(KDbTransaction::CommitOptions options = KDbTransaction::CommitOptions()); 0117 0118 /** 0119 * @brief Deativates the transaction guard 0120 * 0121 * This means nothing will happen on guard's destruction. 0122 */ 0123 void doNothing(); 0124 0125 /** 0126 * @brief Returns transaction that is controlled by this guard 0127 * 0128 * Null object is returned if no transaction is guarded. 0129 */ 0130 const KDbTransaction transaction() const; 0131 0132 private: 0133 Q_DISABLE_COPY(KDbTransactionGuard) 0134 class Private; 0135 Private * const d; 0136 }; 0137 0138 #endif