uonedb-qt team mailing list archive
-
uonedb-qt team
-
Mailing list archive
-
Message #00038
[Merge] lp:~kalikiana/u1db-qt/trunk into lp:u1db-qt
Christian Dywan has proposed merging lp:~kalikiana/u1db-qt/trunk into lp:u1db-qt.
Requested reviews:
U1DB Qt developers (uonedb-qt)
For more details, see:
https://code.launchpad.net/~kalikiana/u1db-qt/trunk/+merge/156795
qdoc for Database, Document, Index and Query
--
https://code.launchpad.net/~kalikiana/u1db-qt/trunk/+merge/156795
Your team U1DB Qt developers is requested to review the proposed merge of lp:~kalikiana/u1db-qt/trunk into lp:u1db-qt.
=== modified file 'database.cpp'
--- database.cpp 2013-03-20 17:10:45 +0000
+++ database.cpp 2013-04-03 10:16:22 +0000
@@ -31,6 +31,19 @@
QT_BEGIN_NAMESPACE_U1DB
+/*!
+ \class Database
+
+ \brief The Database class implements the on-disk storage of an individual
+ U1DB database.
+
+ The functional API can be used from C++ and Javascript, and is the basis of
+ the declarative API.
+*/
+
+/*!
+ A unique identifier for the state of synchronization
+ */
QString
Database::getReplicaUid()
{
@@ -40,6 +53,10 @@
return setError(QString("Failed to get replica UID: %1\n%2").arg(query.lastError().text()).arg(query.lastQuery())) ? QString() : QString();
}
+/*!
+ Checks if the underlying SQLite database is ready to be used
+ Only to be used as a utility function by initializeIfNeeded()
+ */
bool
Database::isInitialized()
{
@@ -49,6 +66,9 @@
return query.next();
}
+/*!
+ Describes the error as a string if the last operation failed.
+ */
bool
Database::setError(const QString& error)
{
@@ -58,12 +78,22 @@
return false;
}
+/*!
+ Describes the error as a string if the last operation failed.
+ */
QString
Database::lastError()
{
return m_error;
}
+/*!
+ Ensures that the underlying database works, or tries to set it up:
+
+ The SQlite backend is loaded - it's an optional Qt5 module and can fail
+ If @path is an existing database, it'll be opened
+ For a new database, the default schema will be applied
+ */
bool
Database::initializeIfNeeded(const QString& path)
{
@@ -115,6 +145,11 @@
initializeIfNeeded();
}
+/*!
+ Used to implement QAbstractListModel
+ Returns docId matching the given row index
+ assuming all documents are ordered consistently
+ */
QString
Database::getDocIdByRow(int row) const
{
@@ -129,6 +164,13 @@
return QString();
}
+/*!
+ Used to implement QAbstractListModel
+ Implements the variables exposed to the Delegate in a model
+ QVariant contents
+ QString docId
+ int index (built-in)
+ */
QVariant
Database::data(const QModelIndex & index, int role) const
{
@@ -140,6 +182,11 @@
return QVariant();
}
+/*!
+ Used to implement QAbstractListModel
+ Defines \b{contents} and \b{docId} as variables exposed to the Delegate in a model
+ \b{index} is supported out of the box.
+ */
QHash<int, QByteArray>
Database::roleNames() const
{
@@ -149,6 +196,10 @@
return roles;
}
+/*!
+ Used to implement QAbstractListModel
+ The number of rows: the number of documents in the database.
+ */
int
Database::rowCount(const QModelIndex & parent) const
{
@@ -162,6 +213,11 @@
return query.value("count").toInt();
}
+/*!
+ Same functionality as getDoc() except it won't set lastError() and it
+ doesn't implicitly try to initialize the underlying database.
+ Use cases: model implementations, Document::getContents()
+ */
QVariant
Database::getDocUnchecked(const QString& docId) const
{
@@ -173,6 +229,7 @@
query.bindValue(":docId", docId);
if (query.exec() && query.next())
{
+ // Convert JSON string to the Variant that QML expects
QJsonDocument json(QJsonDocument::fromJson(query.value("content").toByteArray()));
Q_EMIT docLoaded(docId, json.object().toVariantMap());
return json.object().toVariantMap();
@@ -180,6 +237,11 @@
return QVariant();
}
+/*!
+ Returns the contents of a document by docId in a form that QML recognizes
+ as a Variant object, it's identical to Document::getContents() with the
+ same docId.
+ */
QVariant
Database::getDoc(const QString& docId)
{
@@ -199,6 +261,7 @@
{
if (query.value("conflicts").toInt() > 0)
setError(QString("Conflicts in %1").arg(docId));
+ // Convert JSON string to the Variant that QML expects
QJsonDocument json(QJsonDocument::fromJson(query.value("content").toByteArray()));
Q_EMIT docLoaded(docId, json.object().toVariantMap());
return json.object().toVariantMap();
@@ -214,6 +277,13 @@
return oldRev;
}
+/*!
+ Updates the existing contents of the document identified by docId if
+ there's no error.
+ If no docId is given or docId is an empty string the contents will be
+ stored under an autogenerated name.
+ Returns the new revision of the document, or -1 on failure.
+ */
int
Database::putDoc(QVariant newDoc, const QString& newOrEmptyDocId)
{
@@ -231,6 +301,7 @@
query.prepare("UPDATE document SET doc_rev=:docRev, content=:docJson WHERE doc_id = :docId");
query.bindValue(":docId", docId);
query.bindValue(":docRev", newRev);
+ // Parse Variant from QML as JsonDocument, fallback to string
QString json(QJsonDocument::fromVariant(newDoc).toJson());
query.bindValue(":docJson", json.isEmpty() ? newDoc : json);
if (!query.exec())
@@ -250,6 +321,7 @@
query.prepare("INSERT INTO document (doc_id, doc_rev, content) VALUES (:docId, :docRev, :docJson)");
query.bindValue(":docId", docId);
query.bindValue(":docRev", newRev);
+ // Parse Variant from QML as JsonDocument, fallback to string
QJsonDocument json(QJsonDocument::fromVariant(newDoc));
query.bindValue(":docJson", json.isEmpty() ? newDoc : json.toJson());
if (!query.exec())
@@ -290,6 +362,13 @@
return setError(QString("Failed to list documents: %1\n%2").arg(query.lastError().text()).arg(query.lastQuery())) ? list : list;
}
+/*!
+ A relative filename or absolute path advises the database to store documents
+ and indexes persistently on disk. Internally, an SQlite database is written.
+
+ If no path is set, as is the default, all database contents are written in
+ memory only. The same affect can be achieved by passing the string ":memory:".
+ */
void
Database::setPath(const QString& path)
{
@@ -306,12 +385,20 @@
Q_EMIT pathChanged(path);
}
+/*!
+ The persistent storage location if set. By default the database is only
+ storted in memory. See setPath().
+ */
QString
Database::getPath()
{
return m_path;
}
+/*!
+ Stores a new index under the given name. An existing index won't be
+ replaced implicitly, an error will be set in that case.
+ */
QString
Database::putIndex(const QString& indexName, QStringList expressions)
{
@@ -346,6 +433,9 @@
return QString();
}
+/*!
+ Gets the expressions saved with putIndex().
+ */
QStringList
Database::getIndexExpressions(const QString& indexName)
{
@@ -365,6 +455,9 @@
return expressions;
}
+/*!
+ Lists the index keys of an index created with putIndex().
+ */
QStringList
Database::getIndexKeys(const QString& indexName)
{
=== modified file 'document.cpp'
--- document.cpp 2013-03-06 12:06:56 +0000
+++ document.cpp 2013-04-03 10:16:22 +0000
@@ -30,6 +30,15 @@
QT_BEGIN_NAMESPACE_U1DB
+/*!
+ \class Document
+
+ \brief The Document class proxies a single document stored in the Database.
+
+ This is the declarative API equivalent of Database::putDoc() and
+ Database::getDoc().
+*/
+
Document::Document(QObject *parent) :
QObject(parent), m_database(0), m_create(false)
{
@@ -61,6 +70,10 @@
}
}
+/*!
+ The database is used to lookup the contents of the document, reflecting
+ changes done to it and conversely changes are saved to the database.
+ */
void
Document::setDatabase(Database* database)
{
@@ -90,6 +103,11 @@
return m_docId;
}
+/*!
+ The docId can be that of an existing document in the database and
+ will determine what getContents() returns.
+ If no such documents exists, setDefaults() can be used to supply a preset.
+ */
void
Document::setDocId(const QString& docId)
{
@@ -112,6 +130,10 @@
return m_create;
}
+/*!
+ If create is true, docId is not empty and no document with the same docId
+ exists, defaults will be used to store the document.
+ */
void
Document::setCreate(bool create)
{
@@ -131,6 +153,12 @@
return m_defaults;
}
+/*!
+ The default contents of the document, which are used only if
+ create is true, docId is not empty and no document with the same
+ docId exists in the database yet.
+ If the defaults change, it's up to the API user to handle it.
+ */
void
Document::setDefaults(QVariant defaults)
{
@@ -144,12 +172,20 @@
m_database->putDoc(m_defaults, m_docId);
}
+/*!
+ The contents of the document, as set via setContents() or stored in
+ the database via Database::putDoc().
+ onContentsChanged() can be used to monitor changes.
+ */
QVariant
Document::getContents()
{
return m_contents;
}
+/*!
+ Updates the contents of the document. A valid docId must be set.
+ */
void
Document::setContents(QVariant contents)
{
=== modified file 'index.cpp'
--- index.cpp 2013-02-28 17:59:51 +0000
+++ index.cpp 2013-04-03 10:16:22 +0000
@@ -30,6 +30,17 @@
QT_BEGIN_NAMESPACE_U1DB
+/*!
+ \class Index
+
+ \brief The Index class defines an index to be stored in the database and
+ queried using Query. Changes in documents affected by the index also update
+ the index in the database.
+
+ This is the declarative API equivalent of Database::putIndex() and
+ Database::getIndexExpressions().
+*/
+
Index::Index(QObject *parent) :
QObject(parent), m_database(0)
{
@@ -53,6 +64,11 @@
Q_EMIT dataInvalidated();
}
+/*!
+ Sets the Database to lookup documents from and store the index in. The
+ dataInvalidated() signal will be emitted on all changes that could affect
+ the index.
+ */
void
Index::setDatabase(Database* database)
{
@@ -80,6 +96,10 @@
return m_name;
}
+/*!
+ Sets the name used. Both an expression and a name must be specified
+ for an index to be created.
+ */
void
Index::setName(const QString& name)
{
@@ -102,6 +122,10 @@
return m_expression;
}
+/*!
+ Sets the expression used. Both an expression and a name must be specified
+ for an index to be created.
+ */
void
Index::setExpression(QStringList expression)
{
=== modified file 'query.cpp'
--- query.cpp 2013-02-28 17:59:51 +0000
+++ query.cpp 2013-04-03 10:16:22 +0000
@@ -31,11 +31,27 @@
QT_BEGIN_NAMESPACE_U1DB
+/*!
+ \class Query
+
+ \brief The Query class generates a filtered list of documents based on either
+ a query or a range, and using the given Index.
+
+ This is the declarative API equivalent of FIXME
+*/
+
Query::Query(QObject *parent) :
QAbstractListModel(parent), m_index(0)
{
}
+/*!
+ Used to implement QAbstractListModel
+ Implements the variables exposed to the Delegate in a model
+ QVariant contents
+ QString docId
+ int index (built-in)
+ */
QVariant
Query::data(const QModelIndex & index, int role) const
{
@@ -44,13 +60,21 @@
{
Database* db(m_index->getDatabase());
if (db)
+ {
+ qDebug() << "Query::getData" << docId;
return db->getDocUnchecked(docId);
+ }
}
if (role == 1) // docId
return docId;
return QVariant();
}
+/*!
+ Used to implement QAbstractListModel
+ Defines \b{contents} and \b{docId} as variables exposed to the Delegate in a model
+ \b{index} is supported out of the box.
+ */
QHash<int, QByteArray>
Query::roleNames() const
{
@@ -60,6 +84,10 @@
return roles;
}
+/*!
+ Used to implement QAbstractListModel
+ The number of rows: the number of documents given by the query.
+ */
int
Query::rowCount(const QModelIndex & parent) const
{
@@ -82,6 +110,10 @@
// TODO
}
+/*!
+ Sets the Index to use. The index must have a valid name and index expressions,
+ then either a range or query can be set.
+ */
void
Query::setIndex(Index* index)
{
@@ -103,6 +135,10 @@
return m_query;
}
+/*!
+ Sets a range, such as ['match', false].
+ Only one of query and range is used - setting range unsets the query.
+ */
void
Query::setQuery(QVariant query)
{
@@ -123,6 +159,10 @@
return m_range;
}
+/*!
+ Sets a range, such as [['a', 'b'], ['*']].
+ Only one of query and range is used - setting range unsets the query.
+ */
void
Query::setRange(QVariant range)
{
Follow ups
