1/*
2 Copyright (c) 2006-2008 Volker Krause <vkrause@kde.org>
3
4 This library is free software; you can redistribute it and/or modify it
5 under the terms of the GNU Library General Public License as published by
6 the Free Software Foundation; either version 2 of the License, or (at your
7 option) any later version.
8
9 This library is distributed in the hope that it will be useful, but WITHOUT
10 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
12 License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to the
16 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17 02110-1301, USA.
18*/
19
20#ifndef AKONADI_TRANSACTIONSEQUENCE_H
21#define AKONADI_TRANSACTIONSEQUENCE_H
22
23#include "akonadi_export.h"
24
25#include <akonadi/job.h>
26
27namespace Akonadi {
28
29class TransactionSequencePrivate;
30
31/**
32 * @short Base class for jobs that need to run a sequence of sub-jobs in a transaction.
33 *
34 * As soon as the first subjob is added, the transaction is started.
35 * As soon as the last subjob has successfully finished, the transaction is committed.
36 * If any subjob fails, the transaction is rolled back.
37 *
38 * Alternatively, a TransactionSequence object can be used as a parent object
39 * for a set of jobs to achieve the same behaviour without subclassing.
40 *
41 * Example:
42 *
43 * @code
44 *
45 * // Delete a couple of items inside a transaction
46 * Akonadi::TransactionSequence *transaction = new Akonadi::TransactionSequence;
47 * connect( transaction, SIGNAL(result(KJob*)), SLOT(transactionFinished(KJob*)) );
48 *
49 * const Akonadi::Item::List items = ...
50 *
51 * foreach ( const Akonadi::Item &item, items ) {
52 * new Akonadi::ItemDeleteJob( item, transaction );
53 * }
54 *
55 * ...
56 *
57 * MyClass::transactionFinished( KJob *job )
58 * {
59 * if ( job->error() )
60 * qDebug() << "Error occurred";
61 * else
62 * qDebug() << "Items deleted successfully";
63 * }
64 *
65 * @endcode
66 *
67 * @author Volker Krause <vkrause@kde.org>
68 */
69class AKONADI_EXPORT TransactionSequence : public Job
70{
71 Q_OBJECT
72public:
73 /**
74 * Creates a new transaction sequence.
75 *
76 * @param parent The parent object.
77 */
78 explicit TransactionSequence(QObject *parent = 0);
79
80 /**
81 * Destroys the transaction sequence.
82 */
83 ~TransactionSequence();
84
85 /**
86 * Commits the transaction as soon as all pending sub-jobs finished successfully.
87 */
88 void commit();
89
90 /**
91 * Rolls back the current transaction as soon as possible.
92 * You only need to call this method when you want to roll back due to external
93 * reasons (e.g. user cancellation), the transaction is automatically rolled back
94 * if one of its subjobs fails.
95 * @since 4.5
96 */
97 void rollback();
98
99 /**
100 * Sets which job of the sequence might fail without rolling back the
101 * complete transaction.
102 * @param job a job to ignore errors from
103 * @since 4.5
104 */
105 void setIgnoreJobFailure(KJob *job);
106
107 /**
108 * Disable automatic committing.
109 * Use this when you want to add jobs to this sequence after execution
110 * has been started, usually that is outside of the constructor or the
111 * method that creates this transaction sequence.
112 * @note Calling this method after execution of this job has been started
113 * has no effect.
114 * @param enable @c true to enable autocommitting (default), @c false to disable it
115 * @since 4.5
116 */
117 void setAutomaticCommittingEnabled(bool enable);
118
119protected:
120 bool addSubjob(KJob *job);
121 void doStart();
122
123protected Q_SLOTS:
124 void slotResult(KJob *job);
125
126private:
127 Q_DECLARE_PRIVATE(TransactionSequence)
128
129 //@cond PRIVATE
130 Q_PRIVATE_SLOT(d_func(), void commitResult(KJob *))
131 Q_PRIVATE_SLOT(d_func(), void rollbackResult(KJob *))
132 //@endcond
133};
134
135}
136
137#endif
138