Warning: That file was not part of the compilation database. It may have many parsing errors.

1/*
2 * This file is part of LibKGAPI library
3 *
4 * Copyright (C) 2013 Daniel Vrátil <dvratil@redhat.com>
5 *
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2 of the License, or
9 * (at your option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License along
17 * with this program; if not, write to the Free Software Foundation, Inc.,
18 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
19 *
20 */
21
22#ifndef LIBKGAPI2_JOB_H
23#define LIBKGAPI2_JOB_H
24
25#include <QtCore/QObject>
26
27#include <libkgapi2/types.h>
28#include <libkgapi2/libkgapi2_export.h>
29
30class QNetworkAccessManager;
31class QNetworkReply;
32class QNetworkRequest;
33
34namespace KGAPI2 {
35
36/**
37 * @headerfile Job
38 * @brief Abstract base class for all jobs in LibKGAPI
39 *
40 * Usual workflow of Job subclasses is to reimplement Job::start,
41 * Job::dispatchRequest and Job::handleReply, then enqueue a QNetworkRequest using
42 * Job::enqueueRequest. The request will automatically be scheduled in a queue
43 * and dispatched by calling Job::dispatchRequest implementation. When a reply
44 * is received, the Job will automatically perform error handling and if there
45 * is no error, the reply is passed to implementation of Job::handleReply.
46 *
47 * Job is automatically when program enters an event loop.
48 *
49 * @author Daniel Vrátil <dvratil@redhat.com>
50 * @since 2.0
51 */
52class LIBKGAPI2_EXPORT Job : public QObject
53{
54 Q_OBJECT
55
56 /**
57 * @brief Maximum interval between requests.
58 *
59 * Some Google APIs have a quota on maximum amount of requests per account
60 * per second. When this quota is exceeded, the Job will automatically increase
61 * the interval between dispatching requests, wait for a while and then try
62 * again. If however the interval is incresed over @p maxTimeout, the job
63 * will fail and finish immediatelly. By default @p maxTimeout is @p -1, which
64 * allows the interval to be increased indefinitely.
65 *
66 * @see Job::maxTimeout, Job::setMaxTimeout
67 */
68 Q_PROPERTY(int maxTimeout READ maxTimeout WRITE setMaxTimeout)
69
70 /**
71 * @brief Whether the job is running
72 *
73 * This property indicates whether the job is running or not. The value is
74 * set to @p true when the job is started (see Job::start) and back to
75 * @p false right before Job::finished is emitted.
76 *
77 * @see Job::isRunning, Job::finished
78 */
79 Q_PROPERTY(bool isRunning READ isRunning NOTIFY finished)
80 public:
81
82 /**
83 * @brief Constructor for jobs that don't require authentication
84 *
85 * @param parent
86 */
87 explicit Job(QObject* parent = 0);
88
89 /**
90 * @brief Constructor for jobs that require authentication
91 *
92 * @param account Account to use to authenticate the requests send by this job
93 * @param parent
94 * @see Job::Account, Job::setAccount
95 */
96 explicit Job(const AccountPtr &account, QObject* parent = 0);
97
98 /**
99 * @brief Destructor
100 */
101 virtual ~Job();
102
103 /**
104 * @brief Error code
105 *
106 * This method can only be called after the job has emitted Job::finished
107 * signal. Calling this method on a running job will always return
108 * KGAPI2::NoError.
109 *
110 * @return Returns code of ocurred error or KGAPI2::NoError when no error
111 * has ocurred.
112 */
113 KGAPI2::Error error() const;
114
115 /**
116 * @brief Error string
117 *
118 * This method can only be called after the job has emitted Job::finished
119 * signal. Calling this method on a running job will alaways return an empty
120 * string.
121 *
122 * @return Returns localized description of error or an empty string if no
123 * error has ocurred.
124 */
125 QString errorString() const;
126
127 /**
128 * @brief Set maximum quota timeout
129 *
130 * Sets maximum interval for which the job should wait before trying to submit
131 * a request that has previously failed due to exceeded quota.
132 *
133 * Default timeout is 1 seconds, then after every failed request the timeout
134 * is increesed exponentially until reaching @p maxTimeout.
135 *
136 * @param maxTimeout Maximum timeout (in seconds), or @p -1 for no timeout
137 */
138 void setMaxTimeout(int maxTimeout);
139
140 /**
141 * @brief Maximum quota limit.
142 *
143 * @return Returns maximum timeout in seconds or -1 if there is no timeout set.
144 * @see Job::setMaxTimeout
145 */
146 int maxTimeout() const;
147
148 /**
149 * @brief Whether job is running
150 *
151 * A job is considered running from the moment it's started until
152 * until Job::finished is emitted. Some methods should not be
153 * called when a job is running.
154 *
155 * @return Returns whether this job is currently running.
156 * @sa start()
157 */
158 bool isRunning() const;
159
160 /**
161 * @brief Set account to be used to authenticate requests
162 *
163 * By default, no account is set and all request are sent without any
164 * authentication.
165 *
166 * @param account Account to use
167 */
168 void setAccount(const AccountPtr &account);
169
170 /**
171 * @brief Returns account used to authenticate requests
172 *
173 * For jobs that don't require authentication, this method returns a null
174 * pointer.
175 *
176 * @return Am Account or a null pointer when no account was set.
177 */
178 AccountPtr account() const;
179
180 /**
181 * @brief Restarts this job
182 *
183 * When a job finishes, it's possible to run it again, without having
184 * to create a new job.
185 *
186 * The job will throw away all results retrieved in previous run and retrieve
187 * everything again.
188 *
189 * @see Job::aboutToStart
190 */
191 void restart();
192
193 Q_SIGNALS:
194
195 /**
196 * @brief Emitted when @p job has finished
197 *
198 * The signal is emitted every time, no matter whether the job is successful
199 * or an error has ocurred.
200 *
201 * Sublcasses should never ever emit this signal directly.
202 * Use Job::emitFinished instead.
203 *
204 * @param job The job that has finished
205 * @sa emitFinished()
206 */
207 void finished(KGAPI2::Job *job);
208
209 /**
210 * @brief Emitted when a job progress changes.
211 *
212 * Note that some jobs might not provide progress information, thus this
213 * signal will never be emitted.
214 *
215 * @param job The job that the information relates to
216 * @param processed Amount of already processed items
217 * @param total Total amount of items to process
218 */
219 void progress(KGAPI2::Job *job, int processed, int total);
220
221 protected:
222
223 /**
224 * @brief Set job error to @p error
225 *
226 * @param error Error code to set
227 * @see Job::error
228 */
229 void setError(KGAPI2::Error error);
230
231 /**
232 * @brief Set job error description to @p errorString
233 *
234 * @param errorString Error description to set
235 * @see Job::errorString
236 */
237 void setErrorString(const QString &errorString);
238
239 /**
240 * @brief Emits Job::finished() signal
241 *
242 * Subclasses should always use this method instead of directly emitting
243 * Job::finished().
244 */
245 virtual void emitFinished();
246
247 /**
248 * @brief This method is invoked right before finished() is emitted
249 *
250 * Sublcasses can reimplement this method to do final clean up before
251 * the Job::finished() signal is emitted.
252 *
253 * @note Note that after Job::finished() the job is not running anymore and
254 * therefore the job should not modify any data accessible by user.
255 */
256 virtual void aboutToFinish();
257
258 /**
259 * @brief Emit progress() signal
260 *
261 * Subclasses should always use this method instead of directly emitting
262 * Job::progress().
263 *
264 * @param processed Amount of already processed items
265 * @param total Total amount of itms to process
266 */
267 virtual void emitProgress(int processed, int total);
268
269 /**
270 * @brief This method is invoked right before Job::start() is called.
271 *
272 * Sublcasses should reset their internal state and call parent implementation.
273 */
274 virtual void aboutToStart();
275
276 /**
277 * @brief This method is invoked when job is started.
278 *
279 * Job is automatically started when application enters event loop.
280 */
281 virtual void start() = 0;
282
283 /**
284 * @brief Dispatches @p request via @p accessManager
285 *
286 * Because different types of request require different HTTP method to be
287 * used, subclasses must reimplement this method and use respective HTTP
288 * method to send the @p request via @p accessManager.
289 *
290 * @param accessManager QNetworkAccessManager used to dispatch the request
291 * @param request Request to dispatch
292 * @param data Data to send in body of the request
293 * @param contentType Content-Type of @p data
294 */
295 virtual void dispatchRequest(QNetworkAccessManager *accessManager, const QNetworkRequest &request,
296 const QByteArray &data, const QString &contentType) = 0;
297
298 /**
299 * @brief Called when a reply is received.
300 *
301 * Sublcasses must reimplement this method to handle reply content.
302 *
303 * @param reply A reply received from server
304 * @param rawData Raw content of the reply. Don't use QNetworkReply::readAll,
305 * because this method has already been called by Job and thus it would
306 * return nothing.
307 */
308 virtual void handleReply(const QNetworkReply *reply, const QByteArray &rawData) = 0;
309
310 /**
311 * @brief Enqueues @p request in dispatcher queue
312 *
313 * Subclasses should call this method to enqueue the @p request in main job
314 * queue. The request is automatically dispatched, and reply is handled.
315 *
316 * @param request Request to enqueue
317 * @param data Data to be send in body of the request
318 * @param contentType Content type of @p data
319 */
320 virtual void enqueueRequest(const QNetworkRequest &request, const QByteArray &data = QByteArray(),
321 const QString &contentType = QString());
322
323 private:
324 class Private;
325 Private * const d;
326 friend class Private;
327
328 friend class AuthJob;
329
330 Q_PRIVATE_SLOT(d, void _k_doStart())
331 Q_PRIVATE_SLOT(d, void _k_doEmitFinished())
332 Q_PRIVATE_SLOT(d, void _k_replyReceived(QNetworkReply *reply))
333 Q_PRIVATE_SLOT(d, void _k_dispatchTimeout())
334
335};
336
337} // namespace KGAPI2
338
339#endif // LIBKGAPI2_JOB_H
340

Warning: That file was not part of the compilation database. It may have many parsing errors.