File indexing completed on 2024-12-01 10:29:16

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_TRANSACTION_H
0021 #define KDB_TRANSACTION_H
0022 
0023 #include "config-kdb.h"
0024 #include "kdb_export.h"
0025 
0026 #include <QtGlobal>
0027 
0028 class KDbConnection;
0029 class KDbTransactionData;
0030 
0031 /**
0032  * @brief This class encapsulates a single database transaction
0033  *
0034  * The KDbTransaction handle abstracts a database transaction for given database connection.
0035  * Transaction objects are value-based, implicitly shared.
0036  *
0037  * Lifetime of the transaction object is closely related to a KDbConnection object.
0038  * Deleting the either instance does not commit or rollback the actual transaction.
0039  * Use KDbTransactionGuard for automatic commits or rolls back.
0040  *
0041  * @see KDbConnection::beginTransaction()
0042  */
0043 class KDB_EXPORT KDbTransaction
0044 {
0045 public:
0046     /**
0047      * @brief Constructs a null transaction.
0048      *
0049      * @note It can be initialized only by KDbConnection.
0050      */
0051     KDbTransaction();
0052 
0053     /**
0054      * @brief Copy constructor
0055      */
0056     KDbTransaction(const KDbTransaction& trans);
0057 
0058     ~KDbTransaction();
0059 
0060     //! Options for commiting and rolling back transactions
0061     //! @see KDbConnection::beginTransaction() KDbConnection::rollbackTransaction()
0062     //! @see KDbTransactionGuard::commit() KDbTransactionGuard::rollback()
0063     enum class CommitOption {
0064         None = 0,
0065         IgnoreInactive = 1 //!< Do not return error for inactive or null transactions when
0066                            //!< requesting commit or rollback
0067     };
0068     Q_DECLARE_FLAGS(CommitOptions, CommitOption)
0069 
0070     KDbTransaction& operator=(const KDbTransaction& trans);
0071 
0072     /**
0073      * @brief Returns @c true if this transaction is equal to @a other; otherwise returns @c false
0074      *
0075      * Two transactions are equal if they encapsulate the same physical transaction,
0076      * i.e. copy constructor or assignment operator was used.
0077      * Two null transaction objects are equal.
0078      */
0079     bool operator==(const KDbTransaction& other) const;
0080 
0081     //! @return @c true if this transaction is not equal to @a other; otherwise returns @c false.
0082     //! @since 3.1
0083     inline bool operator!=(const KDbTransaction &other) const { return !operator==(other); }
0084 
0085     /**
0086      * @brief Returns database connection for which the transaction belongs.
0087      *
0088      * @c nullptr is returned for null transactions.
0089      */
0090     KDbConnection* connection();
0091 
0092     //! @overload
0093     //! @since 3.1
0094     const KDbConnection* connection() const;
0095 
0096     /**
0097      * @brief Returns @c true if transaction is active (i.e. started)
0098      *
0099      * @return @c false also if transaction is uninitialised (null) or not started.
0100      * @see KDbConnection::beginTransaction()
0101      * @since 3.1
0102      */
0103     bool isActive() const;
0104 
0105     /**
0106      * @brief Returns @c true if this transaction is null.
0107      *
0108      * Null implies !isActive().
0109      */
0110     bool isNull() const;
0111 
0112 #ifdef KDB_TRANSACTIONS_DEBUG
0113     //! Helper for debugging, returns value of global transaction data reference counter
0114     static int globalCount();
0115 #endif
0116 
0117 protected:
0118     KDbTransactionData *m_data;
0119 
0120     friend class KDbConnection;
0121 };
0122 
0123 Q_DECLARE_OPERATORS_FOR_FLAGS(KDbTransaction::CommitOptions)
0124 
0125 #endif