LP#1551090: Adding necessary connectivity for xenial deb installation.
[OpenSRF.git] / doc / Persist-API.html
1 <html>
2         <head>
3                 <title>OpenSRF Persistence Application API-Namespace</title>
4                 <style><!--
5
6                         * {             font-family: sans-serif;
7                                         font-size: 13pt;
8                         }
9
10                         .sectionhead {  border: solid black 1px;
11                                         background-color: #333333;
12                                         font-weight: bold;
13                                         color: white;
14                                         text-align: center;
15                                         padding: 5px;
16                                         margin: 5px;
17                         }
18
19                         .section {      border: solid black 1px;
20                                         background-color: lightgray;
21                                         color: black;
22                                         padding: 5px;
23                                         margin: 5px;
24                                         margin-bottom: 15px;
25                         }
26
27                         .listheader {   font-weight: bold;
28                                         margin-top: 15px
29                         }
30                         
31                         .value {        font-style: italic;
32                                         margin-top: 5px;
33                                         margin-left: 20px;
34                         }
35
36                         .description {  margin-top: 0px;
37                                         margin-left: 30px;
38                         }
39
40                         //-->
41                 </style>
42
43         </head>
44         <body>
45                 <center>
46                         <h2>OpenSRF Persistence Application API-Namespace</h2>
47                         <hr width="90%">
48                 </center>
49
50                 <div style="margin: 30px;">
51                         The Persistence Application provides other OpenSRF Applications with a standard API for
52                         sharing and caching data.  These data are stored in Slots, and there are three basic
53                         interfaces for interacting with Slots:  QUEUEs, STACKs and OBJECTs.
54                 </div>
55
56                 <ul>
57                         <li> <h3>General Persistence Slot methods</h3>
58
59                         Methods used to create, set up and destroy slots.  
60                         <br><br>
61
62                         <div class="section">
63                                 <div class="sectionhead">opensrf.persist.slot.create( slot_name )</div>
64
65                                 Creates a Persistence Slot.
66
67                                 <div class="listheader">Parameters:</div>
68                                 <div class="value">slot_name (optional)</div>
69                                 <div class="description">
70                                         The name of the Persistence Slot to create.  If a name is not specified
71                                         then the Slot is given a generic, unique name.  Automatically named Slots
72                                         are destroyed as soon as they are empty.
73                                 </div>
74
75
76                                 <div class="listheader">Returns:</div>
77                                 
78                                 <div class="value">Success</div>
79                                 <div class="description">The name of the Slot that was created.</div>
80
81                                 <div class="value">Failure</div>
82                                 <div class="description">An empty (NULL) result.</div>
83                         </div>
84
85                         <div class="section">
86                                 <div class="sectionhead">opensrf.persist.slot.create_expirable( slot_name, expire_interval )</div>
87
88                                 Creates a Persistence Slot that is automatically destroyed after the specified interval.
89
90                                 <div class="listheader">Parameters:</div>
91                                 <div class="value">slot_name</div>
92                                 <div class="description">The name of the Persistence Slot to create.</div>
93                                 <div class="value">expire_interval</div>
94                                 <div class="description">
95                                         An interval describing how long to wait after an access has
96                                         occured on the Slot before automatically destroying it.  The interval
97                                         can be specified using a fairly complex, human readable format, or as
98                                         a number of seconds.  For example:
99                                         <ul>
100                                                 <li> 1 day, 2 hours and 35 minutes </li>
101                                                 <li> +2h </li>
102                                                 <li> 1 week </li>
103                                                 <li> 300 </li>
104                                         </ul>
105
106                                         A setting of 0 (zero) disables automatic expiration for a Slot.
107                                 </div>
108
109
110                                 <div class="listheader">Returns:</div>
111                                 
112                                 <div class="value">Success</div>
113                                 <div class="description">The name of the Slot that was created.</div>
114
115                                 <div class="value">Failure</div>
116                                 <div class="description">An empty (NULL) result.</div>
117                         </div>
118
119                         <div class="section">
120                                 <div class="sectionhead">opensrf.persist.slot.set_expire( slot_name, expire_interval )</div>
121
122                                 Sets or disables the expiration interval on an existing Persistence Slot.
123
124                                 <div class="listheader">Parameters:</div>
125                                 <div class="value">slot_name</div>
126                                 <div class="description">The name of the Persistence Slot to update.</div>
127                                 <div class="value">expire_interval</div>
128                                 <div class="description">
129                                         An interval describing how long to wait after an access has
130                                         occured on the Slot before automatically destroying it.  The interval
131                                         can be specified using a fairly complex, human readable format, or as
132                                         a number of seconds.  For example:
133                                         <ul>
134                                                 <li> 1 day, 2 hours and 35 minutes </li>
135                                                 <li> +2h </li>
136                                                 <li> 1 week </li>
137                                                 <li> 300 </li>
138                                         </ul>
139
140                                         A setting of 0 (zero) disables automatic expiration for a Slot.
141                                 </div>
142
143
144                                 <div class="listheader">Returns:</div>
145                                 
146                                 <div class="value">Success</div>
147                                 <div class="description">The number of seconds the requested interval represents.</div>
148
149                                 <div class="value">Failure</div>
150                                 <div class="description">An empty (NULL) result.</div>
151                         </div>
152
153                         <div class="section">
154                                 <div class="sectionhead">opensrf.persist.slot.destroy( slot_name )</div>
155
156                                 Destroys a Persistence Slot.
157
158                                 <div class="listheader">Parameters:</div>
159                                 <div class="value">slot_name</div>
160                                 <div class="description">The name of the Persistence Slot to destroy.</div>
161
162
163                                 <div class="listheader">Returns:</div>
164                                 
165                                 <div class="value">Success</div>
166                                 <div class="description">The name of the Slot that was destroyed.</div>
167
168                                 <div class="value">Failure</div>
169                                 <div class="description">An empty (NULL) result.</div>
170                         </div>
171
172                         <br>
173                         </li>
174
175                         <li> <h3>QUEUE API-Namespace Slot methods</h3>
176
177                         Uses the Slot in FIFO mode, pushing values onto one end an pulling them off the other.
178                         The QUEUE API-Namespace is useful for creating an ordered message passing access point.
179
180                         <br><br>
181
182                         <div class="section">
183                                 <div class="sectionhead">opensrf.persist.queue.push( slot_name, object )</div>
184
185                                 Adds an object to a Slot in FIFO order.
186
187                                 <div class="listheader">Parameters:</div>
188
189                                 <div class="value">slot_name</div>
190                                 <div class="description">The name of the Persistence Slot to use for storing the object.</div>
191
192                                 <div class="value">object</div>
193                                 <div class="description">The object that should be pushed onto the front of the QUEUE.</div>
194
195
196                                 <div class="listheader">Returns:</div>
197                                 
198                                 <div class="value">Success</div>
199                                 <div class="description">The name of the Slot that was used.</div>
200
201                                 <div class="value">Failure</div>
202                                 <div class="description">An empty (NULL) result.</div>
203                         </div>
204
205                         <div class="section">
206                                 <div class="sectionhead">opensrf.persist.queue.pop( slot_name )</div>
207
208                                 Removes and returns the next value in a QUEUE type Slot.
209
210                                 <div class="listheader">Parameters:</div>
211
212                                 <div class="value">slot_name</div>
213                                 <div class="description">
214                                         The name of the Persistence Slot from which an object should be retrieved.
215                                 </div>
216
217
218                                 <div class="listheader">Returns:</div>
219                                 
220                                 <div class="value">Success</div>
221                                 <div class="description">
222                                         The next object on the QUEUE Slot, or an empty
223                                         (NULL) result if the Slot is empty.
224                                 </div>
225
226                                 <div class="value">Failure</div>
227                                 <div class="description">An empty (NULL) result.</div>
228                         </div>
229
230                         <div class="section">
231                                 <div class="sectionhead">opensrf.persist.queue.peek( slot_name )</div>
232
233                                 Returns the next value in a QUEUE type Slot <u>without</u> removing it.
234
235                                 <div class="listheader">Parameters:</div>
236
237                                 <div class="value">slot_name</div>
238                                 <div class="description">
239                                         The name of the Persistence Slot from which an object should be retrieved.
240                                 </div>
241
242
243                                 <div class="listheader">Returns:</div>
244                                 
245                                 <div class="value">Success</div>
246                                 <div class="description">
247                                         The next object on the QUEUE Slot, or an empty
248                                         (NULL) result if the Slot is empty.
249                                 </div>
250
251                                 <div class="value">Failure</div>
252                                 <div class="description">An empty (NULL) result.</div>
253                         </div>
254
255                         <div class="section">
256                                 <div class="sectionhead">opensrf.persist.queue.peek.all( slot_name )</div>
257
258                                 Returns all values in a QUEUE type Slot <u>without</u> removing them.
259
260                                 <div class="listheader">Parameters:</div>
261
262                                 <div class="value">slot_name</div>
263                                 <div class="description">
264                                         The name of the Persistence Slot from which the objects should be retrieved.
265                                 </div>
266
267
268                                 <div class="listheader">Returns:</div>
269                                 
270                                 <div class="value">Success</div>
271                                 <div class="description">
272                                         A stream of all objects on the QUEUE Slot, or an empty
273                                         (NULL) result if the Slot is empty.
274                                 </div>
275
276                                 <div class="value">Failure</div>
277                                 <div class="description">An empty (NULL) result.</div>
278                         </div>
279
280                         <div class="section">
281                                 <div class="sectionhead">opensrf.persist.queue.peek.all.atomic( slot_name )</div>
282
283                                 Returns all values in a QUEUE type Slot <u>without</u> removing them.
284
285                                 <div class="listheader">Parameters:</div>
286
287                                 <div class="value">slot_name</div>
288                                 <div class="description">
289                                         The name of the Persistence Slot from which the objects should be retrieved.
290                                 </div>
291
292
293                                 <div class="listheader">Returns:</div>
294                                 
295                                 <div class="value">Success</div>
296                                 <div class="description">
297                                         A single array of all objects on the QUEUE Slot, or an empty
298                                         array if the Slot is empty.
299                                 </div>
300
301                                 <div class="value">Failure</div>
302                                 <div class="description">An empty (NULL) result.</div>
303                         </div>
304
305                         <div class="section">
306                                 <div class="sectionhead">opensrf.persist.queue.length( slot_name )</div>
307
308                                 Returns the number of objects in the QUEUE type Slot.
309
310                                 <div class="listheader">Parameters:</div>
311
312                                 <div class="value">slot_name</div>
313                                 <div class="description">
314                                         The name of the Persistence Slot in question.
315                                 </div>
316
317
318                                 <div class="listheader">Returns:</div>
319                                 
320                                 <div class="value">Success</div>
321                                 <div class="description">The number of objects in the Persistence Slot.</div>
322
323                                 <div class="value">Failure</div>
324                                 <div class="description">An empty (NULL) result.</div>
325                         </div>
326
327                         <div class="section">
328                                 <div class="sectionhead">opensrf.persist.queue.size( slot_name )</div>
329
330                                 Returns the number bytes taken up by the JSON encoded version of
331                                 the objects in the QUEUE type Slot.
332
333                                 <div class="listheader">Parameters:</div>
334
335                                 <div class="value">slot_name</div>
336                                 <div class="description">
337                                         The name of the Persistence Slot in question.
338                                 </div>
339
340
341                                 <div class="listheader">Returns:</div>
342                                 
343                                 <div class="value">Success</div>
344                                 <div class="description">
345                                         The space, in bytes, used by the JSON encoded
346                                         objects in the Persistence Slot.
347                                 </div>
348
349                                 <div class="value">Failure</div>
350                                 <div class="description">An empty (NULL) result.</div>
351                         </div>
352
353                         <br>
354                         </li>
355
356                         <li> <h3>STACK style Slot methods</h3>
357
358                         Uses the Slot in FILO mode, pushing and pulling objects at the same end of a list.
359                         The STACK API-Namespace is useful for creating a global Application context stack.
360
361                         <br><br>
362
363                         <div class="section">
364                                 <div class="sectionhead">opensrf.persist.stack.push( slot_name, object )</div>
365
366                                 Adds an object to a Slot in FILO order.
367
368                                 <div class="listheader">Parameters:</div>
369
370                                 <div class="value">slot_name</div>
371                                 <div class="description">The name of the Persistence Slot to use for storing the object.</div>
372
373                                 <div class="value">object</div>
374                                 <div class="description">The object that should be pushed onto the front of the STACK.</div>
375
376
377                                 <div class="listheader">Returns:</div>
378                                 
379                                 <div class="value">Success</div>
380                                 <div class="description">The name of the Slot that was used.</div>
381
382                                 <div class="value">Failure</div>
383                                 <div class="description">An empty (NULL) result.</div>
384                         </div>
385
386                         <div class="section">
387                                 <div class="sectionhead">opensrf.persist.stack.pop( slot_name )</div>
388
389                                 Removes and returns the next value in a STACK type Slot.
390
391                                 <div class="listheader">Parameters:</div>
392
393                                 <div class="value">slot_name</div>
394                                 <div class="description">
395                                         The name of the Persistence Slot from which an object should be retrieved.
396                                 </div>
397
398
399                                 <div class="listheader">Returns:</div>
400                                 
401                                 <div class="value">Success</div>
402                                 <div class="description">
403                                         The next object on the STACK Slot, or an empty
404                                         (NULL) result if the Slot is empty.
405                                 </div>
406
407                                 <div class="value">Failure</div>
408                                 <div class="description">An empty (NULL) result.</div>
409                         </div>
410
411                         <div class="section">
412                                 <div class="sectionhead">opensrf.persist.stack.peek( slot_name )</div>
413
414                                 Returns the next value in a STACK type Slot <u>without</u> removing it.
415
416                                 <div class="listheader">Parameters:</div>
417
418                                 <div class="value">slot_name</div>
419                                 <div class="description">
420                                         The name of the Persistence Slot from which an object should be retrieved.
421                                 </div>
422
423
424                                 <div class="listheader">Returns:</div>
425                                 
426                                 <div class="value">Success</div>
427                                 <div class="description">
428                                         The next object on the STACK Slot, or an empty
429                                         (NULL) result if the Slot is empty.
430                                 </div>
431
432                                 <div class="value">Failure</div>
433                                 <div class="description">An empty (NULL) result.</div>
434                         </div>
435
436                         <div class="section">
437                                 <div class="sectionhead">opensrf.persist.stack.peek.all( slot_name )</div>
438
439                                 Returns all values in a STACK type Slot <u>without</u> removing them.
440
441                                 <div class="listheader">Parameters:</div>
442
443                                 <div class="value">slot_name</div>
444                                 <div class="description">
445                                         The name of the Persistence Slot from which the objects should be retrieved.
446                                 </div>
447
448
449                                 <div class="listheader">Returns:</div>
450                                 
451                                 <div class="value">Success</div>
452                                 <div class="description">
453                                         A stream of all objects on the STACK Slot, or an empty
454                                         (NULL) result if the Slot is empty.
455                                 </div>
456
457                                 <div class="value">Failure</div>
458                                 <div class="description">An empty (NULL) result.</div>
459                         </div>
460
461                         <div class="section">
462                                 <div class="sectionhead">opensrf.persist.stack.peek.all.atomic( slot_name )</div>
463
464                                 Returns all values in a STACK type Slot <u>without</u> removing them.
465
466                                 <div class="listheader">Parameters:</div>
467
468                                 <div class="value">slot_name</div>
469                                 <div class="description">
470                                         The name of the Persistence Slot from which the objects should be retrieved.
471                                 </div>
472
473
474                                 <div class="listheader">Returns:</div>
475                                 
476                                 <div class="value">Success</div>
477                                 <div class="description">
478                                         A single array of all objects on the STACK Slot, or an empty
479                                         array if the Slot is empty.
480                                 </div>
481
482                                 <div class="value">Failure</div>
483                                 <div class="description">An empty (NULL) result.</div>
484                         </div>
485
486                         <div class="section">
487                                 <div class="sectionhead">opensrf.persist.stack.depth( slot_name )</div>
488
489                                 Returns the number of objects in the STACK type Slot.
490
491                                 <div class="listheader">Parameters:</div>
492
493                                 <div class="value">slot_name</div>
494                                 <div class="description">
495                                         The name of the Persistence Slot in question.
496                                 </div>
497
498
499                                 <div class="listheader">Returns:</div>
500                                 
501                                 <div class="value">Success</div>
502                                 <div class="description">The number of objects in the Persistence Slot.</div>
503
504                                 <div class="value">Failure</div>
505                                 <div class="description">An empty (NULL) result.</div>
506                         </div>
507
508                         <div class="section">
509                                 <div class="sectionhead">opensrf.persist.stack.size( slot_name )</div>
510
511                                 Returns the number bytes taken up by the JSON encoded version of
512                                 the objects in the STACK type Slot.
513
514                                 <div class="listheader">Parameters:</div>
515
516                                 <div class="value">slot_name</div>
517                                 <div class="description">
518                                         The name of the Persistence Slot in question.
519                                 </div>
520
521
522                                 <div class="listheader">Returns:</div>
523                                 
524                                 <div class="value">Success</div>
525                                 <div class="description">
526                                         The space, in bytes, used by the JSON encoded
527                                         objects in the Persistence Slot.
528                                 </div>
529
530                                 <div class="value">Failure</div>
531                                 <div class="description">An empty (NULL) result.</div>
532                         </div>
533
534                         <br>
535                         </li>
536
537                         <li> <h3>OBJECT style Slot methods</h3>
538
539                         Uses the Slot in Single Object mode, storing a single object in the Slot.
540
541                         <br><br>
542
543                         The OBJECT API-Namespace is useful for globally caching unique objects.
544
545                         <br><br>
546
547                         <div class="section">
548                                 <div class="sectionhead">opensrf.persist.object.set( slot_name, object )</div>
549
550                                 Sets the value of a Slot.  If the Slot has been used in STACK or QUEUE
551                                 mode and <b>opensrf.persist.object.set</b> is called then all objects currently
552                                 in the Slot will be lost.
553
554                                 <div class="listheader">Parameters:</div>
555
556                                 <div class="value">slot_name</div>
557                                 <div class="description">The name of the Persistence Slot to use for storing the object.</div>
558
559                                 <div class="value">object</div>
560                                 <div class="description">The object that should be set as the one object in the Slot.</div>
561
562
563                                 <div class="listheader">Returns:</div>
564                                 
565                                 <div class="value">Success</div>
566                                 <div class="description">The name of the Slot that was used.</div>
567
568                                 <div class="value">Failure</div>
569                                 <div class="description">An empty (NULL) result.</div>
570                         </div>
571
572                         <div class="section">
573                                 <div class="sectionhead">opensrf.persist.object.get( slot_name )</div>
574
575                                 Removes and returns the value in an OBJECT type Slot.
576
577                                 <div class="listheader">Parameters:</div>
578
579                                 <div class="value">slot_name</div>
580                                 <div class="description">
581                                         The name of the Persistence Slot from which the object should be retrieved.
582                                 </div>
583
584
585                                 <div class="listheader">Returns:</div>
586                                 
587                                 <div class="value">Success</div>
588                                 <div class="description">
589                                         The object in the OBJECT Slot, or an empty
590                                         (NULL) result if the Slot is empty.
591                                 </div>
592
593                                 <div class="value">Failure</div>
594                                 <div class="description">An empty (NULL) result.</div>
595                         </div>
596
597                         <div class="section">
598                                 <div class="sectionhead">opensrf.persist.object.peek( slot_name )</div>
599
600                                 Returns the value in an OBJECT type Slot <u>without</u> removing it.
601
602                                 <div class="listheader">Parameters:</div>
603
604                                 <div class="value">slot_name</div>
605                                 <div class="description">
606                                         The name of the Persistence Slot from which the object should be retrieved.
607                                 </div>
608
609
610                                 <div class="listheader">Returns:</div>
611                                 
612                                 <div class="value">Success</div>
613                                 <div class="description">
614                                         The object on the OBJECT Slot, or an empty
615                                         (NULL) result if the Slot is empty.
616                                 </div>
617
618                                 <div class="value">Failure</div>
619                                 <div class="description">An empty (NULL) result.</div>
620                         </div>
621
622                         <div class="section">
623                                 <div class="sectionhead">opensrf.persist.object.size( slot_name )</div>
624
625                                 Returns the number bytes taken up by the JSON encoded version of
626                                 the object in the OBJECT type Slot.
627
628                                 <div class="listheader">Parameters:</div>
629
630                                 <div class="value">slot_name</div>
631                                 <div class="description">
632                                         The name of the Persistence Slot in question.
633                                 </div>
634
635
636                                 <div class="listheader">Returns:</div>
637                                 
638                                 <div class="value">Success</div>
639                                 <div class="description">
640                                         The space, in bytes, used by the JSON encoded
641                                         object in the Persistence Slot.
642                                 </div>
643
644                                 <div class="value">Failure</div>
645                                 <div class="description">An empty (NULL) result.</div>
646                         </div>
647
648                         </li>
649                 </ul>
650         </body>
651 </html>