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 | |
30 | class QNetworkAccessManager; |
31 | class QNetworkReply; |
32 | class QNetworkRequest; |
33 | |
34 | namespace 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 | */ |
52 | class 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.