1 /* This file is part of the KDE project 2 Copyright (C) 2003-2017 Jarosław Staniek <staniek@kde.org> 3 4 This program is free software; you can redistribute it and/or 5 modify it under the terms of the GNU Library General Public 6 License as published by the Free Software Foundation; either 7 version 2 of the License, or (at your option) any later version. 8 9 This program is distributed in the hope that it will be useful, 10 but WITHOUT ANY WARRANTY; without even the implied warranty of 11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 Library General Public License for more details. 13 14 You should have received a copy of the GNU Library General Public License 15 along with this program; see the file COPYING. If not, write to 16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 17 * Boston, MA 02110-1301, USA. 18 */ 19 20 #ifndef KDB_TRANSACTIONGUARD_H 21 #define KDB_TRANSACTIONGUARD_H 22 23 #include "KDbTransaction.h" 24 25 /** 26 * @brief KDbTransactionGuard class is a convenience class that simplifies handling transactions 27 * 28 * KDbTransactionGuard can be used in two ways: 29 * - start a new transaction in constructor and call commit or allow to rollback on destruction, 30 * - use already started transaction and call commit or allow to rollback on destruction. 31 * 32 * In either case if the guarded transaction is committed or rolled back outside the 33 * KDbTransactionGuard object in the meantime, nothing happens on KDbTransactionGuard's destruction. 34 * 35 * Example usage: 36 * <code> 37 * void MyClass::myMethod() 38 * { 39 * KDbTransaction transaction = connection->beginTransaction(); 40 * KDbTransactionGuard tg(transaction); 41 * // <-- Some code that operates within the transaction here 42 * if (failure_condition) 43 * return; // After this return tg will be destroyed; connection->rollbackTransaction() 44 * // will be called automatically 45 * // success_condition: 46 * tg.commit(); 47 * // Now tg won't do anything because transaction no longer exists 48 * } 49 * </code> 50 */ 51 class KDB_EXPORT KDbTransactionGuard 52 { 53 public: 54 /** 55 * @brief Starts a new transaction for given connection and guards it 56 * 57 * When the new guard object is created a new transaction is started for connection @a 58 * connection using KDbConnection::beginTransaction(). Started KDbTransaction handle is 59 * available via transaction(). Unassigned guard is created if @a connection is @c nullptr or 60 * if beginTransaction() fails. 61 */ 62 explicit KDbTransactionGuard(KDbConnection *connection); 63 64 /** 65 * @brief Creates a new guard for already started transaction 66 * 67 * If transaction is not started i.e. @a transaction is null or not active, it will not be 68 * guarded. 69 * 70 * setTransaction() can be used later to assign active transaction. 71 */ 72 explicit KDbTransactionGuard(const KDbTransaction& transaction); 73 74 /** 75 * @brief Creates a new guard without assigning transaction 76 * 77 * setTransaction() can be used later to assign active transaction. 78 */ 79 KDbTransactionGuard(); 80 81 /** 82 * @brief Roll backs not committed transaction unless doNothing() was called before 83 * 84 * If doNothing() was called, transaction is left unaffected. 85 */ 86 ~KDbTransactionGuard(); 87 88 /** 89 * @brief Assigns transaction to this guard 90 * 91 * Previously assigned transaction will be unassigned from this guard without commiting or 92 * rolling back. 93 */ 94 void setTransaction(const KDbTransaction& transaction); 95 96 /** 97 * @brief Commits the guarded transaction 98 * 99 * This is an equivalent of transaction().connection()->commitTransaction(transaction(), options) 100 * provided for convenience. 101 * 102 * @c false is also returned if transaction().connection() is @c nullptr. 103 */ 104 bool commit(KDbTransaction::CommitOptions options = KDbTransaction::CommitOptions()); 105 106 /** 107 * @brief Rolls back the guarded transaction 108 * 109 * This is an equivalent of transaction().connection()->rollbackTransaction(transaction(), options) 110 * provided for convenience. 111 * 112 * @c false is also returned if transaction().connection() is @c nullptr. 113 * 114 * @since 3.1 115 */ 116 bool rollback(KDbTransaction::CommitOptions options = KDbTransaction::CommitOptions()); 117 118 /** 119 * @brief Deativates the transaction guard 120 * 121 * This means nothing will happen on guard's destruction. 122 */ 123 void doNothing(); 124 125 /** 126 * @brief Returns transaction that is controlled by this guard 127 * 128 * Null object is returned if no transaction is guarded. 129 */ 130 const KDbTransaction transaction() const; 131 132 private: 133 Q_DISABLE_COPY(KDbTransactionGuard) 134 class Private; 135 Private * const d; 136 }; 137 138 #endif 139