1/*
2 Copyright (c) 2007, 2009 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_COLLECTIONSYNC_P_H
21#define AKONADI_COLLECTIONSYNC_P_H
22
23#include <akonadi/collection.h>
24#include <akonadi/transactionsequence.h>
25
26namespace Akonadi {
27
28/**
29 @internal
30
31 Syncs remote and local collections.
32
33 Basic terminology:
34 - "local": The current state in the Akonadi server
35 - "remote": The state in the backend, which is also the state the Akonadi
36 server is supposed to have afterwards.
37
38 There are three options to influence the way syncing is done:
39 - Streaming vs. complete delivery: If streaming is enabled remote collections
40 do not need to be delivered in a single batch but can be delivered in multiple
41 chunks. This improves performance but requires an explicit notification
42 when delivery has been completed.
43 - Incremental vs. non-incremental: In the incremental case only remote changes
44 since the last sync have to be delivered, in the non-incremental mode the full
45 remote state has to be provided. The first is obviously the preferred way,
46 but requires support by the backend.
47 - Hierarchical vs. global RIDs: The first requires RIDs to be unique per parent
48 collection, the second one requires globally unique RIDs (per resource). Those
49 have different advantages and disadvantages, esp. regarding moving. Which one
50 to chose mostly depends on what the backend provides in this regard.
51
52*/
53class CollectionSync : public Job
54{
55 Q_OBJECT
56
57public:
58 /**
59 Creates a new collection synchronzier.
60 @param resourceId The identifier of the resource we are syncing.
61 @param parent The parent object.
62 */
63 explicit CollectionSync(const QString &resourceId, QObject *parent = 0);
64
65 /**
66 Destroys this job.
67 */
68 ~CollectionSync();
69
70 /**
71 Sets the result of a full remote collection listing.
72 @param remoteCollections A list of collections.
73 Important: All of these need a unique remote identifier and parent remote
74 identifier.
75 */
76 void setRemoteCollections(const Collection::List &remoteCollections);
77
78 /**
79 Sets the result of an incremental remote collection listing.
80 @param changedCollections A list of remotely added or changed collections.
81 @param removedCollections A list of remotely deleted collections.
82 */
83 void setRemoteCollections(const Collection::List &changedCollections,
84 const Collection::List &removedCollections);
85
86 /**
87 Enables streaming, that is not all collections are delivered at once.
88 Use setRemoteCollections() multiple times when streaming is enabled and call
89 retrievalDone() when all collections have been retrieved.
90 Must be called before the first call to setRemoteCollections().
91 @param streaming enables streaming if set as @c true
92 */
93 void setStreamingEnabled(bool streaming);
94
95 /**
96 Indicate that all collections have been retrieved in streaming mode.
97 */
98 void retrievalDone();
99
100 /**
101 Indicate whether the resource supplies collections with hierarchical or
102 global remote identifiers. @c false by default.
103 Must be called before the first call to setRemoteCollections().
104 @param hierarchical @c true if collection remote IDs are relative to their parents' remote IDs
105 */
106 void setHierarchicalRemoteIds(bool hierarchical);
107
108 /**
109 Do a rollback operation if needed. In read only cases this is a noop.
110 */
111 void rollback();
112
113 /**
114 * Allows to specify parts of the collection that should not be changed if locally available.
115 *
116 * This is useful for resources to provide default values during the collection sync, while
117 * preserving more up-to date values if available.
118 *
119 * Use CONTENTMIMETYPES as identifier to not overwrite the content mimetypes.
120 *
121 * @since 4.14
122 */
123 void setKeepLocalChanges(const QSet<QByteArray> &parts);
124
125protected:
126 void doStart();
127
128private:
129 class Private;
130 Private *const d;
131
132 Q_PRIVATE_SLOT(d, void localCollectionsReceived(const Akonadi::Collection::List &localCols))
133 Q_PRIVATE_SLOT(d, void localCollectionFetchResult(KJob *job))
134 Q_PRIVATE_SLOT(d, void updateLocalCollectionResult(KJob *job))
135 Q_PRIVATE_SLOT(d, void createLocalCollectionResult(KJob *job))
136 Q_PRIVATE_SLOT(d, void deleteLocalCollectionsResult(KJob *job))
137 Q_PRIVATE_SLOT(d, void transactionSequenceResult(KJob *job))
138};
139
140}
141
142#endif
143