Akonadi

transactionsequence.h
1 /*
2  SPDX-FileCopyrightText: 2006-2008 Volker Krause <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #pragma once
8 
9 #include "akonadicore_export.h"
10 #include "job.h"
11 
12 namespace Akonadi
13 {
14 class TransactionSequencePrivate;
15 
16 /**
17  * @short Base class for jobs that need to run a sequence of sub-jobs in a transaction.
18  *
19  * As soon as the first subjob is added, the transaction is started.
20  * As soon as the last subjob has successfully finished, the transaction is committed.
21  * If any subjob fails, the transaction is rolled back.
22  *
23  * Alternatively, a TransactionSequence object can be used as a parent object
24  * for a set of jobs to achieve the same behaviour without subclassing.
25  *
26  * Example:
27  *
28  * @code
29  *
30  * // Delete a couple of items inside a transaction
31  * Akonadi::TransactionSequence *transaction = new Akonadi::TransactionSequence;
32  * connect( transaction, SIGNAL(result(KJob*)), SLOT(transactionFinished(KJob*)) );
33  *
34  * const Akonadi::Item::List items = ...
35  *
36  * for( const Akonadi::Item &item : items ) {
37  * new Akonadi::ItemDeleteJob( item, transaction );
38  * }
39  *
40  * ...
41  *
42  * MyClass::transactionFinished( KJob *job )
43  * {
44  * if ( job->error() )
45  * qDebug() << "Error occurred";
46  * else
47  * qDebug() << "Items deleted successfully";
48  * }
49  *
50  * @endcode
51  *
52  * @author Volker Krause <[email protected]>
53  */
54 class AKONADICORE_EXPORT TransactionSequence : public Job
55 {
56  Q_OBJECT
57 public:
58  /**
59  * Creates a new transaction sequence.
60  *
61  * @param parent The parent object.
62  */
63  explicit TransactionSequence(QObject *parent = nullptr);
64 
65  /**
66  * Destroys the transaction sequence.
67  */
68  ~TransactionSequence() override;
69 
70  /**
71  * Commits the transaction as soon as all pending sub-jobs finished successfully.
72  */
73  void commit();
74 
75  /**
76  * Rolls back the current transaction as soon as possible.
77  * You only need to call this method when you want to roll back due to external
78  * reasons (e.g. user cancellation), the transaction is automatically rolled back
79  * if one of its subjobs fails.
80  * @since 4.5
81  */
82  void rollback();
83 
84  /**
85  * Sets which job of the sequence might fail without rolling back the
86  * complete transaction.
87  * @param job a job to ignore errors from
88  * @since 4.5
89  */
90  void setIgnoreJobFailure(KJob *job);
91 
92  /**
93  * Disable automatic committing.
94  * Use this when you want to add jobs to this sequence after execution
95  * has been started, usually that is outside of the constructor or the
96  * method that creates this transaction sequence.
97  * @note Calling this method after execution of this job has been started
98  * has no effect.
99  * @param enable @c true to enable autocommitting (default), @c false to disable it
100  * @since 4.5
101  */
102  void setAutomaticCommittingEnabled(bool enable);
103 
104 protected:
105  bool addSubjob(KJob *job) override;
106  void doStart() override;
107 
108 protected Q_SLOTS:
109  void slotResult(KJob *job) override;
110 
111 private:
112  Q_DECLARE_PRIVATE(TransactionSequence)
113 
114  /// @cond PRIVATE
115  Q_PRIVATE_SLOT(d_func(), void commitResult(KJob *))
116  Q_PRIVATE_SLOT(d_func(), void rollbackResult(KJob *))
117  /// @endcond
118 };
119 
120 }
Base class for all actions in the Akonadi storage.
Definition: job.h:80
Base class for jobs that need to run a sequence of sub-jobs in a transaction.
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Wed Sep 27 2023 04:01:20 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.