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