/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.  Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\page notifications.html
\title Notifications

JSON DB clients can register to be informed about changes in the database via
notifications. Clients create notifications containing a query to monitor.
When an object matching the query is modified, JSON DB sends a notification
message to the client.

Notifications are registered via the \l {QJsonDbWatcher} class in C++ and
via the \l {Notification} item in QML.

Notifications usually pertain to new events in the database, but by using the
\l {QJsonDbWatcher::initialStateNumber} property, it's possible to request
notifications based on past events in the database. This can be useful in
writing a program that would need to synchronize with the database.

\section1 Actions

Clients may register to receive notifications based on one or more types
of actions that may occur in the database. The available actions are:

\table
\row
\row
\li Created
\li Notifications with this action generally represent entirely new objects
which match the specified query being created in the database. Another case is an
existing object which previously did not match the query being modified to now
match the query.

\row
\li Updated
\li Notifications with this action represent an object that matches the
specified query being updated (while still matching the query).

\row
\li Removed
\li Notifications with this action generally represent an existing object which
matches the specified query being removed from the database. Another case is an
existing object which previously matched the query being modified so that it no
longer matches the query. Whether the object has been removed or not can be
tested by checking if the object in the notification has a \c _deleted property
with the value of \c true.

\row
\li StateChanged
\li Used for historical notifications only. When this action is received, it
means that the last notification for a particular state (transaction) has been
received.

\endtable

\section1 Lifecycle

Under-the-hood, both \l {QJsonDbWatcher} and \l {Notification} function by
creating an object of type \c notification in the Ephemeral partition (see
\l {Partitions}). Once the object is created, notifications can begin being
sent. When a connection to the database drops, all of the notifications for
that connection are removed.
*/