3 <title>OpenSRF Persistance Application API-Namespace</title>
6 * { font-family: sans-serif;
10 .sectionhead { border: solid black 1px;
11 background-color: #333333;
19 .section { border: solid black 1px;
20 background-color: lightgray;
27 .listheader { font-weight: bold;
31 .value { font-style: italic;
36 .description { margin-top: 0px;
46 <h2>OpenSRF Persistance Application API-Namespace</h2>
50 <div style="margin: 30px;">
51 The Persistance 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.
57 <li> <h3>General Persistance Slot methods</h3>
59 Methods used to create, set up and destroy slots.
63 <div class="sectionhead">opensrf.persist.slot.create( slot_name )</div>
65 Creates a Persistance Slot.
67 <div class="listheader">Parameters:</div>
68 <div class="value">slot_name (optional)</div>
69 <div class="description">
70 The name of the Persistance 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.
76 <div class="listheader">Returns:</div>
78 <div class="value">Success</div>
79 <div class="description">The name of the Slot that was created.</div>
81 <div class="value">Failure</div>
82 <div class="description">An empty (NULL) result.</div>
86 <div class="sectionhead">opensrf.persist.slot.create_expirable( slot_name, expire_interval )</div>
88 Creates a Persistance Slot that is automatically destroyed after the specified interval.
90 <div class="listheader">Parameters:</div>
91 <div class="value">slot_name</div>
92 <div class="description">The name of the Persistance 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:
100 <li> 1 day, 2 hours and 35 minutes </li>
106 A setting of 0 (zero) disables automatic expiration for a Slot.
110 <div class="listheader">Returns:</div>
112 <div class="value">Success</div>
113 <div class="description">The name of the Slot that was created.</div>
115 <div class="value">Failure</div>
116 <div class="description">An empty (NULL) result.</div>
119 <div class="section">
120 <div class="sectionhead">opensrf.persist.slot.set_expire( slot_name, expire_interval )</div>
122 Sets or disables the expiration interval on an existing Persistance Slot.
124 <div class="listheader">Parameters:</div>
125 <div class="value">slot_name</div>
126 <div class="description">The name of the Persistance 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:
134 <li> 1 day, 2 hours and 35 minutes </li>
140 A setting of 0 (zero) disables automatic expiration for a Slot.
144 <div class="listheader">Returns:</div>
146 <div class="value">Success</div>
147 <div class="description">The number of seconds the requested interval represents.</div>
149 <div class="value">Failure</div>
150 <div class="description">An empty (NULL) result.</div>
153 <div class="section">
154 <div class="sectionhead">opensrf.persist.slot.destroy( slot_name )</div>
156 Destroys a Persistance Slot.
158 <div class="listheader">Parameters:</div>
159 <div class="value">slot_name</div>
160 <div class="description">The name of the Persistance Slot to destroy.</div>
163 <div class="listheader">Returns:</div>
165 <div class="value">Success</div>
166 <div class="description">The name of the Slot that was destroyed.</div>
168 <div class="value">Failure</div>
169 <div class="description">An empty (NULL) result.</div>
175 <li> <h3>QUEUE API-Namespace Slot methods</h3>
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.
182 <div class="section">
183 <div class="sectionhead">opensrf.persist.queue.push( slot_name, object )</div>
185 Adds an object to a Slot in FIFO order.
187 <div class="listheader">Parameters:</div>
189 <div class="value">slot_name</div>
190 <div class="description">The name of the Persistance Slot to use for storing the object.</div>
192 <div class="value">object</div>
193 <div class="description">The object that should be pushed onto the front of the QUEUE.</div>
196 <div class="listheader">Returns:</div>
198 <div class="value">Success</div>
199 <div class="description">The name of the Slot that was used.</div>
201 <div class="value">Failure</div>
202 <div class="description">An empty (NULL) result.</div>
205 <div class="section">
206 <div class="sectionhead">opensrf.persist.queue.pop( slot_name )</div>
208 Removes and returns the next value in a QUEUE type Slot.
210 <div class="listheader">Parameters:</div>
212 <div class="value">slot_name</div>
213 <div class="description">
214 The name of the Persistance Slot from which an object should be retrieved.
218 <div class="listheader">Returns:</div>
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.
226 <div class="value">Failure</div>
227 <div class="description">An empty (NULL) result.</div>
230 <div class="section">
231 <div class="sectionhead">opensrf.persist.queue.peek( slot_name )</div>
233 Returns the next value in a QUEUE type Slot <u>without</u> removing it.
235 <div class="listheader">Parameters:</div>
237 <div class="value">slot_name</div>
238 <div class="description">
239 The name of the Persistance Slot from which an object should be retrieved.
243 <div class="listheader">Returns:</div>
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.
251 <div class="value">Failure</div>
252 <div class="description">An empty (NULL) result.</div>
255 <div class="section">
256 <div class="sectionhead">opensrf.persist.queue.peek.all( slot_name )</div>
258 Returns all values in a QUEUE type Slot <u>without</u> removing them.
260 <div class="listheader">Parameters:</div>
262 <div class="value">slot_name</div>
263 <div class="description">
264 The name of the Persistance Slot from which the objects should be retrieved.
268 <div class="listheader">Returns:</div>
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.
276 <div class="value">Failure</div>
277 <div class="description">An empty (NULL) result.</div>
280 <div class="section">
281 <div class="sectionhead">opensrf.persist.queue.peek.all.atomic( slot_name )</div>
283 Returns all values in a QUEUE type Slot <u>without</u> removing them.
285 <div class="listheader">Parameters:</div>
287 <div class="value">slot_name</div>
288 <div class="description">
289 The name of the Persistance Slot from which the objects should be retrieved.
293 <div class="listheader">Returns:</div>
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.
301 <div class="value">Failure</div>
302 <div class="description">An empty (NULL) result.</div>
305 <div class="section">
306 <div class="sectionhead">opensrf.persist.queue.length( slot_name )</div>
308 Returns the number of objects in the QUEUE type Slot.
310 <div class="listheader">Parameters:</div>
312 <div class="value">slot_name</div>
313 <div class="description">
314 The name of the Persistance Slot in question.
318 <div class="listheader">Returns:</div>
320 <div class="value">Success</div>
321 <div class="description">The number of objects in the Persistance Slot.</div>
323 <div class="value">Failure</div>
324 <div class="description">An empty (NULL) result.</div>
327 <div class="section">
328 <div class="sectionhead">opensrf.persist.queue.size( slot_name )</div>
330 Returns the number bytes taken up by the JSON encoded version of
331 the objects in the QUEUE type Slot.
333 <div class="listheader">Parameters:</div>
335 <div class="value">slot_name</div>
336 <div class="description">
337 The name of the Persistance Slot in question.
341 <div class="listheader">Returns:</div>
343 <div class="value">Success</div>
344 <div class="description">
345 The space, in bytes, used by the JSON encoded
346 objects in the Persistance Slot.
349 <div class="value">Failure</div>
350 <div class="description">An empty (NULL) result.</div>
356 <li> <h3>STACK style Slot methods</h3>
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.
363 <div class="section">
364 <div class="sectionhead">opensrf.persist.stack.push( slot_name, object )</div>
366 Adds an object to a Slot in FILO order.
368 <div class="listheader">Parameters:</div>
370 <div class="value">slot_name</div>
371 <div class="description">The name of the Persistance Slot to use for storing the object.</div>
373 <div class="value">object</div>
374 <div class="description">The object that should be pushed onto the front of the STACK.</div>
377 <div class="listheader">Returns:</div>
379 <div class="value">Success</div>
380 <div class="description">The name of the Slot that was used.</div>
382 <div class="value">Failure</div>
383 <div class="description">An empty (NULL) result.</div>
386 <div class="section">
387 <div class="sectionhead">opensrf.persist.stack.pop( slot_name )</div>
389 Removes and returns the next value in a STACK type Slot.
391 <div class="listheader">Parameters:</div>
393 <div class="value">slot_name</div>
394 <div class="description">
395 The name of the Persistance Slot from which an object should be retrieved.
399 <div class="listheader">Returns:</div>
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.
407 <div class="value">Failure</div>
408 <div class="description">An empty (NULL) result.</div>
411 <div class="section">
412 <div class="sectionhead">opensrf.persist.stack.peek( slot_name )</div>
414 Returns the next value in a STACK type Slot <u>without</u> removing it.
416 <div class="listheader">Parameters:</div>
418 <div class="value">slot_name</div>
419 <div class="description">
420 The name of the Persistance Slot from which an object should be retrieved.
424 <div class="listheader">Returns:</div>
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.
432 <div class="value">Failure</div>
433 <div class="description">An empty (NULL) result.</div>
436 <div class="section">
437 <div class="sectionhead">opensrf.persist.stack.peek.all( slot_name )</div>
439 Returns all values in a STACK type Slot <u>without</u> removing them.
441 <div class="listheader">Parameters:</div>
443 <div class="value">slot_name</div>
444 <div class="description">
445 The name of the Persistance Slot from which the objects should be retrieved.
449 <div class="listheader">Returns:</div>
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.
457 <div class="value">Failure</div>
458 <div class="description">An empty (NULL) result.</div>
461 <div class="section">
462 <div class="sectionhead">opensrf.persist.stack.peek.all.atomic( slot_name )</div>
464 Returns all values in a STACK type Slot <u>without</u> removing them.
466 <div class="listheader">Parameters:</div>
468 <div class="value">slot_name</div>
469 <div class="description">
470 The name of the Persistance Slot from which the objects should be retrieved.
474 <div class="listheader">Returns:</div>
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.
482 <div class="value">Failure</div>
483 <div class="description">An empty (NULL) result.</div>
486 <div class="section">
487 <div class="sectionhead">opensrf.persist.stack.depth( slot_name )</div>
489 Returns the number of objects in the STACK type Slot.
491 <div class="listheader">Parameters:</div>
493 <div class="value">slot_name</div>
494 <div class="description">
495 The name of the Persistance Slot in question.
499 <div class="listheader">Returns:</div>
501 <div class="value">Success</div>
502 <div class="description">The number of objects in the Persistance Slot.</div>
504 <div class="value">Failure</div>
505 <div class="description">An empty (NULL) result.</div>
508 <div class="section">
509 <div class="sectionhead">opensrf.persist.stack.size( slot_name )</div>
511 Returns the number bytes taken up by the JSON encoded version of
512 the objects in the STACK type Slot.
514 <div class="listheader">Parameters:</div>
516 <div class="value">slot_name</div>
517 <div class="description">
518 The name of the Persistance Slot in question.
522 <div class="listheader">Returns:</div>
524 <div class="value">Success</div>
525 <div class="description">
526 The space, in bytes, used by the JSON encoded
527 objects in the Persistance Slot.
530 <div class="value">Failure</div>
531 <div class="description">An empty (NULL) result.</div>
537 <li> <h3>OBJECT style Slot methods</h3>
539 Uses the Slot in Single Object mode, storing a single object in the Slot.
543 The OBJECT API-Namespace is useful for globally caching unique objects.
547 <div class="section">
548 <div class="sectionhead">opensrf.persist.object.set( slot_name, object )</div>
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.
554 <div class="listheader">Parameters:</div>
556 <div class="value">slot_name</div>
557 <div class="description">The name of the Persistance Slot to use for storing the object.</div>
559 <div class="value">object</div>
560 <div class="description">The object that should be set as the one object in the Slot.</div>
563 <div class="listheader">Returns:</div>
565 <div class="value">Success</div>
566 <div class="description">The name of the Slot that was used.</div>
568 <div class="value">Failure</div>
569 <div class="description">An empty (NULL) result.</div>
572 <div class="section">
573 <div class="sectionhead">opensrf.persist.object.get( slot_name )</div>
575 Removes and returns the value in an OBJECT type Slot.
577 <div class="listheader">Parameters:</div>
579 <div class="value">slot_name</div>
580 <div class="description">
581 The name of the Persistance Slot from which the object should be retrieved.
585 <div class="listheader">Returns:</div>
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.
593 <div class="value">Failure</div>
594 <div class="description">An empty (NULL) result.</div>
597 <div class="section">
598 <div class="sectionhead">opensrf.persist.object.peek( slot_name )</div>
600 Returns the value in an OBJECT type Slot <u>without</u> removing it.
602 <div class="listheader">Parameters:</div>
604 <div class="value">slot_name</div>
605 <div class="description">
606 The name of the Persistance Slot from which the object should be retrieved.
610 <div class="listheader">Returns:</div>
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.
618 <div class="value">Failure</div>
619 <div class="description">An empty (NULL) result.</div>
622 <div class="section">
623 <div class="sectionhead">opensrf.persist.object.size( slot_name )</div>
625 Returns the number bytes taken up by the JSON encoded version of
626 the object in the OBJECT type Slot.
628 <div class="listheader">Parameters:</div>
630 <div class="value">slot_name</div>
631 <div class="description">
632 The name of the Persistance Slot in question.
636 <div class="listheader">Returns:</div>
638 <div class="value">Success</div>
639 <div class="description">
640 The space, in bytes, used by the JSON encoded
641 object in the Persistance Slot.
644 <div class="value">Failure</div>
645 <div class="description">An empty (NULL) result.</div>