KDb

KDbTransactionGuard.h
1 /* This file is part of the KDE project
2  Copyright (C) 2003-2017 JarosÅ‚aw Staniek <[email protected]>
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  */
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  */
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  */
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  */
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
KDbTransactionGuard class is a convenience class that simplifies handling transactions.
Provides database connection, allowing queries and data modification.
Definition: KDbConnection.h:51
This class encapsulates a single database transaction.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sat Jun 25 2022 06:21:34 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.