1/*
2 Copyright (c) 2006 - 2007 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_ITEMMODIFYJOB_H
21#define AKONADI_ITEMMODIFYJOB_H
22
23#include "akonadi_export.h"
24
25#include <akonadi/item.h>
26#include <akonadi/job.h>
27
28namespace Akonadi {
29
30class Collection;
31class ItemModifyJobPrivate;
32
33/**
34 * @short Job that modifies an existing item in the Akonadi storage.
35 *
36 * This job is used to writing back items to the Akonadi storage, after
37 * the user has changed them in any way.
38 * For performance reasons either the full item (including the full payload)
39 * can written back or only the meta data of the item.
40 *
41 * Example:
42 *
43 * @code
44 *
45 * // Fetch item with unique id 125
46 * Akonadi::ItemFetchJob *fetchJob = new Akonadi::ItemFetchJob( Akonadi::Item( 125 ) );
47 * connect( fetchJob, SIGNAL(result(KJob*)), SLOT(fetchFinished(KJob*)) );
48 *
49 * ...
50 *
51 * MyClass::fetchFinished( KJob *job )
52 * {
53 * if ( job->error() )
54 * return;
55 *
56 * Akonadi::ItemFetchJob *fetchJob = qobject_cast<Akonadi::ItemFetchJob*>( job );
57 *
58 * Akonadi::Item item = fetchJob->items().first();
59 *
60 * // Set a custom flag
61 * item.setFlag( "\GotIt" );
62 *
63 * // Store back modified item
64 * Akonadi::ItemModifyJob *modifyJob = new Akonadi::ItemModifyJob( item );
65 * connect( modifyJob, SIGNAL(result(KJob*)), SLOT(modifyFinished(KJob*)) );
66 * }
67 *
68 * MyClass::modifyFinished( KJob *job )
69 * {
70 * if ( job->error() )
71 * qDebug() << "Error occurred";
72 * else
73 * qDebug() << "Item modified successfully";
74 * }
75 *
76 * @endcode
77 *
78 * <h3>Conflict Resolution</h3>
79
80 * When the job is executed, a check is made to ensure that the Item contained
81 * in the job is not older than the version of the Item already held in the
82 * Akonadi database. If it is older, a conflict resolution dialog is displayed
83 * for the user to choose which version of the Item to use, unless
84 * disableAutomaticConflictHandling() has been called to disable the dialog, or
85 * disableRevisionCheck() has been called to disable version checking
86 * altogether.
87 *
88 * The item version is checked by comparing the Item::revision() values in the
89 * job and in the database. To ensure that two successive ItemModifyJobs for
90 * the same Item work correctly, the revision number of the Item supplied to
91 * the second ItemModifyJob should be set equal to the Item's revision number
92 * on completion of the first ItemModifyJob. This can be obtained by, for
93 * example, calling item().revision() in the job's result slot.
94 *
95 * @author Volker Krause <vkrause@kde.org>
96 */
97class AKONADI_EXPORT ItemModifyJob : public Job
98{
99 friend class ResourceBase;
100
101 Q_OBJECT
102
103public:
104 /**
105 * Creates a new item modify job.
106 *
107 * @param item The modified item object to store.
108 * @param parent The parent object.
109 */
110 explicit ItemModifyJob(const Item &item, QObject *parent = 0);
111
112 /**
113 * Creates a new item modify job for bulk modifications.
114 *
115 * Using this is different from running a modification job per item.
116 * Use this when applying the same change to a set of items, such as a
117 * mass-change of item flags, not if you just want to store a bunch of
118 * randomly modified items.
119 *
120 * Currently the following modifications are supported:
121 * - flag changes
122 *
123 * @note Since this does not do payload modifications, it implies
124 * setIgnorePayload( true ) and disableRevisionCheck().
125 * @param items The list of items to modify, must not be empty.
126 * @since 4.6
127 */
128 explicit ItemModifyJob(const Item::List &items, QObject *parent = 0);
129
130 /**
131 * Destroys the item modify job.
132 */
133 virtual ~ItemModifyJob();
134
135 /**
136 * Sets whether the payload of the modified item shall be
137 * omitted from transmission to the Akonadi storage.
138 * The default is @c false, however it can be set for
139 * performance reasons.
140 * @param ignore ignores payload if set as @c true
141 */
142 void setIgnorePayload(bool ignore);
143
144 /**
145 * Returns whether the payload of the modified item shall be
146 * omitted from transmission to the Akonadi storage.
147 */
148 bool ignorePayload() const;
149
150 /**
151 * Sets whether the GID shall be updated either from the gid parameter or
152 * by extracting it from the payload.
153 * The default is @c false to avoid unecessarily update the GID,
154 * as it should never change once set, and the ItemCreateJob already sets it.
155 * @param update update the GID if set as @c true
156 *
157 * @note If disabled the GID will not be updated, but still be used for identification of the item.
158 * @since 4.12
159 */
160 void setUpdateGid(bool update);
161
162 /**
163 * Returns wheter the GID should be updated.
164 * @since 4.12
165 */
166 bool updateGid() const;
167
168 /**
169 * Disables the check of the revision number.
170 *
171 * @note If disabled, no conflict detection is available.
172 */
173 void disableRevisionCheck();
174
175 /**
176 * Returns the modified and stored item including the changed revision number.
177 *
178 * @note Use this method only when using the single item constructor.
179 */
180 Item item() const;
181
182 /**
183 * Returns the modified and stored items including the changed revision number.
184 *
185 * @since 4.6
186 */
187 Item::List items() const;
188
189 /**
190 * Disables the automatic handling of conflicts.
191 *
192 * By default the item modify job will bring up a dialog to resolve
193 * a conflict that might happen when modifying an item.
194 * Calling this method will avoid that and the job returns with an
195 * error in case of a conflict.
196 *
197 * @since 4.6
198 */
199 void disableAutomaticConflictHandling();
200
201protected:
202 virtual void doStart();
203 virtual void doHandleResponse(const QByteArray &tag, const QByteArray &data);
204
205private:
206 //@cond PRIVATE
207 Q_DECLARE_PRIVATE(ItemModifyJob)
208
209 Q_PRIVATE_SLOT(d_func(), void conflictResolved())
210 Q_PRIVATE_SLOT(d_func(), void conflictResolveError(const QString &))
211 //@endcond
212};
213
214}
215
216#endif
217