QtDataSync
4.2.0
A simple offline-first synchronisation framework, to synchronize data of Qt applications between devices
|
A cursor style class to read from the global change event log. More...
#include <eventcursor.h>
Public Slots | |
void | setSkipObsolete (bool skipObsolete) |
WRITE accessor for EventCursor::skipObsolete. | |
void | clearEventLog (quint64 offset=0) |
Clears all events from the log up to offset entries before the one this cursor points at. More... | |
Signals | |
void | eventLogChanged (QPrivateSignal) |
Is emitted whenever a new change event was added to the database. More... | |
void | indexChanged (quint64 index, QPrivateSignal) |
NOTIFY accessor for EventCursor::index. | |
void | keyChanged (const QtDataSync::ObjectKey &key, QPrivateSignal) |
NOTIFY accessor for EventCursor::key. | |
void | wasRemovedChanged (bool wasRemoved, QPrivateSignal) |
NOTIFY accessor for EventCursor::wasRemoved. | |
void | timestampChanged (const QDateTime ×tamp, QPrivateSignal) |
NOTIFY accessor for EventCursor::timestamp. | |
void | skipObsoleteChanged (bool skipObsolete, QPrivateSignal) |
NOTIFY accessor for EventCursor::skipObsolete. | |
Public Member Functions | |
Q_INVOKABLE QByteArray | save () const |
Returns encoded position data of the cursor to be loaded again. More... | |
bool | isValid () const |
READ accessor for EventCursor::valid. | |
QString | setupName () const |
READ accessor for EventCursor::setupName. | |
quint64 | index () const |
READ accessor for EventCursor::index. | |
QtDataSync::ObjectKey | key () const |
READ accessor for EventCursor::key. | |
bool | wasRemoved () const |
READ accessor for EventCursor::wasRemoved. | |
QDateTime | timestamp () const |
READ accessor for EventCursor::timestamp. | |
bool | skipObsolete () const |
READ accessor for EventCursor::skipObsolete. | |
Q_INVOKABLE bool | hasNext () const |
Checks if there is a newer change event after the one this cursor points to. More... | |
Q_INVOKABLE bool | next () |
Advances the cursor to the next newer change event, if one exists. More... | |
Q_INVOKABLE void | autoScanLog () |
Automatically scans though all change events. More... | |
void | autoScanLog (std::function< bool(const EventCursor *)> function, bool scanCurrent=true) |
Automatically scans though all change events, calling the given function on each event. More... | |
void | autoScanLog (QObject *scope, std::function< bool(const EventCursor *)> function, bool scanCurrent=true) |
Automatically scans though all change events, calling the given function on each event. More... | |
template<typename TClass > | |
void | autoScanLog (TClass *scope, bool(TClass::*function)(const EventCursor *), bool scanCurrent=true) |
Automatically scans though all change events, calling the given function on each event. More... | |
Public Member Functions inherited from QObject | |
virtual const QMetaObject * | metaObject () const const |
virtual void * | qt_metacast (const char *) |
virtual int | qt_metacall (QMetaObject::Call, int, void **) |
QObject (QObject *parent) | |
virtual bool | event (QEvent *e) |
virtual bool | eventFilter (QObject *watched, QEvent *event) |
QString | objectName () const const |
void | setObjectName (const QString &name) |
bool | isWidgetType () const const |
bool | isWindowType () const const |
bool | signalsBlocked () const const |
bool | blockSignals (bool block) |
QThread * | thread () const const |
void | moveToThread (QThread *targetThread) |
int | startTimer (int interval, Qt::TimerType timerType) |
int | startTimer (std::chrono::milliseconds time, Qt::TimerType timerType) |
void | killTimer (int id) |
T | findChild (const QString &name, Qt::FindChildOptions options) const const |
QList< T > | findChildren (const QString &name, Qt::FindChildOptions options) const const |
QList< T > | findChildren (const QRegExp ®Exp, Qt::FindChildOptions options) const const |
QList< T > | findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const |
const QObjectList & | children () const const |
void | setParent (QObject *parent) |
void | installEventFilter (QObject *filterObj) |
void | removeEventFilter (QObject *obj) |
QMetaObject::Connection | connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const const |
bool | disconnect (const char *signal, const QObject *receiver, const char *method) const const |
bool | disconnect (const QObject *receiver, const char *method) const const |
void | dumpObjectTree () |
void | dumpObjectInfo () |
void | dumpObjectTree () const const |
void | dumpObjectInfo () const const |
bool | setProperty (const char *name, const QVariant &value) |
QVariant | property (const char *name) const const |
QList< QByteArray > | dynamicPropertyNames () const const |
void | destroyed (QObject *obj) |
void | objectNameChanged (const QString &objectName) |
QObject * | parent () const const |
bool | inherits (const char *className) const const |
void | deleteLater () |
Static Public Member Functions | |
static bool | isEventLogActive (const QString &setupName=DefaultSetup) |
Checks if the eventlog is currently beeing collected or not. More... | |
static EventCursor * | first (QObject *parent=nullptr) |
Create a cursor positioned on the oldest change event. More... | |
static EventCursor * | first (const QString &setupName, QObject *parent=nullptr) |
Create a cursor positioned on the oldest change event. More... | |
static EventCursor * | last (QObject *parent=nullptr) |
Create a cursor positioned on the newest change event. More... | |
static EventCursor * | last (const QString &setupName, QObject *parent=nullptr) |
Create a cursor positioned on the newest change event. More... | |
static EventCursor * | create (quint64 index, QObject *parent=nullptr) |
Create a cursor positioned on the given index, if it is a valid index. More... | |
static EventCursor * | create (quint64 index, const QString &setupName, QObject *parent=nullptr) |
Create a cursor positioned on the given index, if it is a valid index. More... | |
static EventCursor * | load (const QByteArray &data, QObject *parent=nullptr) |
Create a cursor positioned on the index provided by the previously stored data, if still valid. More... | |
static EventCursor * | load (const QByteArray &data, const QString &setupName, QObject *parent=nullptr) |
Create a cursor positioned on the index provided by the previously stored data, if still valid. More... | |
Static Public Member Functions inherited from QObject | |
QString | tr (const char *sourceText, const char *disambiguation, int n) |
QString | trUtf8 (const char *sourceText, const char *disambiguation, int n) |
QMetaObject::Connection | connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type) |
QMetaObject::Connection | connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type) |
QMetaObject::Connection | connect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type) |
QMetaObject::Connection | connect (const QObject *sender, PointerToMemberFunction signal, Functor functor) |
QMetaObject::Connection | connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type) |
bool | disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method) |
bool | disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method) |
bool | disconnect (const QMetaObject::Connection &connection) |
bool | disconnect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method) |
Properties | |
bool | valid |
Holds whether the cursor is positioned on a valid record. More... | |
QString | setupName |
Holds the name of the setup this cursor operates on. More... | |
quint64 | index |
Holds the current position of the cursor. More... | |
QtDataSync::ObjectKey | key |
Holds the key of the dataset this cursor is positioned on. More... | |
bool | wasRemoved |
Holds the information whether the dataset was changed or removed. More... | |
QDateTime | timestamp |
Provides the timestamp of when the change occured. More... | |
bool | skipObsolete |
Specify if the cursor should automatically skip obsolete changes when advancing. More... | |
Properties inherited from QObject | |
objectName | |
Additional Inherited Members | |
Protected Member Functions inherited from QObject | |
QObject * | sender () const const |
int | senderSignalIndex () const const |
int | receivers (const char *signal) const const |
bool | isSignalConnected (const QMetaMethod &signal) const const |
virtual void | timerEvent (QTimerEvent *event) |
virtual void | childEvent (QChildEvent *event) |
virtual void | customEvent (QEvent *event) |
virtual void | connectNotify (const QMetaMethod &signal) |
virtual void | disconnectNotify (const QMetaMethod &signal) |
A cursor style class to read from the global change event log.
The EventCursor class provides a simple interface to walk through all the changes that have been done on the internal data set. Unlike the DataStore, which presents the actual data but does give no guarantees on completeness of change events, this class can be used to deterministically handle all changes in chronological order.
Definition at line 19 of file eventcursor.h.
QtDataSync::EventCursor::autoScanLog | ( | ) |
Automatically scans though all change events.
EventCursorException | Thrown if access to the underlying database failed |
This method basically just calles next() in a loop to walk through all existing change events until it reaches the current one. After that happend, the cursor will now react on changes to the events in the database and automatically advance forward as soon as a new event was logged there.
This method honors the value of skipObsolete
QtDataSync::EventCursor::autoScanLog | ( | std::function< bool(const EventCursor *)> | function, |
bool | scanCurrent = true |
||
) |
Automatically scans though all change events, calling the given function on each event.
function | The callback to be called for each event visited |
scanCurrent | Specify if the event currently pointed should be passed to the function before advancing to the next one |
EventCursorException | Thrown if access to the underlying database failed |
This method basically just calles next() in a loop to walk through all existing change events until it reaches the current one. After that happend, the cursor will now react on changes to the events in the database and automatically advance forward as soon as a new event was logged there.
For every event visited that way, the function callback is called once with this cursor passed to it. The method can return true to continue the loop or false to end it.
This method honors the value of skipObsolete
QtDataSync::EventCursor::autoScanLog | ( | QObject * | scope, |
std::function< bool(const EventCursor *)> | function, | ||
bool | scanCurrent = true |
||
) |
Automatically scans though all change events, calling the given function on each event.
scope | The object scope to limit the callback to. Only call as long as the scope still exists |
function | The callback to be called for each event visited |
scanCurrent | Specify if the event currently pointed should be passed to the function before advancing to the next one |
EventCursorException | Thrown if access to the underlying database failed |
This method basically just calles next() in a loop to walk through all existing change events until it reaches the current one. After that happend, the cursor will now react on changes to the events in the database and automatically advance forward as soon as a new event was logged there.
For every event visited that way, the function callback is called once with this cursor passed to it. The method can return true to continue the loop or false to end it.
This method honors the value of skipObsolete
void QtDataSync::EventCursor::autoScanLog | ( | TClass * | scope, |
bool(TClass::*)(const EventCursor *) | function, | ||
bool | scanCurrent = true |
||
) |
Automatically scans though all change events, calling the given function on each event.
scope | The object scope to limit the callback to. Only call as long as the scope still exists |
function | The callback to be called for each event visited |
scanCurrent | Specify if the event currently pointed should be passed to the function before advancing to the next one |
EventCursorException | Thrown if access to the underlying database failed |
This method basically just calles next() in a loop to walk through all existing change events until it reaches the current one. After that happend, the cursor will now react on changes to the events in the database and automatically advance forward as soon as a new event was logged there.
For every event visited that way, the function callback is called once with this cursor passed to it. The method can return true to continue the loop or false to end it.
This method honors the value of skipObsolete
Definition at line 160 of file eventcursor.h.
|
slot |
Clears all events from the log up to offset entries before the one this cursor points at.
offset | The number of events to keep before the current one |
EventCursorException | Thrown if access to the underlying database failed |
When called, all events that are older than the one currently pointed to are deleted. You can additionally keep entries by specifing an offset. If the offset is for example 5, there will be 5 entries left that are older than the current one after the cleanup.
|
static |
Create a cursor positioned on the given index, if it is a valid index.
index | The index of the change event to position the cursor on |
parent | The parent object to set as parent of the event cursor |
EventCursorException | Thrown if access to the underlying database failed |
If no setup name is specified, the cursor is created for the default setup name
|
static |
Create a cursor positioned on the given index, if it is a valid index.
setupName | The name of the setup to create the cursor for |
index | The index of the change event to position the cursor on |
parent | The parent object to set as parent of the event cursor |
EventCursorException | Thrown if access to the underlying database failed |
If no setup name is specified, the cursor is created for the default setup name
|
signal |
Is emitted whenever a new change event was added to the database.
This signal does not mean that the event the current cursor is pointing to has changed. It only notifies you that there are new events that have been added to the underlying event log. This signal is used by autoScanLog() to automatically advance through new events.
|
static |
Create a cursor positioned on the oldest change event.
parent | The parent object to set as parent of the event cursor |
EventCursorException | Thrown if access to the underlying database failed |
If no setup name is specified, the cursor is created for the default setup name
Create a cursor positioned on the oldest change event.
setupName | The name of the setup to create the cursor for |
parent | The parent object to set as parent of the event cursor |
EventCursorException | Thrown if access to the underlying database failed |
If no setup name is specified, the cursor is created for the default setup name
QtDataSync::EventCursor::hasNext | ( | ) | const |
Checks if there is a newer change event after the one this cursor points to.
EventCursorException | Thrown if access to the underlying database failed |
This method does not change the position or general state of the current cursor. This method honors the value of skipObsolete
|
static |
Checks if the eventlog is currently beeing collected or not.
setupName | The name of the setup to check for an active log |
Eventlogging must be explicitly enabled when creating a setup. In case you do not know at the point of using the cursor whether the log is actually available, you can use this method to check
|
static |
Create a cursor positioned on the newest change event.
parent | The parent object to set as parent of the event cursor |
EventCursorException | Thrown if access to the underlying database failed |
If no setup name is specified, the cursor is created for the default setup name
Create a cursor positioned on the newest change event.
setupName | The name of the setup to create the cursor for |
parent | The parent object to set as parent of the event cursor |
EventCursorException | Thrown if access to the underlying database failed |
If no setup name is specified, the cursor is created for the default setup name
|
static |
Create a cursor positioned on the index provided by the previously stored data, if still valid.
data | The data to create the cursor from |
parent | The parent object to set as parent of the event cursor |
EventCursorException | Thrown if access to the underlying database failed |
If no setup name is specified, the cursor is created for the default setup name. The following properties are restored from the data:
Use save() to save the data of an existing cursor so you can later load it again using this method.
|
static |
Create a cursor positioned on the index provided by the previously stored data, if still valid.
setupName | The name of the setup to create the cursor for |
data | The data to create the cursor from |
parent | The parent object to set as parent of the event cursor |
EventCursorException | Thrown if access to the underlying database failed |
If no setup name is specified, the cursor is created for the default setup name. The following properties are restored from the data:
Use save() to save the data of an existing cursor so you can later load it again using this method.
QtDataSync::EventCursor::next | ( | ) |
Advances the cursor to the next newer change event, if one exists.
EventCursorException | Thrown if access to the underlying database failed |
In case there was a new change event, after calling this method the cursor is now positioned on that newer record and in case it was previously valid now still is valid and true is returned. If however there was no new change event to advance to, the cursor stayes unchanged and false is returned. This means the cursor is not set to be invalid if this method fails, only the return value or the index can be used to check if the next operation actually did anything.
This method honors the value of skipObsolete
QtDataSync::EventCursor::save | ( | ) | const |
Returns encoded position data of the cursor to be loaded again.
The following properties are encoded into the data:
|
read |
Holds the current position of the cursor.
Default: 0
This index is unqiue and can uniquely identify an event. They are automatically generate and are strictly ascending, meaning that newer events will always have a higher index compared to an older event.
Accessors | |
---|---|
READ | index() |
NOTIFY | indexChanged() |
Definition at line 29 of file eventcursor.h.
|
read |
Holds the key of the dataset this cursor is positioned on.
Default: empty
This key contains both, the name of the class and the id of the dataset that was changed.
Accessors | |
---|---|
READ | key() |
NOTIFY | keyChanged() |
Definition at line 31 of file eventcursor.h.
|
read |
Holds the name of the setup this cursor operates on.
Default: QtDataSync::DefaultSetup
The setup name is the name that was passed to the Setup::create method to create the datasync instance this cursor is refering to.
Accessors | |
---|---|
READ | setupName() |
CONSTANT |
Definition at line 26 of file eventcursor.h.
|
readwrite |
Specify if the cursor should automatically skip obsolete changes when advancing.
Default: true
If skipping obsolete entries is enabled, the cursor will automatically skip multiple change events on the same dataset and only consider the most recent ones. If set to false, all entries are used instead.
A simple example. Consider the following chain of events:
If this property is set to true, calling next() will move it to 002
. Calling next again will make it skip 003
and move to 004
instead, because there is a newer change event for the same dataset (005
). Calling next one more time then moves to 005
. If this property had been disabled, entry 003
would not have been skipped, event though the change that was done has already been succeeded by a newer one.
Accessors | |
---|---|
READ | skipObsolete() |
WRITE | setSkipObsolete() |
NOTIFY | skipObsoleteChanged() |
Definition at line 38 of file eventcursor.h.
|
read |
Provides the timestamp of when the change occured.
Default: invalid
Timestamps are generated internally based on the current local time and then converted to UTC the moment a dataset was changed. This property loads the UTC variant and converts it back to the current local time, which means this property always returns the time converter to the current local time. If you need UTC timestamps, convert it back. The timestamp contains the date and time with milliseconds precision.
Accessors | |
---|---|
READ | timestamp() |
NOTIFY | timestampChanged() |
Definition at line 35 of file eventcursor.h.
|
read |
Holds whether the cursor is positioned on a valid record.
Default: false
This can be used to check if an eventcursor returned from one of the static functions is actually valid.
Accessors | |
---|---|
READ | isValid() |
CONSTANT |
Definition at line 24 of file eventcursor.h.
|
read |
Holds the information whether the dataset was changed or removed.
Default: false
If a change event created a new dataset or modified an existing one, than this property is set to false. If an existing dataset was deleted it is set to true.
Accessors | |
---|---|
READ | wasRemoved() |
NOTIFY | wasRemovedChanged() |
Definition at line 33 of file eventcursor.h.