Akonadi

transactionsequence.h
1/*
2 SPDX-FileCopyrightText: 2006-2008 Volker Krause <vkrause@kde.org>
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
12namespace Akonadi
13{
14class 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 <vkrause@kde.org>
53 */
54class AKONADICORE_EXPORT TransactionSequence : public Job
55{
56 Q_OBJECT
57public:
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
104protected:
105 bool addSubjob(KJob *job) override;
106 void doStart() override;
107
108protected Q_SLOTS:
109 void slotResult(KJob *job) override;
110
111private:
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:81
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-2024 The KDE developers.
Generated on Fri Jul 12 2024 11:50:58 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.