Kgapi

job.h
1/*
2 * This file is part of LibKGAPI library
3 *
4 * SPDX-FileCopyrightText: 2013 Daniel Vrátil <dvratil@redhat.com>
5 *
6 * SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
7 */
8
9#pragma once
10
11#include "kgapicore_export.h"
12#include "types.h"
13
14#include <QObject>
15
17class QNetworkReply;
18class QNetworkRequest;
19
20namespace KGAPI2
21{
22
23/**
24 * @headerfile job.h
25 * @brief Abstract base class for all jobs in LibKGAPI
26 *
27 * Usual workflow of Job subclasses is to reimplement Job::start,
28 * Job::dispatchRequest and Job::handleReply, then enqueue a QNetworkRequest using
29 * Job::enqueueRequest. Authorization headers and standard query parameters will be
30 * set by Job class. The request will automatically be scheduled in a queue and
31 * dispatched by calling Job::dispatchRequest implementation. When a reply is received,
32 * the Job will automatically perform error handling and if there is no error, the
33 * reply is passed to implementation of Job::handleReply.
34 *
35 * Job is automatically started when program enters an event loop.
36 *
37 * @author Daniel Vrátil <dvratil@redhat.com>
38 * @since 2.0
39 */
40class KGAPICORE_EXPORT Job : public QObject
41{
42 Q_OBJECT
43
44 /**
45 * @brief Maximum interval between requests.
46 *
47 * Some Google APIs have a quota on maximum amount of requests per account
48 * per second. When this quota is exceeded, the Job will automatically increase
49 * the interval between dispatching requests, wait for a while and then try
50 * again. If however the interval is increased over @p maxTimeout, the job
51 * will fail and finish immediately. By default @p maxTimeout is @p -1, which
52 * allows the interval to be increased indefinitely.
53 *
54 * @see Job::maxTimeout, Job::setMaxTimeout
55 */
56 Q_PROPERTY(int maxTimeout READ maxTimeout WRITE setMaxTimeout)
57
58 /**
59 * @brief Whether the job is running
60 *
61 * This property indicates whether the job is running or not. The value is
62 * set to @p true when the job is started (see Job::start) and back to
63 * @p false right before Job::finished is emitted.
64 *
65 * @see Job::isRunning, Job::finished
66 */
67 Q_PROPERTY(bool isRunning READ isRunning NOTIFY finished)
68public:
69 /**
70 * @brief Constructor for jobs that don't require authentication
71 *
72 * @param parent
73 */
74 explicit Job(QObject *parent = nullptr);
75
76 /**
77 * @brief Constructor for jobs that require authentication
78 *
79 * @param account Account to use to authenticate the requests send by this job
80 * @param parent
81 * @see Job::Account, Job::setAccount
82 */
83 explicit Job(const AccountPtr &account, QObject *parent = nullptr);
84
85 struct KGAPICORE_EXPORT StandardParams {
86 static const QString PrettyPrint;
87 static const QString Fields;
88 };
89
90 /**
91 * @brief Destructor
92 */
93 ~Job() override;
94
95 /**
96 * @brief Error code
97 *
98 * This method can only be called after the job has emitted Job::finished
99 * signal. Calling this method on a running job will always return
100 * KGAPI2::NoError.
101 *
102 * @return Returns code of occurred error or KGAPI2::NoError when no error
103 * has occurred.
104 */
105 KGAPI2::Error error() const;
106
107 /**
108 * @brief Error string
109 *
110 * This method can only be called after the job has emitted Job::finished
111 * signal. Calling this method on a running job will always return an empty
112 * string.
113 *
114 * @return Returns localized description of error or an empty string if no
115 * error has occurred.
116 */
117 QString errorString() const;
118
119 /**
120 * @brief Set maximum quota timeout
121 *
122 * Sets maximum interval for which the job should wait before trying to submit
123 * a request that has previously failed due to exceeded quota.
124 *
125 * Default timeout is 1 seconds, then after every failed request the timeout
126 * is increased exponentially until reaching @p maxTimeout.
127 *
128 * @param maxTimeout Maximum timeout (in seconds), or @p -1 for no timeout
129 */
130 void setMaxTimeout(int maxTimeout);
131
132 /**
133 * @brief Maximum quota limit.
134 *
135 * @return Returns maximum timeout in seconds or -1 if there is no timeout set.
136 * @see Job::setMaxTimeout
137 */
138 int maxTimeout() const;
139
140 /**
141 * @brief Whether job is running
142 *
143 * A job is considered running from the moment it's started until
144 * until Job::finished is emitted. Some methods should not be
145 * called when a job is running.
146 *
147 * @return Returns whether this job is currently running.
148 * @sa start()
149 */
150 bool isRunning() const;
151
152 /**
153 * @brief Set account to be used to authenticate requests
154 *
155 * By default, no account is set and all request are sent without any
156 * authentication.
157 *
158 * @param account Account to use
159 */
160 void setAccount(const AccountPtr &account);
161
162 /**
163 * @brief Returns account used to authenticate requests
164 *
165 * For jobs that don't require authentication, this method returns a null
166 * pointer.
167 *
168 * @return Am Account or a null pointer when no account was set.
169 */
170 AccountPtr account() const;
171
172 /**
173 * @brief Sets whether response will have indentations and line breaks.
174 *
175 * When this is false, it can reduce the response payload size,
176 * which might lead to better performance in some environments.
177 * Default is false.
178 *
179 * @param prettyPrint
180 */
181 void setPrettyPrint(bool prettyPrint);
182
183 /**
184 * @brief Returns prettyPrint query parameter.
185 *
186 * @return prettyPrint query parameter
187 */
188 bool prettyPrint() const;
189
190 /**
191 * @brief Set subset of fields to include in the response.
192 *
193 * Use for better performance.
194 *
195 * @param fields List of fields
196 */
197 void setFields(const QStringList &fields);
198
199 static QString buildSubfields(const QString &field, const QStringList &fields);
200
201 /**
202 * @brief Returns fields selector.
203 *
204 * @return List of fields
205 */
206 QStringList fields() const;
207
208 /**
209 * @brief Restarts this job
210 *
211 * When a job finishes, it's possible to run it again, without having
212 * to create a new job.
213 *
214 * The job will throw away all results retrieved in previous run and retrieve
215 * everything again.
216 *
217 * @see Job::aboutToStart
218 */
219 void restart();
220
221Q_SIGNALS:
222
223 /**
224 * @brief Emitted when @p job has finished
225 *
226 * The signal is emitted every time, no matter whether the job is successful
227 * or an error has occurred.
228 *
229 * Subclasses should never ever emit this signal directly.
230 * Use Job::emitFinished instead.
231 *
232 * @param job The job that has finished
233 * @sa emitFinished()
234 */
236
237 /**
238 * @brief Emitted when a job progress changes.
239 *
240 * Note that some jobs might not provide progress information, thus this
241 * signal will never be emitted.
242 *
243 * @param job The job that the information relates to
244 * @param processed Amount of already processed items
245 * @param total Total amount of items to process
246 */
247 void progress(KGAPI2::Job *job, int processed, int total);
248
249protected:
250 /**
251 * @brief Set job error to @p error
252 *
253 * @param error Error code to set
254 * @see Job::error
255 */
256 void setError(KGAPI2::Error error);
257
258 /**
259 * @brief Set job error description to @p errorString
260 *
261 * @param errorString Error description to set
262 * @see Job::errorString
263 */
264 void setErrorString(const QString &errorString);
265
266 /**
267 * @brief Emits Job::finished() signal
268 *
269 * Subclasses should always use this method instead of directly emitting
270 * Job::finished().
271 */
272 virtual void emitFinished();
273
274 /**
275 * @brief This method is invoked right before finished() is emitted
276 *
277 * Subclasses can reimplement this method to do a final cleanup before
278 * the Job::finished() signal is emitted.
279 *
280 * @note Note that after Job::finished() the job is not running anymore and
281 * therefore the job should not modify any data accessible by user.
282 */
283 virtual void aboutToFinish();
284
285 /**
286 * @brief Emit progress() signal
287 *
288 * Subclasses should always use this method instead of directly emitting
289 * Job::progress().
290 *
291 * @param processed Amount of already processed items
292 * @param total Total amount of items to process
293 */
294 virtual void emitProgress(int processed, int total);
295
296 /**
297 * @brief This method is invoked right before Job::start() is called.
298 *
299 * Subclasses should reset their internal state and call parent implementation.
300 */
301 virtual void aboutToStart();
302
303 /**
304 * @brief This method is invoked when job is started.
305 *
306 * Job is automatically started when application enters event loop.
307 */
308 virtual void start() = 0;
309
310 /**
311 * @brief Dispatches @p request via @p accessManager
312 *
313 * Because different types of request require different HTTP method to be
314 * used, subclasses must reimplement this method and use respective HTTP
315 * method to send the @p request via @p accessManager.
316 *
317 * @param accessManager QNetworkAccessManager used to dispatch the request
318 * @param request Request to dispatch
319 * @param data Data to sent in the body of the request
320 * @param contentType Content-Type of @p data
321 */
322 virtual void dispatchRequest(QNetworkAccessManager *accessManager, const QNetworkRequest &request, const QByteArray &data, const QString &contentType) = 0;
323
324 /**
325 * @brief Called when a reply is received.
326 *
327 * Subclasses must reimplement this method to handle reply content.
328 *
329 * @param reply A reply received from server
330 * @param rawData Raw content of the reply. Don't use QNetworkReply::readAll,
331 * because this method has already been called by Job and thus it would
332 * return nothing.
333 */
334 virtual void handleReply(const QNetworkReply *reply, const QByteArray &rawData) = 0;
335
336 /**
337 * @brief Called when an error occurs.
338 *
339 * This allows subclasses to handle error cases that might be specific for their
340 * particular API they are implementing. The re-implementation should return @c true
341 * if the error was handled and KGAPI should not perform any more error handling.
342 * If the error was not handled, the re-implementation should return @c false,
343 * which is also what the default implementation returns.
344 *
345 * @param statusCode The status code of the respons.
346 * @param rawData Raw data of the server response.
347 * @return Returns true when the error was handled by the subclass, false otherwise.
348 */
349 virtual bool handleError(int statusCode, const QByteArray &rawData);
350
351 /**
352 * @brief Enqueues @p request in dispatcher queue
353 *
354 * Subclasses should call this method to enqueue the @p request in main job
355 * queue. The request is automatically dispatched, and reply is handled.
356 * Authorization headers and standards query parameters will be applied.
357 *
358 * @param request Request to enqueue
359 * @param data Data to be send in body of the request
360 * @param contentType Content type of @p data
361 */
362 virtual void enqueueRequest(const QNetworkRequest &request, const QByteArray &data = QByteArray(), const QString &contentType = QString());
363
364private:
365 class Private;
366 Private *const d;
367 friend class Private;
368
369 friend class AuthJob;
370};
371
372} // namespace KGAPI2
A job to authenticate against Google and fetch tokens.
Definition authjob.h:34
Abstract base class for all jobs in LibKGAPI.
Definition job.h:41
void progress(KGAPI2::Job *job, int processed, int total)
Emitted when a job progress changes.
void finished(KGAPI2::Job *job)
Emitted when job has finished.
virtual void dispatchRequest(QNetworkAccessManager *accessManager, const QNetworkRequest &request, const QByteArray &data, const QString &contentType)=0
Dispatches request via accessManager.
virtual void start()=0
This method is invoked when job is started.
virtual void handleReply(const QNetworkReply *reply, const QByteArray &rawData)=0
Called when a reply is received.
A job to fetch a single map tile described by a StaticMapUrl.
Definition blog.h:16
Error
Job error codes.
Definition types.h:176
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 6 2024 12:11:00 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.