1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
/****************************************************************************
**
** 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.
*/
|
