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