KDb

KDbTransactionGuard.h
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 */
51class KDB_EXPORT KDbTransactionGuard
52{
53public:
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
132private:
133 Q_DISABLE_COPY(KDbTransactionGuard)
134 class Private;
135 Private * const d;
136};
137
138#endif
Provides database connection, allowing queries and data modification.
KDbTransactionGuard class is a convenience class that simplifies handling transactions.
This class encapsulates a single database transaction.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 6 2024 12:12:34 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.