/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** 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.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\page partitions.html
\title Partitions

\section1 Introduction

JSON DB may be configured as a number of partitions, each with its
own unique name. All operations in JSON DB operate on exactly one partition at
a time.

\section1 Accessing Partitions

The various partitions in a set are accessed via the \l {Partition} element in QML. In
C++, the partition is selected by \c setPartition() on a
\l {QJsonDbReadRequest}, \l {QJsonDbWriteRequest} or \l {QJsonDbWatcher}.

\section1 Defining Partitions

Partitions in JSON DB are defined via .json files. The filenames must be of the
form \c partitions*.json. JSON DB searches a series of directories looking for
such files and the search order is defined as follows:

\list
\li If -config-path <PATH> is passed as an argument to the JSON DB binary
(jsondb) then this location is searched.
\li If the above argument is not provided, JSON DB searches the colon-separated
list of directories specified by the JSONDB_CONFIG_SEARCH_PATH environment variable
if it's defined.
\li If neither of these above options are used, the current working directory and
/etc/jsondb are searched.
\endlist

The partition definition files consist of an array of objects which define the
partitions:
\code
[
  {
    "name" : "com.qt-project.partition1",
    "default" : true
  },
  {
    "name" : "com.qt-project.partition2",
    "path" : "/var/run/jsondb/partition2"
  }
]
\endcode

The allowed properties:

\table
\row

\row
\li name
\li The name of the partition, specified on all requests to the database.
If more than one partition specifies the same \c name property, JSON DB
only loads the first one it finds. See \l {Partition::name} and
\l {QJsonDbRequest::partition}.

\row
\li path
\li The path where the partition files should be stored. If not specified, it
defaults to the current working directory.

\row
\li default
\li If this boolean property is \c true, then requests which do not specify
a partition will default to this partition. If more than one partition is marked
as default, JSON DB chooses one arbitrarily.

\row
\li removable
\li If this bool property is \c true, then the path of the partition is assumed
to be on removable media. See \l {Removable Partitions} for more details.

\endtable

If no partitions.json files are created, then the database defaults to a single
partition with the name "default".

The paths specified in the partition definition file \e must exist prior to
starting the JSON DB daemon. If the directories don't exist, the daemon will
not start. The exception to this is \l {Removable Partitions}.

A removable partition is not allowed to be a default partition. If the \e removable
and \e default properties are both true for the same partition, the \e default property
is automatically set to false.

If only removable partitions are specified, an extra partition is automatically created
in the current working directory to act as the default partition. The current working
directory is assumed to be located on a non-removable medium in that case.

\section1 Querying Available Partitions

The current state of the partitions in the system are reflected in objects
of _type \c Partition in \l {The Ephemeral Partition}. These objects can be
queried to find the currently available partitions. These objects are read-only.
For example:

\code
jclient> query partition:Ephemeral [?_type="Partition"]
Received 3 object(s) [state 0]
{
    "_owner": "root",
    "_type": "Partition",
    "_uuid": "{2dee7d2f-2cb6-358b-a11a-72f24bfe1063}",
    "_version": "1-29b8899e4d",
    "available": true,
    "name": "partition2",
    "path": "/var/run/jsondb/partition2"
},
{
    "_owner": "root",
    "_type": "Partition",
    "_uuid": "{5fc4e506-ce38-3eb7-85e2-ecf612432b13}",
    "_version": "1-fbf10c15e8",
    "available": false,
    "name": "card",
    "path": "/media/card/jsondb"
},
{
    "_owner": "root",
    "_type": "Partition",
    "_uuid": "{d5545f62-86c8-39e7-a721-2ac739309394}",
    "_version": "1-bf7b68056d",
    "available": true,
    "default": true,
    "name": "partition1",
    "path": "/var/run/jsondb/partition1"
}
\endcode

\section1 The Ephemeral Partition

JSON DB offers a partition called \c Ephemeral. Objects written to this
partition are not persistent, but rather stored entirely in memory. The
entire partition is cleared every time the database server is restarted. This
partition can be very useful for storing frequently updated data since it does not
cause any disk I/O.

\code
QJsonDbReadRequest *request = new QJsonDbReadRequest(this);
request->setQuery("[?_type=\"Status\"]");
request->setPartition("Ephemeral");
\endcode

\section1 Private Partitions

JSON DB also provides support for private partitions on a per-user basis. These
partitions are private to each user and are disconnected from the database daemon
itself. Rather than routing calls to these private partitions through the daemon
(as with typical partitions) the JSON DB client library directly accesses the
database files.

Private partitions are addressed as follows:
\list
\li If the partition is specified as "Private", then the private partition for the
current user is used.
\li If the partition is specified as "username.Private" (where "username" is a user
with a home directory on the system), then the private partition for the user with
the specified username is used.
\endlist

Only a single thread/process may access a private partition at a time. This is because
the database files are directly accessed and do not support concurrency. Advisory file
locks are used to ensure that two clients do not access the database files at the same
time.

Private partitions currently do not support \l Notifications. This means that the QML
list models will not automatically update themselves when used with private partitions.

Apart from the naming scheme and the lack of \l Notifications, private partitions behave
like normal partitions and are accessed via exactly the same APIs as other partitions.

\section1 Removable Partitions

JSON DB supports partitions on removable media. When the \c removable property is
\c true for a partition, the JSON DB daemon can run even when the path for the partition
doesn't exist. If the media for a partition is not present in the system, the \c Partition
object in the Ephemeral partition will have an \c available property with a value of \c
false. If a client attempts to read or write to an unavailable partition, the daemon will
return a \l {QJsonDbRequest::PartitionUnavailable} error.

The daemon does not poll or watch the filesystem to determine whether or not a removable
partition has become available. Instead, whenever the media for a removal partition is
inserted and removed, the JSON DB daemon must be sent a SIGHUP signal. This will cause the
daemon to reparse the partition definitions and check for partition availability.
*/