Merge lp:~kevin-wright-1/u1db-qt/synchronizer-07-juni-2013 into lp:u1db-qt

[Cris Dywan]

[Cris Dywan (kalikiana)]

syncLocalToLocal should use U1db::Database to re-use the initialization, which would also give it the existing sanity checks

the logic of onSyncChanged is probably best moved into a separate callback. Changing resolve_to_source and targets would trigger it as well. Thus it becomes possible to delay/ thread the real sync and avoid any delay at startup.

Even with keeping in mind it's incomplete //uncommented code and conflicts make reviewing a little hard.

I love the description of the sync via HTTP/ JSON, this would be nice to get into one qdoc-ified comment and make it accessible as documentation.

=== modified file 'CMakeLists.txt'
--- CMakeLists.txt	2013-05-01 22:49:50 +0000
+++ CMakeLists.txt	2013-06-07 13:40:37 +0000
@@ -39,4 +39,3 @@
 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/${QT_U1DB_PKGCONFIG_FILE}
     DESTINATION ${CMAKE_INSTALL_PREFIX}/lib/pkgconfig
     )
-

=== added directory 'examples/u1db-qt-example-6'
=== added file 'examples/u1db-qt-example-6/u1db-qt-example-6.qdoc'
--- examples/u1db-qt-example-6/u1db-qt-example-6.qdoc	1970-01-01 00:00:00 +0000
+++ examples/u1db-qt-example-6/u1db-qt-example-6.qdoc	2013-06-07 13:40:37 +0000
@@ -0,0 +1,387 @@
+/*!
+
+\page  u1db-qt-tutorial-6.html
+
+\title U1Db-Qt Synchronizing Tutorial
+
+This tutorial is designed to demonstrate a variety of essential U1Db-Qt functionality and usage, including:
+
+\list 1
+    \li Synchronizing two databases
+    \li Utilizing the U1db-Qt Index element
+    \li Various approaches to define U1db-Qt Document elements when using the Index element
+    \li Partnering the U1db-Qt Index element and a QML ListView element 
+\endlist
+
+\section1 Storing Data
+
+\section2 The Database Element
+
+\section3 Creating a Database
+
+A Database is very simple to create. It only needs an id and a path where the file will be created. A Database is a model, which can be used by elements, such as the ListView further in this example.
+
+\code
+U1db.Database {
+    id: aDatabase
+    path: "aDatabase4"
+}
+\endcode
+
+\section1 The Document Element
+
+\section2 Declaring Documents (at Runtime)
+
+A Document can be instantiated at runtime, or generated dynamically. The examples below demonstrate the former.
+
+A very basic Document could include its unique 'id' and 'docId' properties. While it is not mandatory to define these properties, in some cases they can be convenient references. More advanced applications would likely find these very useful, and in some cases may be an absolute necessity to achieve the objectives of the program.
+
+This example of a very simple Document will not initially do anything, until more properties are added and defined:
+
+\code
+U1db.Document {
+    id: aDocument1
+    docId: 'helloworld1'
+}
+\endcode
+
+A basic but still practical Document definition contains several essential properties. In addition to 'id' and 'docId' (discussed above), the 'database', 'create', and 'defaults' properties are also very important, and are introduced below.
+
+The 'database' property ensures that the Document is attached to an already defined (or possibly soon to be defined one) identified by its id (in this case 'aDatabase'). For example:
+
+\code
+U1db.Document {
+    id: aDocument1
+    database: aDatabase
+    docId: 'helloworld1'
+}
+\endcode
+
+Should the Database not already contain a Document with the same docId ('hellowworld1' in this example) when a 'create' property is present and set to true it will be generated. For example:
+
+\code
+U1db.Document {
+    id: aDocument1
+    database: aDatabase
+    docId: 'helloworld1'
+    create: true
+}
+\endcode
+
+However, the Document still requires some data to be useful, which is what the 'defaults' property provides. The value of 'defaults' is a map of data that will be stored in the database (again when the create property is et to true). It contain key:value pairs, where the value can be a string, number, or nested object (e.g. additional fields, lists). For example:
+
+\code
+U1db.Document {
+    id: aDocument1
+    database: aDatabase
+    docId: 'helloworld1'
+    create: true
+    defaults:{"hello": { "world": { "message":"Hello World", "id": 1 } } }
+}
+\endcode
+
+As mentioned above, lists can also be nested in Document data. Lists provide a convenient method for producing multiple instances of the same key (AKA 'field' or 'sub-field'). The example code below shows valid use of the 'message' and 'id' sub-fields multiple times within the same object.
+
+\code
+U1db.Document {
+    id: aDocument2
+    database: aDatabase
+    docId: 'helloworld2'
+    create: true
+    defaults:{"hello": { "world": [
+                            { "message":"Hello World", "id": 2 },
+                            { "message":"Hello World", "id": 2.5 }
+                        ] } }
+}
+\endcode
+
+When the default Javascript Object Notation itself is formatted with appropriate line breaks and indentation, it becomes easier to visualize an embedded list, containing sub-fields 'message' and 'id' (and their respective values):
+
+\code
+{"hello":
+    { "world":
+        [
+            { "message":"Hello World", "id": 2 },
+            { "message":"Hello World", "id": 2.5 }
+        ]
+    }
+}
+\endcode
+
+In dot notation these sub-fields are represented by 'hello.world.message' and 'hello.world.id' respectively. Later in this tutorial these will be utilized within the 'expression' property of U1Db-Qt's Index element, in close collaboration with a QML ListView's delegates.
+
+
+Normally when a docId already exists in a database, and when the set flag is set to true, the value in 'defaults' will be ignored (and the existing data in the database will remain untouched). Sometimes a developer needs to easily overwrite the data in an existing document. The 'contents' property can be used for just that purpose. When 'contents' is defined, its value will replace existing data in the database, for the document identified by the docId. In addition, 'contents' can be used to add new documents, in the same way as the 'create: true' + 'defaults' combination does; in other words, if the document defined by 'docId' does not exist it will be created.
+
+\code
+U1db.Document {
+    id: aDocument3
+    database: aDatabase
+    docId: 'helloworld3'
+    contents:{"hello": { "world": [
+                            { "message":"Hello World", "id": 3 },
+                            { "message":"Hello World", "id": 3.33 },
+                            { "message":"Hello World", "id": 3.66 }
+                        ] } }
+}
+\endcode
+
+If 'defaults' exists, 'create' is set to 'true' (or 'false' for that matter) and 'contents' is also defined, it is the latter that takes precidence. In other words, 'create' and 'defaults' will be ignored. The following example demonstrates this scenario:
+
+\code
+U1db.Document {
+    id: aDocument3
+    database: aDatabase
+    docId: 'helloworld3'
+    create: true
+    default:{"hello": { "world": [{ "message":"Hello World", "id": 3 }] } }
+    contents:{"hello": { "world": [
+                                    { "message":"Hello World", "id": 3 },
+                                    { "message":"Hello World", "id": 3.33 },
+                                    { "message":"Hello World", "id": 3.66 }
+                        ] } }
+}
+\endcode
+
+This snippet simply represents the absence of the 'create' property, which is synonymous with 'create: false'. The Document can still be recognized within the application, but until applicable properties (such as those outlined above) are added and/or modified then nothing will be added or modified in the database, and this instance may have very little practical value.
+
+\code
+U1db.Document {
+    id: aDocument4
+    database: aDatabase
+    docId: 'helloworld4'
+    defaults:{"hello": { "world": { "message":"Hello World", "id": 4 } } }
+}
+\endcode
+
+\section3 Samples of Stored Documents
+
+The data stored in the database after defining the above Document elements (and then running the application, will consist of the following:
+
+\table
+\header
+    \li docId
+    \li content
+\row
+
+    \li 'helloworld1'
+    \li
+\code
+{
+    "hello": {
+        "world": {
+            "id": 1,
+            "message": "Hello World"
+        }
+    }
+}
+
+\endcode
+
+
+\row
+
+    \li 'helloworld2'
+    \li
+\code
+{
+    "hello": {
+        "world": [
+            {
+                "id": 2,
+                "message": "Hello World"
+            },
+            {
+                "id": 2.5,
+                "message": "Hello World"
+            }
+        ]
+    }
+}
+\endcode
+
+\row
+
+    \li 'helloworld3'
+    \li
+\code
+{
+    "hello": {
+        "world": [
+            {
+                "id": 3,
+                "message": "Hello World"
+            },
+            {
+                "id": 3.33,
+                "message": "Hello World"
+            },
+            {
+                "id": 3.66,
+                "message": "Hello World"
+            }
+        ]
+    }
+}
+\endcode
+
+
+\endtable
+
+\section1 Retrieving Data
+
+To retrieve the Documents that were declared earlier requires two additional elements: Index and Query.
+
+\section2 The Index Element
+
+\section3 Creating and Index Element
+
+The Index element requires both a unique 'id' and a pointer to a 'database' in order to begin becoming useful, as demonstrated here:
+
+\code
+U1db.Index{
+    database: aDatabase
+    id: by_helloworld
+}
+\endcode
+
+In the future, the Index element will support on disk storage of appropriate results / data. At the present time only in memory indexing is done, but once the storing capability is implemented, defining and identifying it is as simple as using the 'name' property (which will be stored in the database along with the relvent data that goes with it). The snippet below shows the use of the 'name' property:
+
+\code
+U1db.Index{
+    database: aDatabase
+    id: by_helloworld
+    //name: "by-helloworld"
+}
+\endcode
+
+The Index element describes, using dot notation, the fields and sub-fields where the developer expects to find information. That information is defined in a list, and added as the value for the 'expression' property. The list can contain one or more entries, as exemplified here (the property is commented out due to its current status):
+
+\code
+U1db.Index{
+    database: aDatabase
+    id: by_helloworld
+    //name: "by-helloworld"
+    expression: ["hello.world.id","hello.world.message"]
+}
+\endcode
+
+\section2 The QueryElement
+
+\section3 Creating a Query Element
+
+The Query element has two responsibilities: a bridge from Database+Index to other parts of the application, as well as further filtering of data in the database (in addition to what Index provides).
+
+In order to fulfil its duties as a bridge to an Index (and Database), the 'index' property must point to an Index element, identified by its 'id'. For example:
+
+\code
+U1db.Query{
+    id: aQuery
+    index: by_helloworld
+}
+\endcode
+
+While Index helps to filter data based on 'where' it is located (e.g. field.sub-field), Query helps determine the additional set of criteria for 'what' is being searched for. The intent of the 'query' property is to provide the mechanism for defnining the search criteria, but at the time of writing that functionality is not yet available. However, once the implementation is in place, using it is only requires defining the property's value (e.g. "Hello World"). Wild card searches using '*' are supported, which is the default query (i.e. if 'query' is not set it is assumed to be '*'). For example (the property is commented out due to its current status):
+
+\code
+U1db.Query{
+    id: aQuery
+    index: by_helloworld
+    //query: "*"
+}
+\endcode
+
+When the 'query' property becomes available, only wildcard search definitions for "starts with" will be suppoprted. Thus the following would be supported:
+
+\code
+U1db.Query{
+    id: aQuery
+    index: by_helloworld
+    //query: "Hello*"
+}
+\endcode
+
+
+But this would not:
+
+\code
+U1db.Query{
+    id: aQuery
+    index: by_helloworld
+    //query: "*World"
+}
+\endcode
+
+Note: again, the 'query' property is commented out in the above two snippets due to its current status
+
+\section1 Using Data
+
+\section2 Data and the Application UI
+
+\section3 Using Data With Models and Views
+
+This simple snippet represents how to attach a ListModel to a ListView. In this instance the model 'aQuery' is representative of the Query + Index combination defined earlier:
+
+\code
+ListView {
+    width: units.gu(45)
+    height: units.gu(80)
+    model: aQuery
+}
+\endcode
+
+\section4 Data and Delegates
+
+How a model and ListView + delegates work together is a common QML concept, and not specific to U1Db-Qt. However, the asynchronous nature of this relationship is important to understand. When using QML ListView, delegates will be created based on particular properties such as the size of the application window, ListView, and delegate itself (amongst other factors). Each delegate can then represent a Document retrieved from the Database based on the record's index. This example demonstrates some of the property definitions that contribute to determining the number of delegates a ListView will contain:
+
+\code
+ListView {
+    width: units.gu(45)
+    height: units.gu(80)
+    model: aQuery
+
+    delegate: Text {
+        x: 66; y: 77
+    }
+
+}
+\endcode
+
+
+When the number of Documents is less than or equal to the number of delegates then there is a one to one mapping of index to delegate (e.g. the first delegate will represent the Document with an index = 0; the second, index = 1; and so on).
+
+When there are more Documents than delegates the ListView will request a new index depending on the situation (e.g. a user scrolls up or down). For example, if a ListView has 10 delegates, but 32 Documents to handle, when a user initially scrolls the first delegate will change from representing the Document with index = 0 to the Document that might have index = 8; the second, from index = 1 to index = 9; ...; the 10th delegate from index = 9 to index = 17. A second scrolling gesture the first index may change to 15, and the final index 24. And so on. Scrolling in the opposite direction will have a similar effect, but the Document index numbers for each delegate will obviously start to decline (towards their original values).
+
+The following snippet, which modifies the above delegate definition, could demonstrate this effect if there were enough Documents to do so (i.e. some number greater than the number of delegates):
+
+\code
+ListView {
+    width: units.gu(45)
+    height: units.gu(80)
+    model: aQuery
+
+    delegate: Text {
+        x: 66; y: 77
+        text: index
+    }
+
+}
+\endcode
+
+The object called 'contents' contains one or more properties. This example demonstrates the retrieval of data based on the U1db.Index defined earlier (id: by-helloworld). In this instance the Index contained two expressions simultaniously, "hello.world.id" and "hello.world.message"
+
+\code
+ListView {
+    width: units.gu(45)
+    height: units.gu(80)
+    model: aQuery
+
+    delegate: Text {
+        x: 66; y: 77
+        text: "(" + index + ") '" + contents.message + " " + contents.id + "'"
+    }
+
+}
+\endcode
+
+*/

=== added file 'examples/u1db-qt-example-6/u1db-qt-example-6.qml'
--- examples/u1db-qt-example-6/u1db-qt-example-6.qml	1970-01-01 00:00:00 +0000
+++ examples/u1db-qt-example-6/u1db-qt-example-6.qml	2013-06-07 13:40:37 +0000
@@ -0,0 +1,174 @@
+/*
+ * Copyright (C) 2013 Canonical, Ltd.
+ *
+ * Authors:
+ *  Kevin Wright <[e-mail]>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation; version 3.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+import QtQuick 2.0
+import U1db 1.0 as U1db
+import Ubuntu.Components 0.1
+
+
+Item {
+
+        width: units.gu(45)
+        height: units.gu(80)
+
+        U1db.Database {
+            id: aDatabase
+            path: "aDatabase6"
+        }
+
+        U1db.Database {
+            id: aTargetDatabase
+            path: "aTargetDatabase6"
+        }
+
+       U1db.Document {
+            id: aDocument1
+            database: aDatabase
+            docId: 'helloworld'
+            create: true
+            defaults:{"hello": { "world": { "message":"Hello World", "id": 1 } } }
+
+        }
+
+       U1db.Document {
+            id: aDocument2
+            database: aTargetDatabase
+            docId: 'helloworld'
+            create: true
+            defaults:{"hello": { "world": [
+                        { "message":"Hello World", "id": 2 },
+                        { "message":"Hello World", "id": 2.5 }
+                    ] } }
+        }
+
+       U1db.Index{
+           database: aDatabase
+           id: by_helloworld
+           expression: ["hello.world.id","hello.world.message"]
+       }
+
+       U1db.Query{
+           id: aQuery
+           index: by_helloworld
+           query: [{"id":"*"},{"message":"Hel*"}]
+       }
+
+       U1db.Index{
+           database: aTargetDatabase
+           id: by_target_helloworld
+           expression: ["hello.world.id","hello.world.message"]
+       }
+
+       U1db.Query{
+           id: aTargetQuery
+           index: by_target_helloworld
+           query: [{"id":"*"},{"message":"Hel*"}]
+       }
+
+       U1db.Synchronizer{
+           id: aSynchronizer
+           source: aDatabase
+           //local_targets: [aTargetDatabase]
+           //remote_targets: ["http://somewhere"]
+           targets: [{remote:true},
+               {remote:false,location:"database7",resolve_to_source:true},
+               {remote:"OK"}]
+           resolve_to_source: true
+           synchronize: false
+       }
+
+    MainView {
+
+        id: u1dbView
+        width: units.gu(45)
+        height: units.gu(80)
+        anchors.top: parent.top;
+
+        Tabs {
+            id: tabs
+            anchors.fill: parent
+
+            Tab {
+                objectName: "Tab1"
+
+                title: i18n.tr("Hello U1Db!")
+
+                page: Page {
+                    id: helloPage
+
+                    Rectangle {
+                         width: units.gu(45)
+                         height: units.gu(70)
+                         anchors.top: parent.top;
+
+                        ListView {
+                            width: units.gu(45)
+                            height: units.gu(35)
+                            anchors.top: parent.top;
+                            model: aQuery
+
+                            delegate: Text {
+                                x: 66; y: 77
+                                text: {
+                                    text: "(" + index + ") '" + contents.message + " " + contents.id + "'"
+                                }
+                            }
+                        }
+
+                        ListView {
+                            width: units.gu(45)
+                            height: units.gu(35)
+                            anchors.bottom: parent.bottom;
+                            model: aTargetQuery
+
+                            delegate: Text {
+                                x: 66; y: 77
+                                text: {
+                                    text: "(" + index + ") '" + contents.message + " " + contents.id + "'"
+                                }
+                            }
+                        }
+                    }
+
+                   Rectangle {
+                       width: units.gu(45)
+                       height: units.gu(5)
+                       anchors.bottom: parent.bottom;
+                       color: "white"
+
+                       Button{
+                           text: "Sync"
+                           onClicked: aSynchronizer.synchronize = true
+                           anchors.left: parent.left
+                           anchors.right: parent.right
+
+                       }
+
+                   }
+                }
+
+            }
+
+        }
+
+    }
+
+}
+
+

=== modified file 'modules/U1db/plugin.cpp'
--- modules/U1db/plugin.cpp	2013-02-15 11:43:45 +0000
+++ modules/U1db/plugin.cpp	2013-06-07 13:40:37 +0000
@@ -21,6 +21,7 @@
 #include "document.h"
 #include "index.h"
 #include "query.h"
+#include "synchronizer.h"
 #include "plugin.h"
 #include <qqml.h>
 
@@ -32,5 +33,6 @@
     qmlRegisterType<Document>(uri, 1, 0, "Document");
     qmlRegisterType<Index>(uri, 1, 0, "Index");
     qmlRegisterType<Query>(uri, 1, 0, "Query");
+    qmlRegisterType<Synchronizer>(uri, 1, 0, "Synchronizer");
 }
 

=== modified file 'src/CMakeLists.txt'
--- src/CMakeLists.txt	2013-04-23 10:39:54 +0000
+++ src/CMakeLists.txt	2013-06-07 13:40:37 +0000
@@ -6,6 +6,7 @@
     document.cpp
     index.cpp
     query.cpp
+    synchronizer.cpp
     )
 
 # Generated files
@@ -14,6 +15,7 @@
     moc_document.cpp
     moc_index.cpp
     moc_query.cpp
+    moc_synchronizer.cpp
     )
 set_directory_properties(PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES "${U1DB_QT_GENERATED}")
 
@@ -50,7 +52,7 @@
     LIBRARY DESTINATION lib${LIB_SUFFIX}
     )
 
-install(FILES global.h database.h document.h index.h query.h
+install(FILES global.h database.h document.h index.h query.h synchronizer.h
     DESTINATION ${INCLUDE_INSTALL_DIR}
     )
 

=== modified file 'src/database.cpp'
--- src/database.cpp	2013-04-29 23:54:19 +0000
+++ src/database.cpp	2013-06-07 13:40:37 +0000
@@ -106,7 +106,11 @@
     /* A unique ID is used for the connection name to ensure that we aren't
        re-using or replacing other opend databases. */
     if (!m_db.isValid())
+<<<<<<< TREE
         m_db = QSqlDatabase::addDatabase("QSQLITE", QUuid::createUuid().toString());
+=======
+        m_db = QSqlDatabase::addDatabase("QSQLITE",QUuid::createUuid().toString());
+>>>>>>> MERGE-SOURCE
     if (!m_db.isValid())
         return setError("QSqlDatabase error");
     m_db.setDatabaseName(path);

=== modified file 'src/index.cpp'
--- src/index.cpp	2013-05-10 13:22:44 +0000
+++ src/index.cpp	2013-06-07 13:40:37 +0000
@@ -146,7 +146,19 @@
     if (m_expression == expression)
         return;
 
-    m_expression = expression;
+<<<<<<< TREE
+    m_expression = expression;
+=======
+    m_expression = expression;
+
+    if (m_database)
+    {
+        m_database->putIndex(m_name, expression);
+        Q_EMIT dataInvalidated();
+    }
+
+
+>>>>>>> MERGE-SOURCE
 
     if (m_database)
     {

=== added file 'src/synchronizer.cpp'
--- src/synchronizer.cpp	1970-01-01 00:00:00 +0000
+++ src/synchronizer.cpp	2013-06-07 13:40:37 +0000
@@ -0,0 +1,526 @@
+/*
+ * Copyright (C) 2013 Canonical, Ltd.
+ *
+ * Authors:
+ *  Kevin Wright <[e-mail]>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation; version 3.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include <QDebug>
+#include <QSqlQuery>
+#include <QFile>
+#include <QSqlError>
+#include <QUuid>
+#include <QStringList>
+#include <QJsonDocument>
+
+#include "synchronizer.h"
+#include "private.h"
+
+QT_BEGIN_NAMESPACE_U1DB
+
+/*!
+    \class Synchronizer
+    \inmodule U1db
+    \ingroup modules
+
+    \brief The Synchronizer class handles synchronizing between two databases.
+
+*/
+
+/*
+
+ Below this line are methods that are standards in declarative API design. They include the element instantiation, default settings for properties and get/set methods for properties.
+
+*/
+
+/*!
+    Instantiate a new Synchronizer with an optional \a parent, usually by declaring it as a QML item.
+
+    Synchronizer elements sync two databases together, a 'source' database and a remote or local 'target' database.
+
+ */
+
+Synchronizer::Synchronizer(QObject *parent) :
+    QObject(parent), m_synchronize(false)
+{
+    qDebug()<<"Synchronizer::Synchronizer";
+
+    QObject::connect(this, &Synchronizer::syncChanged, this, &Synchronizer::onSyncChanged);
+}
+
+/*!
+    \property Synchronizer::source
+ */
+void Synchronizer::setSource(Database* source)
+{
+    qDebug()<<"Synchronizer::setSource";
+
+    if (m_source == source)
+        return;
+
+    if (m_source)
+        QObject::disconnect(m_source, 0, this, 0);
+
+    m_source = source;
+
+    Q_EMIT sourceChanged(source);
+}
+
+/*!
+    \property Synchronizer::local_targets
+ */
+void Synchronizer::setLocalTargets(QList<QObject*> local_targets)
+{
+    qDebug()<<"Synchronizer::setLocalTargets";
+
+    if (m_local_targets == local_targets)
+        return;
+
+    //if (m_local_targets)
+      //  QObject::disconnect(m_local_targets, 0, this, 0);
+
+    m_local_targets = local_targets;
+    Q_EMIT localTargetsChanged(local_targets);
+}
+
+/*!
+    \property Synchronizer::remote_targets
+ */
+void Synchronizer::setRemoteTargets(QList<QString> remote_targets)
+{
+    qDebug()<<"Synchronizer::setRemoteTargets";
+
+    if (m_remote_targets == remote_targets)
+        return;
+
+    //if (m_local_targets)
+      //  QObject::disconnect(m_local_targets, 0, this, 0);
+
+    m_remote_targets = remote_targets;
+    Q_EMIT remoteTargetsChanged(remote_targets);
+}
+
+/*!
+    \property Synchronizer::targets
+ */
+void Synchronizer::setTargets(QVariant targets)
+{
+    qDebug()<<"Synchronizer::setTargets";
+
+    if (m_targets == targets)
+        return;
+
+    //if (m_targets)
+      //  QObject::disconnect(m_targets, 0, this, 0);
+
+    m_targets = targets;
+    Q_EMIT targetsChanged(targets);
+}
+
+/*!
+    \property Synchronizer::synchronize
+ */
+void Synchronizer::setSync(bool synchronize)
+{
+    qDebug()<<"Synchronizer::setSync";
+
+    if (m_synchronize == synchronize)
+        return;
+
+    m_synchronize = synchronize;
+    Q_EMIT syncChanged(synchronize);
+}
+
+/*!
+    \property Synchronizer::resolve_to_source
+ */
+void Synchronizer::setResolveToSource(bool resolve_to_source)
+{
+    qDebug()<<"Synchronizer::setResolveToSource";
+
+    if (m_resolve_to_source == resolve_to_source)
+        return;
+
+    m_resolve_to_source = resolve_to_source;
+    Q_EMIT resolveToSourceChanged(resolve_to_source);
+}
+
+/*!
+
+ */
+Database* Synchronizer::getSource()
+{
+    qDebug()<<"Synchronizer::getSource";
+
+    return m_source;
+}
+
+/*!
+
+ */
+QList<QObject*> Synchronizer::getLocalTargets()
+{
+    qDebug()<<"Synchronizer::getLocalTargets";
+
+    return m_local_targets;
+}
+
+/*!
+
+ */
+QList<QString> Synchronizer::getRemoteTargets()
+{
+    qDebug()<<"Synchronizer::getRemoteTargets";
+
+    return m_remote_targets;
+}
+
+/*!
+
+ */
+QVariant Synchronizer::getTargets()
+{
+    qDebug()<<"Synchronizer::getTargets";
+
+    return m_targets;
+}
+
+
+/*!
+
+ */
+bool Synchronizer::getSync()
+{
+    qDebug()<<"Synchronizer::getSync";
+
+    return m_synchronize;
+}
+
+/*!
+
+ */
+bool Synchronizer::getResolveToSource(){
+
+    qDebug()<<"Synchronizer::getResolveToSource";
+
+    return m_resolve_to_source;
+}
+
+/*
+
+ Below this line represents the unique API methods that are not part of standard declarative API design.
+
+*/
+
+void Synchronizer::onSyncChanged(bool synchronize){
+
+    qDebug() << "Synchronizer::onSyncChanged = " << synchronize;
+
+    /*
+     * `validator` is used to ensure that the QVariant types, for a given key,
+     * within each QMap that represents a target db defintion, are correct.
+     *
+     * Similarily, `mandatory` checks to ensure the minimum necessary properties
+     * have been set with some value.
+     *
+     * There may be a more elegant way to approach this, but for now it will do.
+     *
+     */
+
+    QList<QList<QString>> errors;
+
+    QMap<QString,QString>validator;
+
+    validator.insert("remote","bool");
+    validator.insert("location","QString");
+    validator.insert("resolve_to_source","bool");
+    validator.insert("errors", "QStringList");
+
+    QList<QString>mandatory;
+
+    mandatory.append("remote");
+    mandatory.append("location");
+    mandatory.append("resolve_to_source");
+
+    if(synchronize == true){
+
+        int index = 0;
+
+
+        Database* source = getSource();
+
+        QList<QVariant> targets = getTargets().toList();
+        QList<QVariant> sync_targets;
+
+        Q_FOREACH (QVariant target_variant, targets)
+        {
+            index++;
+            QString index_number = QString::number(index);
+
+            QMap<QString, QVariant> target = target_variant.toMap();
+
+            QList<QString> error;
+
+            bool valid = true;
+            bool complete = true;
+
+            QMapIterator<QString, QVariant> i(target);
+            while (i.hasNext()) {
+
+                i.next();
+
+                if(validator.contains(i.key())&&validator[i.key()]!=i.value().typeName()){
+                    valid = false;
+
+                    error.append(index_number + ": For Key: " + i.key() + " Expecting Type: " + validator[i.key()] + " Received Type: " + i.value().typeName());
+                    target.insert("sync",false);
+
+                    break;
+                }
+
+                if(valid==false){
+                    targets.removeOne(target);
+                    break;
+                }
+                else{
+                    QListIterator<QString> j(mandatory);
+
+                    while(j.hasNext()){
+                        QString value = j.next();
+                        if(!target.contains(value)){
+                            error.append(index_number + ": Expected Key: `" + value + "` but it is not present.");
+                            target.insert("sync",false);
+                            targets.removeOne(target);
+                            complete = false;
+                            break;
+                        }
+                    }
+                    if(complete==false){
+                        break;
+                    }
+
+                }
+            }
+
+            if(target.contains("sync")&&target["sync"]==false){
+                errors.append(error);
+            }
+            else
+            {
+                target.insert("sync",true);
+                sync_targets.append(target);
+            }
+
+        }
+
+
+
+        Q_FOREACH (QStringList err, errors){
+            Q_FOREACH (QString error, err){
+                qDebug()<<error;
+            }
+        }
+
+        synchronizeTargets(source, sync_targets);
+
+/* The source replica asks the target replica for the information it has stored about the last time these two replicas were synchronised (if ever).*/
+
+        //QList<QObject*> local_targets = this->getLocalTargets();
+
+        /*Q_FOREACH (QObject* local_target, local_targets)
+        {
+
+            Database *target = (Database*)local_target;
+            qDebug() << "Synchronizer::onSyncChanged Q_FOREACH (Database* local_target, local_targets) = " << target->getPath();
+
+            //syncWithLocalTarget(Database *source, Database *target, bool resolve_to_source)
+
+        }*/
+
+        //QList<QString> remote_targets = this->getRemoteTargets();
+
+        /*Q_FOREACH (QString remote_target, remote_targets)
+        {
+
+            qDebug() << "Synchronizer::onSyncChanged Q_FOREACH (QObject* remote_target, remote_targets) = " << remote_target;
+
+            //syncWithRemoteTarget(Database *source, QString target_url, bool resolve_to_source)
+
+        }*/
+
+        QMap<QString, QVariant> sync_from_information;
+        //sync_from_information.insert("source_replica_uid",source_replica_uid);
+        sync_from_information.insert("source_replica_generation","");
+        sync_from_information.insert("source_transaction_id","");
+        //sync_from_information.insert("target_replica_uid",target_replica_uid);
+        sync_from_information.insert("target_replica_generation","");
+        sync_from_information.insert("target_replica_transaction_id","");
+
+/*
+
+The application wishing to synchronise sends the following GET request to the server:
+
+GET /thedb/sync-from/my_replica_uid
+
+Where thedb is the name of the database to be synchronised, and my_replica_uid is the replica id of the application’s (i.e. the local, or synchronisation source) database
+
+*/
+
+/*
+
+The target responds with a JSON document that looks like this:
+
+{
+    "target_replica_uid": "other_replica_uid",
+    "target_replica_generation": 12,
+    "target_replica_transaction_id": "T-sdkfj92292j",
+    "source_replica_uid": "my_replica_uid",
+    "source_replica_generation": 23,
+    "source_transaction_id": "T-39299sdsfla8"
+}
+
+With all the information it has stored for the most recent synchronisation between itself and this particular source replica. In this case it tells us that the synchronisation target believes that when it and the source were last synchronised, the target was at generation 12 and the source at generation 23.
+
+*/
+
+
+
+/* The source replica validates that its information regarding the last synchronisation is consistent with the target’s information, and raises an error if not. (This could happen for instance if one of the replicas was lost and restored from backup, or if a user inadvertently tries to synchronise a copied database.) */
+
+
+
+/* The source replica generates a list of changes since the last change the target replica knows of. */
+
+
+
+/* The source replica checks what the last change is it knows about on the target replica. */
+
+
+
+/* If there have been no changes on either replica that the other side has not seen, the synchronisation stops here. */
+
+
+
+/* The source replica sends the changed documents to the target, along with what the latest change is that it knows about on the target replica. */
+
+
+
+/* The target processes the changed documents, and records the source replica’s latest change. */
+
+
+
+/* The target responds with the documents that have changes that the source does not yet know about. */
+
+
+
+/* The source processes the changed documents, and records the target replica’s latest change. */
+
+
+
+/* If the source has seen no changes unrelated to the synchronisation during this whole process, it now sends the target what its latest change is, so that the next synchronisation does not have to consider changes that were the result of this one.*/
+
+        setSync(false);
+
+
+    }
+    else{
+
+    }
+}
+
+void Synchronizer::synchronizeTargets(Database *source, QVariant targets){
+
+    qDebug() << "Synchronizer::synchronizeTargets";
+
+    if(targets.typeName()== QStringLiteral("QVariantList")){
+
+        QList<QVariant> target_list = targets.toList();
+
+        QListIterator<QVariant> i(target_list);
+
+        while(i.hasNext()){
+
+            QVariant target = i.next();
+
+            if(target.typeName()== QStringLiteral("QVariantMap")){
+                QMap<QString,QVariant> target_map = target.toMap();
+
+                if(target_map.contains("remote")&&target_map["remote"]==false){
+                    if(target_map.contains("sync")&&target_map["sync"]==true){
+                        syncLocalToLocal(source, target_map);
+                    }
+                }
+                else if(target_map.contains("remote")&&target_map["remote"]==true){
+                    if(target_map.contains("sync")&&target_map["sync"]==true){
+                        qDebug() << "Remote database sync is under construction. Try again later.";
+                    }
+                }
+                else{
+
+                }
+            }
+
+
+        }
+
+    }
+
+
+}
+
+void Synchronizer::syncLocalToLocal(Database *source, QMap<QString,QVariant> target)
+{
+    qDebug() << "Synchronizer::syncLocalToLocal";
+
+    QSqlDatabase db;
+
+    db = QSqlDatabase::addDatabase("QSQLITE",QUuid::createUuid().toString());
+
+    QString target_db_name = target["location"].toString();
+
+    QFile target_db_file(target_db_name);
+
+    if(!target_db_file.exists())
+    {
+        qDebug()<< "Local database " << target_db_name << " does not exist";
+    }
+    else
+    {
+        db.setDatabaseName(target_db_name);
+        if (!db.open()){
+            qDebug() << db.lastError().text();
+        }
+        else{
+            QString source_uid;
+
+            QSqlQuery query (db.exec("SELECT value FROM u1db_config WHERE name = 'replica_uid'"));
+
+            if(!query.lastError().isValid() && query.next()){
+                source_uid = query.value(0).toString();
+            }
+            else{
+                qDebug() << query.lastError().text();
+            }
+        }
+
+    }
+
+}
+
+
+QT_END_NAMESPACE_U1DB
+
+#include "moc_synchronizer.cpp"
+

=== added file 'src/synchronizer.h'
--- src/synchronizer.h	1970-01-01 00:00:00 +0000
+++ src/synchronizer.h	2013-06-07 13:40:37 +0000
@@ -0,0 +1,88 @@
+/*
+ * Copyright (C) 2013 Canonical, Ltd.
+ *
+ * Authors:
+ *  Kevin Wright <[e-mail]>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation; version 3.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef U1DB_SYNCHRONIZER_H
+#define U1DB_SYNCHRONIZER_H
+
+#include <QtCore/QObject>
+#include <QSqlDatabase>
+#include <QVariant>
+
+#include "database.h"
+
+QT_BEGIN_NAMESPACE_U1DB
+
+class Q_DECL_EXPORT Synchronizer : public QObject {
+    Q_OBJECT
+#ifdef Q_QDOC
+    Q_PROPERTY(Database* source READ getSource WRITE setSource NOTIFY sourceChanged)   
+#else
+    Q_PROPERTY(QT_PREPEND_NAMESPACE_U1DB(Database*) source READ getSource WRITE setSource NOTIFY sourceChanged)  
+#endif
+    Q_PROPERTY(bool synchronize READ getSync WRITE setSync NOTIFY syncChanged)
+    Q_PROPERTY(bool resolve_to_source READ getResolveToSource WRITE setResolveToSource NOTIFY resolveToSourceChanged)
+    //Q_PROPERTY(QList <QObject*> local_targets READ getLocalTargets WRITE setLocalTargets NOTIFY localTargetsChanged)
+    //Q_PROPERTY(QList <QString> remote_targets READ getRemoteTargets WRITE setRemoteTargets NOTIFY remoteTargetsChanged)
+    Q_PROPERTY(QVariant targets READ getTargets WRITE setTargets NOTIFY targetsChanged)
+
+public:
+    Synchronizer(QObject* parent = 0);
+    Database* getSource();
+    QList<QObject*> getLocalTargets();
+    QList<QString> getRemoteTargets();
+    QVariant getTargets();
+    bool getSync();
+    bool getResolveToSource();
+    void setSource(Database* source);
+    void setLocalTargets(QList<QObject*> local_targets);
+    void setRemoteTargets(QList<QString> remote_targets);
+    void setTargets(QVariant targets);
+    void setSync(bool synchronize);
+    void setResolveToSource(bool resolve_to_source);
+
+    void syncWithLocalTarget(Database *source, Database *target, bool resolve_to_source);
+    void syncWithRemoteTarget(Database *source, QString target_url, bool resolve_to_source);
+    void syncLocalToLocal(Database *source, QMap<QString,QVariant> target);
+    void synchronizeTargets(Database *source, QVariant targets);
+
+Q_SIGNALS:
+    void sourceChanged(Database* source);
+    void localTargetsChanged(QList<QObject*> local_targets);
+    void remoteTargetsChanged(QList<QString> remote_targets);
+    void targetsChanged(QVariant targets);
+    void syncChanged(bool synchronize);
+    void resolveToSourceChanged(bool resolve_to_source);
+private:
+    Q_DISABLE_COPY(Synchronizer)
+    Database* m_source;
+    bool m_synchronize;
+    bool m_resolve_to_source;
+    QList <QObject*> m_local_targets;
+    QList <QString> m_remote_targets;
+    QVariant m_targets;
+    QList <QStringList> m_errors;
+
+    void onSyncChanged(bool synchronize);
+
+};
+
+QT_END_NAMESPACE_U1DB
+
+#endif // U1DB_SYNCHRONIZER_H
+