Status: | Merged |
---|---|
Approved by: | Cris Dywan |
Approved revision: | 66 |
Merged at revision: | 58 |
Proposed branch: | lp:~kalikiana/u1db-qt/trunk |
Merge into: | lp:u1db-qt |
Diff against target: |
483 lines (+193/-0) 4 files modified
database.cpp (+93/-0) document.cpp (+36/-0) index.cpp (+24/-0) query.cpp (+40/-0) |
To merge this branch: | bzr merge lp:~kalikiana/u1db-qt/trunk |
Related bugs: |
Reviewer | Review Type | Date Requested | Status |
---|---|---|---|
Ubuntu Phone Apps Jenkins Bot | continuous-integration | Approve | |
Cris Dywan | Approve | ||
Review via email: mp+156795@code.launchpad.net |
Commit message
qdoc for Database, Document, Index and Query
Description of the change
qdoc for Database, Document, Index and Query
To post a comment you must log in.
Revision history for this message
Ubuntu Phone Apps Jenkins Bot (ubuntu-phone-apps-jenkins-bot) wrote : | # |
review:
Needs Fixing
(continuous-integration)
Revision history for this message
Cris Dywan (kalikiana) : | # |
review:
Approve
Revision history for this message
Ubuntu Phone Apps Jenkins Bot (ubuntu-phone-apps-jenkins-bot) : | # |
review:
Approve
(continuous-integration)
Preview Diff
[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1 | === modified file 'database.cpp' |
2 | --- database.cpp 2013-03-20 17:10:45 +0000 |
3 | +++ database.cpp 2013-04-03 10:16:22 +0000 |
4 | @@ -31,6 +31,19 @@ |
5 | |
6 | QT_BEGIN_NAMESPACE_U1DB |
7 | |
8 | +/*! |
9 | + \class Database |
10 | + |
11 | + \brief The Database class implements the on-disk storage of an individual |
12 | + U1DB database. |
13 | + |
14 | + The functional API can be used from C++ and Javascript, and is the basis of |
15 | + the declarative API. |
16 | +*/ |
17 | + |
18 | +/*! |
19 | + A unique identifier for the state of synchronization |
20 | + */ |
21 | QString |
22 | Database::getReplicaUid() |
23 | { |
24 | @@ -40,6 +53,10 @@ |
25 | return setError(QString("Failed to get replica UID: %1\n%2").arg(query.lastError().text()).arg(query.lastQuery())) ? QString() : QString(); |
26 | } |
27 | |
28 | +/*! |
29 | + Checks if the underlying SQLite database is ready to be used |
30 | + Only to be used as a utility function by initializeIfNeeded() |
31 | + */ |
32 | bool |
33 | Database::isInitialized() |
34 | { |
35 | @@ -49,6 +66,9 @@ |
36 | return query.next(); |
37 | } |
38 | |
39 | +/*! |
40 | + Describes the error as a string if the last operation failed. |
41 | + */ |
42 | bool |
43 | Database::setError(const QString& error) |
44 | { |
45 | @@ -58,12 +78,22 @@ |
46 | return false; |
47 | } |
48 | |
49 | +/*! |
50 | + Describes the error as a string if the last operation failed. |
51 | + */ |
52 | QString |
53 | Database::lastError() |
54 | { |
55 | return m_error; |
56 | } |
57 | |
58 | +/*! |
59 | + Ensures that the underlying database works, or tries to set it up: |
60 | + |
61 | + The SQlite backend is loaded - it's an optional Qt5 module and can fail |
62 | + If @path is an existing database, it'll be opened |
63 | + For a new database, the default schema will be applied |
64 | + */ |
65 | bool |
66 | Database::initializeIfNeeded(const QString& path) |
67 | { |
68 | @@ -115,6 +145,11 @@ |
69 | initializeIfNeeded(); |
70 | } |
71 | |
72 | +/*! |
73 | + Used to implement QAbstractListModel |
74 | + Returns docId matching the given row index |
75 | + assuming all documents are ordered consistently |
76 | + */ |
77 | QString |
78 | Database::getDocIdByRow(int row) const |
79 | { |
80 | @@ -129,6 +164,13 @@ |
81 | return QString(); |
82 | } |
83 | |
84 | +/*! |
85 | + Used to implement QAbstractListModel |
86 | + Implements the variables exposed to the Delegate in a model |
87 | + QVariant contents |
88 | + QString docId |
89 | + int index (built-in) |
90 | + */ |
91 | QVariant |
92 | Database::data(const QModelIndex & index, int role) const |
93 | { |
94 | @@ -140,6 +182,11 @@ |
95 | return QVariant(); |
96 | } |
97 | |
98 | +/*! |
99 | + Used to implement QAbstractListModel |
100 | + Defines \b{contents} and \b{docId} as variables exposed to the Delegate in a model |
101 | + \b{index} is supported out of the box. |
102 | + */ |
103 | QHash<int, QByteArray> |
104 | Database::roleNames() const |
105 | { |
106 | @@ -149,6 +196,10 @@ |
107 | return roles; |
108 | } |
109 | |
110 | +/*! |
111 | + Used to implement QAbstractListModel |
112 | + The number of rows: the number of documents in the database. |
113 | + */ |
114 | int |
115 | Database::rowCount(const QModelIndex & parent) const |
116 | { |
117 | @@ -162,6 +213,11 @@ |
118 | return query.value("count").toInt(); |
119 | } |
120 | |
121 | +/*! |
122 | + Same functionality as getDoc() except it won't set lastError() and it |
123 | + doesn't implicitly try to initialize the underlying database. |
124 | + Use cases: model implementations, Document::getContents() |
125 | + */ |
126 | QVariant |
127 | Database::getDocUnchecked(const QString& docId) const |
128 | { |
129 | @@ -173,6 +229,7 @@ |
130 | query.bindValue(":docId", docId); |
131 | if (query.exec() && query.next()) |
132 | { |
133 | + // Convert JSON string to the Variant that QML expects |
134 | QJsonDocument json(QJsonDocument::fromJson(query.value("content").toByteArray())); |
135 | Q_EMIT docLoaded(docId, json.object().toVariantMap()); |
136 | return json.object().toVariantMap(); |
137 | @@ -180,6 +237,11 @@ |
138 | return QVariant(); |
139 | } |
140 | |
141 | +/*! |
142 | + Returns the contents of a document by docId in a form that QML recognizes |
143 | + as a Variant object, it's identical to Document::getContents() with the |
144 | + same docId. |
145 | + */ |
146 | QVariant |
147 | Database::getDoc(const QString& docId) |
148 | { |
149 | @@ -199,6 +261,7 @@ |
150 | { |
151 | if (query.value("conflicts").toInt() > 0) |
152 | setError(QString("Conflicts in %1").arg(docId)); |
153 | + // Convert JSON string to the Variant that QML expects |
154 | QJsonDocument json(QJsonDocument::fromJson(query.value("content").toByteArray())); |
155 | Q_EMIT docLoaded(docId, json.object().toVariantMap()); |
156 | return json.object().toVariantMap(); |
157 | @@ -214,6 +277,13 @@ |
158 | return oldRev; |
159 | } |
160 | |
161 | +/*! |
162 | + Updates the existing contents of the document identified by docId if |
163 | + there's no error. |
164 | + If no docId is given or docId is an empty string the contents will be |
165 | + stored under an autogenerated name. |
166 | + Returns the new revision of the document, or -1 on failure. |
167 | + */ |
168 | int |
169 | Database::putDoc(QVariant newDoc, const QString& newOrEmptyDocId) |
170 | { |
171 | @@ -231,6 +301,7 @@ |
172 | query.prepare("UPDATE document SET doc_rev=:docRev, content=:docJson WHERE doc_id = :docId"); |
173 | query.bindValue(":docId", docId); |
174 | query.bindValue(":docRev", newRev); |
175 | + // Parse Variant from QML as JsonDocument, fallback to string |
176 | QString json(QJsonDocument::fromVariant(newDoc).toJson()); |
177 | query.bindValue(":docJson", json.isEmpty() ? newDoc : json); |
178 | if (!query.exec()) |
179 | @@ -250,6 +321,7 @@ |
180 | query.prepare("INSERT INTO document (doc_id, doc_rev, content) VALUES (:docId, :docRev, :docJson)"); |
181 | query.bindValue(":docId", docId); |
182 | query.bindValue(":docRev", newRev); |
183 | + // Parse Variant from QML as JsonDocument, fallback to string |
184 | QJsonDocument json(QJsonDocument::fromVariant(newDoc)); |
185 | query.bindValue(":docJson", json.isEmpty() ? newDoc : json.toJson()); |
186 | if (!query.exec()) |
187 | @@ -290,6 +362,13 @@ |
188 | return setError(QString("Failed to list documents: %1\n%2").arg(query.lastError().text()).arg(query.lastQuery())) ? list : list; |
189 | } |
190 | |
191 | +/*! |
192 | + A relative filename or absolute path advises the database to store documents |
193 | + and indexes persistently on disk. Internally, an SQlite database is written. |
194 | + |
195 | + If no path is set, as is the default, all database contents are written in |
196 | + memory only. The same affect can be achieved by passing the string ":memory:". |
197 | + */ |
198 | void |
199 | Database::setPath(const QString& path) |
200 | { |
201 | @@ -306,12 +385,20 @@ |
202 | Q_EMIT pathChanged(path); |
203 | } |
204 | |
205 | +/*! |
206 | + The persistent storage location if set. By default the database is only |
207 | + storted in memory. See setPath(). |
208 | + */ |
209 | QString |
210 | Database::getPath() |
211 | { |
212 | return m_path; |
213 | } |
214 | |
215 | +/*! |
216 | + Stores a new index under the given name. An existing index won't be |
217 | + replaced implicitly, an error will be set in that case. |
218 | + */ |
219 | QString |
220 | Database::putIndex(const QString& indexName, QStringList expressions) |
221 | { |
222 | @@ -346,6 +433,9 @@ |
223 | return QString(); |
224 | } |
225 | |
226 | +/*! |
227 | + Gets the expressions saved with putIndex(). |
228 | + */ |
229 | QStringList |
230 | Database::getIndexExpressions(const QString& indexName) |
231 | { |
232 | @@ -365,6 +455,9 @@ |
233 | return expressions; |
234 | } |
235 | |
236 | +/*! |
237 | + Lists the index keys of an index created with putIndex(). |
238 | + */ |
239 | QStringList |
240 | Database::getIndexKeys(const QString& indexName) |
241 | { |
242 | |
243 | === modified file 'document.cpp' |
244 | --- document.cpp 2013-03-06 12:06:56 +0000 |
245 | +++ document.cpp 2013-04-03 10:16:22 +0000 |
246 | @@ -30,6 +30,15 @@ |
247 | |
248 | QT_BEGIN_NAMESPACE_U1DB |
249 | |
250 | +/*! |
251 | + \class Document |
252 | + |
253 | + \brief The Document class proxies a single document stored in the Database. |
254 | + |
255 | + This is the declarative API equivalent of Database::putDoc() and |
256 | + Database::getDoc(). |
257 | +*/ |
258 | + |
259 | Document::Document(QObject *parent) : |
260 | QObject(parent), m_database(0), m_create(false) |
261 | { |
262 | @@ -61,6 +70,10 @@ |
263 | } |
264 | } |
265 | |
266 | +/*! |
267 | + The database is used to lookup the contents of the document, reflecting |
268 | + changes done to it and conversely changes are saved to the database. |
269 | + */ |
270 | void |
271 | Document::setDatabase(Database* database) |
272 | { |
273 | @@ -90,6 +103,11 @@ |
274 | return m_docId; |
275 | } |
276 | |
277 | +/*! |
278 | + The docId can be that of an existing document in the database and |
279 | + will determine what getContents() returns. |
280 | + If no such documents exists, setDefaults() can be used to supply a preset. |
281 | + */ |
282 | void |
283 | Document::setDocId(const QString& docId) |
284 | { |
285 | @@ -112,6 +130,10 @@ |
286 | return m_create; |
287 | } |
288 | |
289 | +/*! |
290 | + If create is true, docId is not empty and no document with the same docId |
291 | + exists, defaults will be used to store the document. |
292 | + */ |
293 | void |
294 | Document::setCreate(bool create) |
295 | { |
296 | @@ -131,6 +153,12 @@ |
297 | return m_defaults; |
298 | } |
299 | |
300 | +/*! |
301 | + The default contents of the document, which are used only if |
302 | + create is true, docId is not empty and no document with the same |
303 | + docId exists in the database yet. |
304 | + If the defaults change, it's up to the API user to handle it. |
305 | + */ |
306 | void |
307 | Document::setDefaults(QVariant defaults) |
308 | { |
309 | @@ -144,12 +172,20 @@ |
310 | m_database->putDoc(m_defaults, m_docId); |
311 | } |
312 | |
313 | +/*! |
314 | + The contents of the document, as set via setContents() or stored in |
315 | + the database via Database::putDoc(). |
316 | + onContentsChanged() can be used to monitor changes. |
317 | + */ |
318 | QVariant |
319 | Document::getContents() |
320 | { |
321 | return m_contents; |
322 | } |
323 | |
324 | +/*! |
325 | + Updates the contents of the document. A valid docId must be set. |
326 | + */ |
327 | void |
328 | Document::setContents(QVariant contents) |
329 | { |
330 | |
331 | === modified file 'index.cpp' |
332 | --- index.cpp 2013-02-28 17:59:51 +0000 |
333 | +++ index.cpp 2013-04-03 10:16:22 +0000 |
334 | @@ -30,6 +30,17 @@ |
335 | |
336 | QT_BEGIN_NAMESPACE_U1DB |
337 | |
338 | +/*! |
339 | + \class Index |
340 | + |
341 | + \brief The Index class defines an index to be stored in the database and |
342 | + queried using Query. Changes in documents affected by the index also update |
343 | + the index in the database. |
344 | + |
345 | + This is the declarative API equivalent of Database::putIndex() and |
346 | + Database::getIndexExpressions(). |
347 | +*/ |
348 | + |
349 | Index::Index(QObject *parent) : |
350 | QObject(parent), m_database(0) |
351 | { |
352 | @@ -53,6 +64,11 @@ |
353 | Q_EMIT dataInvalidated(); |
354 | } |
355 | |
356 | +/*! |
357 | + Sets the Database to lookup documents from and store the index in. The |
358 | + dataInvalidated() signal will be emitted on all changes that could affect |
359 | + the index. |
360 | + */ |
361 | void |
362 | Index::setDatabase(Database* database) |
363 | { |
364 | @@ -80,6 +96,10 @@ |
365 | return m_name; |
366 | } |
367 | |
368 | +/*! |
369 | + Sets the name used. Both an expression and a name must be specified |
370 | + for an index to be created. |
371 | + */ |
372 | void |
373 | Index::setName(const QString& name) |
374 | { |
375 | @@ -102,6 +122,10 @@ |
376 | return m_expression; |
377 | } |
378 | |
379 | +/*! |
380 | + Sets the expression used. Both an expression and a name must be specified |
381 | + for an index to be created. |
382 | + */ |
383 | void |
384 | Index::setExpression(QStringList expression) |
385 | { |
386 | |
387 | === modified file 'query.cpp' |
388 | --- query.cpp 2013-02-28 17:59:51 +0000 |
389 | +++ query.cpp 2013-04-03 10:16:22 +0000 |
390 | @@ -31,11 +31,27 @@ |
391 | |
392 | QT_BEGIN_NAMESPACE_U1DB |
393 | |
394 | +/*! |
395 | + \class Query |
396 | + |
397 | + \brief The Query class generates a filtered list of documents based on either |
398 | + a query or a range, and using the given Index. |
399 | + |
400 | + This is the declarative API equivalent of FIXME |
401 | +*/ |
402 | + |
403 | Query::Query(QObject *parent) : |
404 | QAbstractListModel(parent), m_index(0) |
405 | { |
406 | } |
407 | |
408 | +/*! |
409 | + Used to implement QAbstractListModel |
410 | + Implements the variables exposed to the Delegate in a model |
411 | + QVariant contents |
412 | + QString docId |
413 | + int index (built-in) |
414 | + */ |
415 | QVariant |
416 | Query::data(const QModelIndex & index, int role) const |
417 | { |
418 | @@ -44,13 +60,21 @@ |
419 | { |
420 | Database* db(m_index->getDatabase()); |
421 | if (db) |
422 | + { |
423 | + qDebug() << "Query::getData" << docId; |
424 | return db->getDocUnchecked(docId); |
425 | + } |
426 | } |
427 | if (role == 1) // docId |
428 | return docId; |
429 | return QVariant(); |
430 | } |
431 | |
432 | +/*! |
433 | + Used to implement QAbstractListModel |
434 | + Defines \b{contents} and \b{docId} as variables exposed to the Delegate in a model |
435 | + \b{index} is supported out of the box. |
436 | + */ |
437 | QHash<int, QByteArray> |
438 | Query::roleNames() const |
439 | { |
440 | @@ -60,6 +84,10 @@ |
441 | return roles; |
442 | } |
443 | |
444 | +/*! |
445 | + Used to implement QAbstractListModel |
446 | + The number of rows: the number of documents given by the query. |
447 | + */ |
448 | int |
449 | Query::rowCount(const QModelIndex & parent) const |
450 | { |
451 | @@ -82,6 +110,10 @@ |
452 | // TODO |
453 | } |
454 | |
455 | +/*! |
456 | + Sets the Index to use. The index must have a valid name and index expressions, |
457 | + then either a range or query can be set. |
458 | + */ |
459 | void |
460 | Query::setIndex(Index* index) |
461 | { |
462 | @@ -103,6 +135,10 @@ |
463 | return m_query; |
464 | } |
465 | |
466 | +/*! |
467 | + Sets a range, such as ['match', false]. |
468 | + Only one of query and range is used - setting range unsets the query. |
469 | + */ |
470 | void |
471 | Query::setQuery(QVariant query) |
472 | { |
473 | @@ -123,6 +159,10 @@ |
474 | return m_range; |
475 | } |
476 | |
477 | +/*! |
478 | + Sets a range, such as [['a', 'b'], ['*']]. |
479 | + Only one of query and range is used - setting range unsets the query. |
480 | + */ |
481 | void |
482 | Query::setRange(QVariant range) |
483 | { |
FAILED: Continuous integration, rev:66 /code.launchpad .net/~kalikiana /u1db-qt/ trunk/+ merge/156795/ +edit-commit- message
No commit message was specified in the merge proposal. Click on the following link and set the commit message (if you want a jenkins rebuild you need to trigger it yourself):
https:/
http:// 91.189. 93.125: 8080/job/ u1db-qt- ci/6/ 91.189. 93.125: 8080/job/ u1db-qt- quantal- amd64-ci/ 6 91.189. 93.125: 8080/job/ u1db-qt- raring- amd64-ci/ 6
Executed test runs:
SUCCESS: http://
SUCCESS: http://
Click here to trigger a rebuild: 91.189. 93.125: 8080/job/ u1db-qt- ci/6/rebuild
http://