|
1 \subsection{Data Store Server Interface} |
|
2 |
|
3 A data store (DS) retains information across invocations of DTN2 |
|
4 software; a DS server manages one or more data stores. Clients of the |
|
5 DS server include the BPA, the DP, and the CLA; the DS server may also |
|
6 be used by applications (A/M module). |
|
7 |
|
8 DTN2 runs well on small devices, and when augmenting it to support |
|
9 external data stores we do not want to make any changes that would put |
|
10 this at risk. One of the reasons that DTN2 can run on small devices is |
|
11 that it does not require a data store with rich semantics; its data |
|
12 model is that of a simple persistent hash table. When DTN2 stores a |
|
13 C++ object, it first serializes the object as a string of octets, and |
|
14 then inserts the object into the (abstract) persistent hash table. The |
|
15 persistent hash table can be implemented using any number of |
|
16 underlying storage methods---files, a simple persistent hash table for |
|
17 octet strings, or a more traditional database. |
|
18 |
|
19 On the other hand, DTN2 also runs well on large devices, and we wish |
|
20 to support research that will need a data model that is richer than |
|
21 that offered by opaque octet strings. Decision plane components will |
|
22 need access to the fields of the persistently stored objects, hence |
|
23 our DS interface should provide field-level access. |
|
24 |
|
25 In addition, we envision two general development models for data |
|
26 stores and DP components. First, one or more simple DS servers will be |
|
27 developed independently of DP components and made available for |
|
28 general use; for some DP components these DS servers will be |
|
29 sufficient for their needs. In other cases the DP will need more |
|
30 advanced support from the DS server (e.g. will require that the DS |
|
31 server be able to perform {\it inference}). Advanced DS servers, |
|
32 designed to support these DP components, will likely provide a very |
|
33 rich interface to their clients, using a syntax that we cannot know |
|
34 {\em a priori}. |
|
35 |
|
36 We must keep in mind, however, that whatever language the DP uses to |
|
37 communicate with its DS server, DTN2 must also be able to communicate |
|
38 with that DS server. DTN2 will do this through the use of an external |
|
39 DS client stub, and we have as a goal to implement a single stub that |
|
40 DTN2 can use to connect to any data store. In this way, researchers |
|
41 can innovate in the DP and the DS without having to modify DTN2, and |
|
42 can connect their components to any instance of DTN2. |
|
43 |
|
44 In summary, our requirements for the interface include the following. |
|
45 |
|
46 \begin{enumerate} |
|
47 \item The DS interface should provide support for efficient storage of |
|
48 key-value pair, for small devices with simple DPs. |
|
49 \item The DS interface should provide field-level access to |
|
50 objects, for deployments where DP components need access to the |
|
51 fields of stored objects, but do not require advanced DS server |
|
52 support. |
|
53 \item The DS interface should provide support for advanced |
|
54 DS servers (e.g. knowledge bases) that may use data |
|
55 definition and manipulation languages that are not known to us beforehand. |
|
56 \item All DS servers should support a simple, common interface |
|
57 that DTN2 will use. |
|
58 \end{enumerate} |
|
59 |
|
60 Given requirement 4, we have that all DS servers should |
|
61 support a common interface. What should that interface be? Requirement |
|
62 1 points us to a simple persistent table of (key, value) pairs, but that |
|
63 does not give us field-level access (requirement 2). And any simple |
|
64 common interface will restrict the expressiveness of advanced data |
|
65 stores / knowledge bases (requirement 3). |
|
66 |
|
67 Our solution is to provide three levels of functionality: |
|
68 |
|
69 \begin{itemize} |
|
70 \item {\tt pair} storage, which DTN2 will use when the |
|
71 DS server does not support field-based access (e.g. when running on |
|
72 small devices with a limited DP functionality). |
|
73 \item {\tt field} storage, which DTN2 will use when the DS |
|
74 server supports elements with multiple fields (e.g. when running |
|
75 with a more powerful DP). |
|
76 \item An {\tt advanced} interface used as a general escape |
|
77 mechanism for DP components, allowing them to communicate with DS |
|
78 servers using a mutually-agreed-to language (e.g. Prolog, SPARQL, |
|
79 RDF/OWL, KIF). The advanced interface will not impose any |
|
80 restrictions on the syntax of the messages passed between the DP and |
|
81 DS server. |
|
82 \end{itemize} |
|
83 |
|
84 In addition, each DS server will support a simple meta-interface that |
|
85 can be used to learn about its capabilities. |
|
86 |
|
87 We envision the following usage scenarios: |
|
88 |
|
89 \begin{itemize} |
|
90 \item {\em {\tt pair} data store server:} DTN2 stores key-value pairs, |
|
91 with the data holding an object serialized as an opaque string of octets. |
|
92 As the values are opaque, DP components must be able |
|
93 to work without information about the contents of the stored objects. |
|
94 \item {\em {\tt field} data store server:} DTN2 stores data as objects |
|
95 with multiple named fields. Decision plane components can retrieve objects from the |
|
96 DS and inspect the fields of the objects. |
|
97 \item {\em {\tt advanced} data store server:} DTN2 and clients other |
|
98 than DP components treat such a server as they would treat |
|
99 a simple data store server. Advanced DP components can query |
|
100 the DS server to learn what advanced data definition and data |
|
101 manipulation languages are supported by the latter, and |
|
102 then use these languages to perform advanced operations. As an |
|
103 example, a DP component might determine that the DS |
|
104 server supports SPARQL; the component could then |
|
105 send SPARQL queries to the DS server. |
|
106 \end{itemize} |
|
107 |
|
108 In short, we see three types of DS servers: simple (key-value) {\tt |
|
109 pair} storage servers; {\tt field} servers; and {\tt advanced} servers |
|
110 (which will also support {\tt field}-based access). |
|
111 |
|
112 \subsubsection{Implementation}\label{sec:ds-iccp-impl} |
|
113 |
|
114 The DS interface is provided using the ICCP (Section~\ref{sec:iccp}), which |
|
115 builds upon the external router interface protocol developed by MITRE. We |
|
116 require some extensions (as described below) to the current MITRE |
|
117 implementation in order to support the DS interface. |
|
118 |
|
119 Messages are encoded as XML and transmitted via TCP. Each |
|
120 transmission is preceded by a zero-padded, eight-octet, printable |
|
121 ASCII length argument, which specifies specifying the number of octets of |
|
122 XML data to follow (e.g. the characters ``00000321'' would precede 321 |
|
123 bytes of XML data). |
|
124 |
|
125 XML schema (XSD) files for the client-to-DS server and DS |
|
126 server-to-client interfaces will be provided. |
|
127 |
|
128 The protocol is asynchronous. Clients can layer a synchronous |
|
129 interface on top if they so desire (the better to work with DTN2). The |
|
130 {\em cookie} argument, present in all request messages, can be used to |
|
131 match reply messages with their corresponding requests. The cookie |
|
132 argument is not interpreted by the DS server---it is copied directly from |
|
133 a request message to the corresponding reply, and is entirely for the |
|
134 use of the client. |
|
135 |
|
136 All DS servers support the standard storage interface, but simple {\tt |
|
137 pair} servers can only handle tables with two fields (key and |
|
138 value). Advanced servers support the full storage interface. |
|
139 |
|
140 Each data store can hold a number of named tables---collections of |
|
141 (abstractly) homogeneous objects. The elements in each table have some |
|
142 number of fields. As stated above, tables in a {\tt pair} |
|
143 store are limited to two fields (key and value); tables in other data |
|
144 stores can have more fields. Each table has a distinguished field that |
|
145 is used as the key; keys are unique across all elements of the table. |
|
146 |
|
147 The number of fields per table is fixed at table creation.\footnote{Note that |
|
148 we may want to change this, e.g., if the DP wants to add arbitrary |
|
149 attribute/value pairs to stored data.} |
|
150 |
|
151 \subsubsection{Parameter Types} |
|
152 |
|
153 \begin{tabular}{|r|p{5in}|} |
|
154 \hline |
|
155 Cookie & string sent by client, returned by server on corresponding response \\ \hline |
|
156 Data Store Type & {\tt pair}, {\tt field}, {\tt advanced} \\ \hline |
|
157 DS Handle & an uninterpreted string representing a client's active connection to a data store \\ \hline |
|
158 Error code & unsigned int returned from data store (details TBD) \\ \hline |
|
159 Key, Data & byte strings \\ \hline |
|
160 Keys & a list of encryption keys \\ \hline |
|
161 Language & a string identifying a language that can be used to communicate with the DS \\ \hline |
|
162 Name & a character string, used to identify data store names, table names, and field names \\ \hline |
|
163 Password & a password string \\ \hline |
|
164 Quota & a 32-bit signed integer representing a storage quota, in MB \\ \hline |
|
165 User & a string identifying a user \\ \hline |
|
166 \end{tabular} |
|
167 |
|
168 \subsubsection{Client to Data Store Server Request Messages} |
|
169 |
|
170 This section enumerates the request messages that can be sent from |
|
171 clients (DTN2, DP components, etc.) to the DS |
|
172 server. The following section enumerates the corresponding reply |
|
173 messages, which are sent from the DS server to its clients. |
|
174 For each message defined in this section named {\em SomeMessage} |
|
175 there will be a corresponding {\em SomeMessageReply} defined below. |
|
176 |
|
177 \begin{table} |
|
178 \centering |
|
179 \begin{tabular}{|l|c|c|c|c|} |
|
180 \hline |
|
181 {\em Store Type} & {\em Data Store} & {\em Table} & {\em Element} & {\em Advanced} \\ \hline \hline |
|
182 {\tt pair} & ALL & ALL & Put, Get, Del & --- \\ \hline |
|
183 {\tt field} & ALL & ALL & ALL & --- \\ \hline |
|
184 {\tt advanced} & ALL & ALL & ALL & ALL \\ \hline |
|
185 \end{tabular} |
|
186 \caption{\label{table:supported-messages} Messages supported by each data store type.} |
|
187 \end{table} |
|
188 |
|
189 \paragraph {} |
|
190 {\bf Data store server messages} |
|
191 |
|
192 Messages sent from the client to operate on the DS server |
|
193 itself---query its capabilities, create a data store, open, close, and |
|
194 delete a data store, |
|
195 |
|
196 \method{DataStoreCapabilities(cookie)} |
|
197 { |
|
198 \metP |
|
199 {\em cookie}: character string, returned with reply |
|
200 |
|
201 \metD |
|
202 Request information about the capabilities of the DS server. |
|
203 Returns the supported languages, store type, and whether or not |
|
204 the DS server supports {\em triggers} (detailed description in |
|
205 Section \ref{sec:dsadvmsg}). |
|
206 } |
|
207 |
|
208 |
|
209 \method{DataStoreCreate(name, clear, quota, user, password, keys, cookie)} |
|
210 { |
|
211 \metP |
|
212 {\em name}: name of data store to create\\ |
|
213 {\em clear}: if true, and data store exists, clear it out\\ |
|
214 {\em quota (opt)}: maximum size in MB of the data store\\ |
|
215 {\em cookie}: character string, returned with reply |
|
216 |
|
217 Placeholders for authentication:\\ |
|
218 {\em user (opt)}: User name\\ |
|
219 {\em password (opt)}: Password\\ |
|
220 {\em keys (opt)}: Keys for accessing the data store |
|
221 |
|
222 \metD |
|
223 Create the named data store, or, if it exists and the {\em clear} |
|
224 flag is set, clearing it. Authentication parameters are listed |
|
225 here as a placeholder; the details of the authentication procedures |
|
226 are to be worked out. |
|
227 |
|
228 } |
|
229 |
|
230 \method{DataStoreDelete(name, user, password, keys, cookie)} |
|
231 { |
|
232 \metP |
|
233 {\em name}: name of data store to create\\ |
|
234 {\em cookie}: character string, returned with reply |
|
235 |
|
236 Placeholders for authentication:\\ |
|
237 {\em user (opt)}: User name\\ |
|
238 {\em password (opt)}: Password\\ |
|
239 {\em keys (opt)}: Keys for accessing the data store |
|
240 |
|
241 \metD |
|
242 Delete the named data store. |
|
243 } |
|
244 |
|
245 \method{DataStoreOpen(name, lease, user, password, keys, cookie)} |
|
246 { |
|
247 \metP |
|
248 {\em name}: name of data store to open\\ |
|
249 {\em lease (opt)}: lease time, in seconds\\ |
|
250 {\em cookie}: character string, returned with reply |
|
251 |
|
252 Placeholders for authentication:\\ |
|
253 {\em user (opt)}: User name\\ |
|
254 {\em password (opt)}: Password\\ |
|
255 {\em keys (opt)}: Keys for accessing the data store |
|
256 |
|
257 |
|
258 \metD |
|
259 |
|
260 Return a handle for the data store. The handle will be valid for the period of |
|
261 the lease, or until the connection drops, or the client or server is restarted. |
|
262 } |
|
263 |
|
264 \method{DataStoreStat(handle, cookie)} |
|
265 { |
|
266 \metP |
|
267 {\em handle}: A handle to the data store\\ |
|
268 {\em cookie}: character string, returned with reply |
|
269 |
|
270 \metD |
|
271 Return a description of the tables in the data store. For now this |
|
272 is just a list of the table names. |
|
273 } |
|
274 |
|
275 |
|
276 \method{DataStoreClose(handle, cookie)} |
|
277 { |
|
278 \metP |
|
279 {\em handle}: handle of data store to close.\\ |
|
280 {\em cookie}: character string, returned with reply |
|
281 |
|
282 \metD |
|
283 Drop the connection to the data store. The handle is invalidated. |
|
284 } |
|
285 |
|
286 \paragraph{} |
|
287 {\bf Table messages} |
|
288 |
|
289 Each data store can hold multiple named tables. Table messages are used to |
|
290 create, delete, and obtain information about the tables in a data store. |
|
291 |
|
292 \method{TableCreate(handle, name, keyname, keytype, list(pair(fieldname, fieldtype)), cookie)} |
|
293 { |
|
294 \metP |
|
295 {\em handle}: handle of the data store\\ |
|
296 {\em name}: table name\\ |
|
297 {\em keyname}: name of key field\\ |
|
298 {\em keytype}: type of key field\\ |
|
299 {\em fieldname}: name of a field\\ |
|
300 {\em fieldtype}: type of the field\\ |
|
301 {\em cookie}: character string, returned with reply |
|
302 |
|
303 \metD |
|
304 Create a named table, with the specified fields. The name of the |
|
305 key field is called out. The key field should also appear |
|
306 in the list of fieldnames and types. TableCreate is used by all |
|
307 stores, but only two fields (one named key, and one other) can be |
|
308 created when using a {\tt pair} data store. |
|
309 |
|
310 We envision supporting a set of standard simple data types, e.g. |
|
311 integers, strings, booleans, etc. Details are TBD. |
|
312 |
|
313 If there is already a table with that name, the data store returns |
|
314 failure. |
|
315 } |
|
316 |
|
317 \method{TableDel(handle, tablename, cookie)} |
|
318 { |
|
319 \metP |
|
320 {\em handle}: handle of the data store\\ |
|
321 {\em tablename}: table name\\ |
|
322 {\em cookie}: character string, returned with reply |
|
323 |
|
324 \metD |
|
325 Delete the named table, and all of its data |
|
326 } |
|
327 |
|
328 \method{TableStat(handle, tablename, cookie)} |
|
329 { |
|
330 \metP |
|
331 {\em handle}: handle of the data store\\ |
|
332 {\em tablename}: table name\\ |
|
333 {\em cookie}: character string, returned with reply |
|
334 |
|
335 \metD |
|
336 Return information about the named table, including the table's schema |
|
337 (the names and types of its fields), the number of elements in the table, |
|
338 and, if available, the aggregate size (in MB) of the table. |
|
339 } |
|
340 |
|
341 \method{TableKeys(handle, tablename, cookie)} |
|
342 { |
|
343 \metP |
|
344 {\em handle}: handle of the data store\\ |
|
345 {\em tablename}: table name\\ |
|
346 {\em cookie}: character string, returned with reply |
|
347 |
|
348 \metD |
|
349 Return a list of the keys stored in the table. |
|
350 } |
|
351 |
|
352 \paragraph{} |
|
353 {\bf Element messages} |
|
354 |
|
355 \method{Put(handle, tablename, keyval, list(pair(fieldname, value)), cookie)} |
|
356 { |
|
357 \metP |
|
358 {\em handle}: handle of the data store\\ |
|
359 {\em tablename}: table name\\ |
|
360 {\em key}: key value for element\\ |
|
361 {\em fieldname}: name of field\\ |
|
362 {\em value}: value for field\\ |
|
363 {\em cookie}: character string, returned with reply |
|
364 |
|
365 \metD |
|
366 {\em Put} is used to add an element to a table. Values for each |
|
367 field in the table must be specified. |
|
368 If an element with the specified key already exists, the element is replaced. |
|
369 } |
|
370 |
|
371 \method{Get(handle, tablename, key, cookie)} |
|
372 { |
|
373 \metP |
|
374 {\em handle}: handle of the data store\\ |
|
375 {\em tablename}: table name\\ |
|
376 {\em key}: key value for element\\ |
|
377 {\em cookie}: character string, returned with reply |
|
378 |
|
379 \metD |
|
380 {\em Get} is used to retrieve a single element from the table, |
|
381 based on key. See {\em Select}, below, for a more powerful query |
|
382 interface available with {\tt field} databases. |
|
383 } |
|
384 |
|
385 \method{Del(handle, tablename, key, cookie)} |
|
386 { |
|
387 \metP |
|
388 {\em handle}: handle of the data store\\ |
|
389 {\em tablename}: table name\\ |
|
390 {\em key}: key value for element\\ |
|
391 {\em cookie}: character string, returned with reply |
|
392 |
|
393 \metD |
|
394 Delete the corresponding element from the named table. |
|
395 } |
|
396 |
|
397 \method{Select(handle, tablename, list(pair(fieldname to match, value)), list(fieldname to retrieve), howmany, cookie)} |
|
398 { |
|
399 \metP |
|
400 {\em handle}: handle of the data store\\ |
|
401 {\em tablename}: table name\\ |
|
402 {\em fieldname}: name of field\\ |
|
403 {\em value}: some constant value (integer, string, etc).\\ |
|
404 {\em howmany (opt)}: maximum number of elements to return\\ |
|
405 {\em cookie}: character string, returned with reply |
|
406 |
|
407 \metD |
|
408 {\tt Field} and {\tt advanced} data stores provide |
|
409 {\em Select}, a limited query functionality. |
|
410 Fields of each element in a table are compared for equality with |
|
411 passed-in constant values.\footnote{I.e. no joins.} If an element |
|
412 matches (the fields are equal to the specified constant values) |
|
413 the fields of interest of that element are returned.\footnote{This is |
|
414 for the case where a table stores objects with many fields, but |
|
415 only a few fields are of interest.} |
|
416 |
|
417 Returns failure if there are no elements in the table that meet the |
|
418 criteria. |
|
419 |
|
420 If the {\em howmany} field is passed it specifies the maximum |
|
421 number of elements to return. If zero is passed for {\em howmany}, |
|
422 returns success (and no elements) if there are any elements that |
|
423 meet the criteria. |
|
424 } |
|
425 |
|
426 \paragraph {} |
|
427 {\bf Advanced messages} \label{sec:dsadvmsg} |
|
428 |
|
429 There are two general-purpose advanced messages for use as an escape |
|
430 mechanism when working with DS servers that have capabilities |
|
431 outside the realm of the standard interfaces. These messages provide |
|
432 the interface for interacting with a full-fledged knowledge base. |
|
433 |
|
434 \method{Eval(handle, language, command, cookie)} |
|
435 { |
|
436 \metP |
|
437 {\em handle}: handle of the data store\\ |
|
438 {\em language}: the language used by the command\\ |
|
439 {\em command}: the command itself\\ |
|
440 {\em cookie}: character string, returned with reply |
|
441 |
|
442 \metD |
|
443 The {\em Eval} message is used as a mechanism for clients to send |
|
444 commands directly to the DS server, unencumbered by the |
|
445 syntax defined above. For example, if the data store is |
|
446 implemented using an Oracle database, {\em Eval} can be used to |
|
447 send an arbitrary SQL statement. If the data store is implemented |
|
448 using Flora-2 (see \cite{Flora2} and \cite{XSB}), {\em Eval} can |
|
449 be used to send a Flora-2 expression. |
|
450 |
|
451 If the language is not one of the languages supported by the DS |
|
452 server the request will fail. |
|
453 |
|
454 Results are returned as an uninterpreted string of octets. |
|
455 } |
|
456 |
|
457 \method{Trigger(handle, language, command, cookie)} |
|
458 { |
|
459 \metP |
|
460 {\em handle}: handle of the data store\\ |
|
461 {\em language}: the language used by the command\\ |
|
462 {\em command}: the command itself\\ |
|
463 {\em cookie}: character string, returned with reply |
|
464 |
|
465 \metD |
|
466 The {\em trigger} message is a generalized form of the standard |
|
467 trigger request mechanism found in many data stores and production |
|
468 systems. {\em Trigger} sends a command to the DS server, |
|
469 just as {\em eval}, but unlike an {\em eval}, which generates only |
|
470 a single reply message, a {\em trigger} can generate multiple |
|
471 reply messages. |
|
472 |
|
473 % (In fact, {\em trigger} is more of a hint to the system than it is |
|
474 % strictly necessary. It is a way for the client to tell the data |
|
475 % store to treat the attached command as one that may generate |
|
476 % multiple responses, not a single response.) |
|
477 % Trigger are useful in order to support a callback style or an |
|
478 % event-condition-action style of operation. With triggers, the DP |
|
479 % need not look at every event of a particular type; rather it can |
|
480 % simply wait for a condition to be satisifed within the KB. Triggers |
|
481 % therefore allow a mechanism by which the DP can delegate some of the |
|
482 % processing responsibility to an intelligent data store |
|
483 |
|
484 If the data store does not support triggers the request will fail. |
|
485 |
|
486 If the language is not one of the languages supported by the DS |
|
487 server the request will fail. |
|
488 } |
|
489 |
|
490 %%---------------------------------------------------------------- |
|
491 |
|
492 \subsubsection{Data Store Server to Client Reply Messages} |
|
493 |
|
494 Note: the specifics of error codes are TBD. Assume for now that |
|
495 possible error codes include SUCCESS and FAILURE, with more likely to |
|
496 be defined. |
|
497 |
|
498 \paragraph {} |
|
499 {\bf Data store server replies} |
|
500 |
|
501 \method{DataStoreCapabilitiesReply(cookie, dstype, list(languages), |
|
502 supports-triggers, error)} |
|
503 { |
|
504 \metP |
|
505 {\em dstype}: string ({\tt pair}, {\tt field}, or {\tt advanced}).\\ |
|
506 {\em language}: uninterpreted strings, representing a language |
|
507 supported by this DS server (e.g. FLORA-2, KIF, |
|
508 RDF/OWL). The meanings of each string is a private contract |
|
509 between DS server and DP component authors.\\ |
|
510 {\em supports-triggers}: boolean, true or false.\\ |
|
511 {\em cookie}: character string sent on request\\ |
|
512 {\em error}: error (result) code |
|
513 |
|
514 \metD |
|
515 Information about the capabilities of the DS server. |
|
516 The supported languages (strings), store type ({\tt pair}, {\tt |
|
517 field}, or {\tt advanced}), and whether or not |
|
518 the DS server supports {\em triggers} (detailed description in |
|
519 Section \ref{sec:dsadvmsg}). |
|
520 } |
|
521 |
|
522 \method{DataStoreCreateReply(cookie, error)} |
|
523 { |
|
524 \metP |
|
525 {\em cookie}: character string sent on request\\ |
|
526 {\em error}: error (result) code |
|
527 |
|
528 \metD |
|
529 Error code indicates whether the data store was successfully |
|
530 created or, if creation failed, why. |
|
531 } |
|
532 |
|
533 |
|
534 \method{DataStoreDeleteReply(cookie, error)} |
|
535 { |
|
536 \metP |
|
537 {\em cookie}: character string sent on request\\ |
|
538 {\em error}: error (result) code |
|
539 |
|
540 \metD |
|
541 Error code indicates whether the data store was successfully |
|
542 deleted or, if deletion failed, why (e.g. it was currently in use, |
|
543 it does not exist). |
|
544 } |
|
545 |
|
546 \method{DataStoreOpenReply(handle, cookie, error)} |
|
547 { |
|
548 \metP |
|
549 {\em handle}: handle for opened data store\\ |
|
550 {\em cookie}: character string sent on request\\ |
|
551 {\em error}: error (result) code |
|
552 |
|
553 \metD |
|
554 |
|
555 A handle for the opened data store. The handle will be valid for |
|
556 the period of the lease, or until the connection drops, or the |
|
557 client or server is restarted. |
|
558 } |
|
559 |
|
560 \method{DataStoreStatReply(list(tablename), cookie, error)} |
|
561 { |
|
562 \metP |
|
563 {\em tablename}: The name of a table\\ |
|
564 {\em cookie}: character string sent on request\\ |
|
565 {\em error}: error (result) code |
|
566 |
|
567 \metD |
|
568 Return the names of the tables in the data store. |
|
569 } |
|
570 |
|
571 \method{DataStoreCloseReply(cookie, error)} |
|
572 { |
|
573 \metP |
|
574 {\em cookie}: character string sent on request\\ |
|
575 {\em error}: error (result) code |
|
576 |
|
577 \metD |
|
578 Error code indicates whether data store was closed successfully. |
|
579 (One possible reason for failure is that the data store is not |
|
580 currently open.) |
|
581 } |
|
582 |
|
583 \paragraph{} |
|
584 {\bf Table replies} |
|
585 |
|
586 Each data store can hold multiple named tables. Table messages are used to |
|
587 create, delete, and obtain information about the tables in a data store. |
|
588 |
|
589 \method{TableCreateReply(cookie, error)} |
|
590 { |
|
591 \metP |
|
592 {\em cookie}: character string sent on request\\ |
|
593 {\em error}: error (result) code |
|
594 |
|
595 \metD |
|
596 Error code indicates whether the table could be created. |
|
597 } |
|
598 |
|
599 \method{TableDelReply(cookie, error)} |
|
600 { |
|
601 \metP |
|
602 {\em cookie}: character string sent on request\\ |
|
603 {\em error}: error (result) code |
|
604 |
|
605 \metD |
|
606 Error code indicates whether the table could be deleted. |
|
607 } |
|
608 |
|
609 \method{TableStatReply(tablestatus, cookie, error)} |
|
610 { |
|
611 \metP |
|
612 {\em table-status}: information about the table\\ |
|
613 {\em cookie}: character string sent on request\\ |
|
614 {\em error}: error (result) code |
|
615 |
|
616 \metD |
|
617 Specifics of {\em table-status} TBD, but will include information |
|
618 about the table's schema (a list containing the names of its |
|
619 fields and their types) and the number of elements in the table } |
|
620 |
|
621 \method{TableKeysReply(list(key), cookie, error)} |
|
622 { |
|
623 \metP |
|
624 {\em key}: a key from the table\\ |
|
625 {\em cookie}: character string sent on request\\ |
|
626 {\em error}: error (result) code |
|
627 |
|
628 \metD |
|
629 The keys for the elements stored in the table. Error code indicates |
|
630 success or failure (including no such table). |
|
631 |
|
632 } |
|
633 |
|
634 \paragraph{} |
|
635 {\bf Element replies} |
|
636 |
|
637 \method{PutReply(cookie, error)} |
|
638 { |
|
639 \metP |
|
640 {\em cookie}: character string sent on request\\ |
|
641 {\em error}: error (result) code |
|
642 |
|
643 \metD |
|
644 Error code indicates whether element was stored. |
|
645 } |
|
646 |
|
647 \method{GetReply(list(pair(fieldname, value)), cookie, error)} |
|
648 { |
|
649 \metP |
|
650 {\em fieldname}: name of field\\ |
|
651 {\em value}: value for field\\ |
|
652 {\em cookie}: character string sent on request\\ |
|
653 {\em error}: error (result) code |
|
654 |
|
655 \metD |
|
656 The requested value. Error code indicates success or failure |
|
657 (including no such key, no such table). |
|
658 } |
|
659 |
|
660 \method{DelReply(cookie, error)} |
|
661 { |
|
662 \metP |
|
663 {\em cookie}: character string sent on request\\ |
|
664 {\em error}: error (result) code |
|
665 |
|
666 \metD |
|
667 Error code indicates success or failure (including no such key, no |
|
668 such table). |
|
669 } |
|
670 |
|
671 \method{SelectReply(list(list(pair(fieldname, value))), cookie, error)} |
|
672 { |
|
673 \metP |
|
674 {\em fieldname}: name of field\\ |
|
675 {\em value}: some constant value (integer, string, etc).\\ |
|
676 {\em cookie}: character string sent on request\\ |
|
677 {\em error}: error (result) code |
|
678 |
|
679 \metD |
|
680 Each sub-list consists of (fieldname, value) information from an element |
|
681 that met the constraints of the Select. |
|
682 |
|
683 Returns failure if there are no elements in the table that meet the |
|
684 criteria, if the table does not exist, if the named fields do not exist. |
|
685 } |
|
686 |
|
687 \paragraph {} |
|
688 {\bf Advanced replies} |
|
689 |
|
690 \method{EvalReply(result, cookie, error)} |
|
691 { |
|
692 \metP |
|
693 {\em result}: the result itself, an uninterpreted string of octets\\ |
|
694 {\em cookie}: character string sent on request\\ |
|
695 {\em error}: error (result) code |
|
696 |
|
697 \metD |
|
698 The response from the DS server for the corresponding {\em |
|
699 Eval} message. The payload ({\em result} argument) is whatever the |
|
700 DS server sent. The error code is specified by the DS |
|
701 server's Eval message handler. } |
|
702 |
|
703 \method{TriggerReply(result, cookie, error)} |
|
704 { |
|
705 \metP |
|
706 {\em result}: the result itself, uninterpreted string of octets\\ |
|
707 {\em cookie}: character string sent on request\\ |
|
708 {\em error}: error (result) code |
|
709 |
|
710 \metD |
|
711 A {\em trigger} message is like an {\em Eval}, but may generate |
|
712 a second reply messages at an arbitrary time in the future. |
|
713 |
|
714 A rigorous definition of {\em trigger} semantics is TBD. |
|
715 } |
|
716 |