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>