OpenSRF Persistance Application API-Namespace

Date: Sun, 27 Feb 2005 03:08:05 +0000 Subject: [PATCH] API Documentation for the Persistance Application git-svn-id: svn://svn.open-ils.org/OpenSRF/trunk@119 9efc2488-bf62-4759-914b-345cdb29e865 --- doc/Persist-API.html | 651 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 651 insertions(+) create mode 100644 doc/Persist-API.html diff --git a/doc/Persist-API.html b/doc/Persist-API.html new file mode 100644 index 0000000..29eef38 --- /dev/null +++ b/doc/Persist-API.html @@ -0,0 +1,651 @@ + + + OpenSRF Persistance Application API-Namespace + + + + + +

OpenSRF Persistance Application API-Namespace

+ + +

+ The Persistance Application provides other OpenSRF Applications with a standard API for + sharing and caching data. These data are stored in Slots, and there are three basic + interfaces for interacting with Slots: QUEUEs, STACKs and OBJECTs. +

+ +

General Persistance Slot methods
+ + Methods used to create, set up and destroy slots. +

+ +
+
opensrf.persist.slot.create( slot_name )
+ + Creates a Persistance Slot. + +
Parameters:
+
slot_name (optional)
+
+ The name of the Persistance Slot to create. If a name is not specified + then the Slot is given a generic, unique name. Automatically named Slots + are destroyed as soon as they are empty. +
+ + +
Returns:
+ +
Success
+
The name of the Slot that was created.
+ +
Failure
+
An empty (NULL) result.
+
+ +
+
opensrf.persist.slot.create_expirable( slot_name, expire_interval )
+ + Creates a Persistance Slot that is automatically destroyed after the specified interval. + +
Parameters:
+
slot_name
+
The name of the Persistance Slot to create.
+
expire_interval
+
+ An interval describing how long to wait after an access has + occured on the Slot before automatically destroying it. The interval + can be specified using a fairly complex, human readable format, or as + a number of seconds. For example: +
- 1 day, 2 hours and 35 minutes
- +2h
- 1 week
- 300
+ + A setting of 0 (zero) disables automatic expiration for a Slot. +
+ + +
Returns:
+ +
Success
+
The name of the Slot that was created.
+ +
Failure
+
An empty (NULL) result.
+
+ +
+
opensrf.persist.slot.set_expire( slot_name, expire_interval )
+ + Sets or disables the expiration interval on an existing Persistance Slot. + +
Parameters:
+
slot_name
+
The name of the Persistance Slot to update.
+
expire_interval
+
+ An interval describing how long to wait after an access has + occured on the Slot before automatically destroying it. The interval + can be specified using a fairly complex, human readable format, or as + a number of seconds. For example: +
- 1 day, 2 hours and 35 minutes
- +2h
- 1 week
- 300
+ + A setting of 0 (zero) disables automatic expiration for a Slot. +
+ + +
Returns:
+ +
Success
+
The number of seconds the requested interval represents.
+ +
Failure
+
An empty (NULL) result.
+
+ +
+
opensrf.persist.slot.destroy( slot_name )
+ + Destroys a Persistance Slot. + +
Parameters:
+
slot_name
+
The name of the Persistance Slot to destroy.
+ + +
Returns:
+ +
Success
+
The name of the Slot that was destroyed.
+ +
Failure
+
An empty (NULL) result.
+
+ +
+
QUEUE API-Namespace Slot methods
+ + Uses the Slot in FIFO mode, pushing values onto one end an pulling them off the other. + The QUEUE API-Namespace is useful for creating an ordered message passing access point. + +

+ +
+
opensrf.persist.queue.push( slot_name, object )
+ + Adds an object to a Slot in FIFO order. + +
Parameters:
+ +
slot_name
+
The name of the Persistance Slot to use for storing the object.
+ +
object
+
The object that should be pushed onto the front of the QUEUE.
+ + +
Returns:
+ +
Success
+
The name of the Slot that was used.
+ +
Failure
+
An empty (NULL) result.
+
+ +
+
opensrf.persist.queue.pop( slot_name )
+ + Removes and returns the next value in a QUEUE type Slot. + +
Parameters:
+ +
slot_name
+
+ The name of the Persistance Slot from which an object should be retrieved. +
+ + +
Returns:
+ +
Success
+
+ The next object on the QUEUE Slot, or an empty + (NULL) result if the Slot is empty. +
+ +
Failure
+
An empty (NULL) result.
+
+ +
+
opensrf.persist.queue.peek( slot_name )
+ + Returns the next value in a QUEUE type Slot without removing it. + +
Parameters:
+ +
slot_name
+
+ The name of the Persistance Slot from which an object should be retrieved. +
+ + +
Returns:
+ +
Success
+
+ The next object on the QUEUE Slot, or an empty + (NULL) result if the Slot is empty. +
+ +
Failure
+
An empty (NULL) result.
+
+ +
+
opensrf.persist.queue.peek.all( slot_name )
+ + Returns all values in a QUEUE type Slot without removing them. + +
Parameters:
+ +
slot_name
+
+ The name of the Persistance Slot from which the objects should be retrieved. +
+ + +
Returns:
+ +
Success
+
+ A stream of all objects on the QUEUE Slot, or an empty + (NULL) result if the Slot is empty. +
+ +
Failure
+
An empty (NULL) result.
+
+ +
+
opensrf.persist.queue.peek.all.atomic( slot_name )
+ + Returns all values in a QUEUE type Slot without removing them. + +
Parameters:
+ +
slot_name
+
+ The name of the Persistance Slot from which the objects should be retrieved. +
+ + +
Returns:
+ +
Success
+
+ A single array of all objects on the QUEUE Slot, or an empty + array if the Slot is empty. +
+ +
Failure
+
An empty (NULL) result.
+
+ +
+
opensrf.persist.queue.length( slot_name )
+ + Returns the number of objects in the QUEUE type Slot. + +
Parameters:
+ +
slot_name
+
+ The name of the Persistance Slot in question. +
+ + +
Returns:
+ +
Success
+
The number of objects in the Persistance Slot.
+ +
Failure
+
An empty (NULL) result.
+
+ +
+
opensrf.persist.queue.size( slot_name )
+ + Returns the number bytes taken up by the JSON encoded version of + the objects in the QUEUE type Slot. + +
Parameters:
+ +
slot_name
+
+ The name of the Persistance Slot in question. +
+ + +
Returns:
+ +
Success
+
+ The space, in bytes, used by the JSON encoded + objects in the Persistance Slot. +
+ +
Failure
+
An empty (NULL) result.
+
+ +
+
STACK style Slot methods
+ + Uses the Slot in FILO mode, pushing and pulling objects at the same end of a list. + The STACK API-Namespace is useful for creating a global Application context stack. + +

+ +
+
opensrf.persist.stack.push( slot_name, object )
+ + Adds an object to a Slot in FILO order. + +
Parameters:
+ +
slot_name
+
The name of the Persistance Slot to use for storing the object.
+ +
object
+
The object that should be pushed onto the front of the STACK.
+ + +
Returns:
+ +
Success
+
The name of the Slot that was used.
+ +
Failure
+
An empty (NULL) result.
+
+ +
+
opensrf.persist.stack.pop( slot_name )
+ + Removes and returns the next value in a STACK type Slot. + +
Parameters:
+ +
slot_name
+
+ The name of the Persistance Slot from which an object should be retrieved. +
+ + +
Returns:
+ +
Success
+
+ The next object on the STACK Slot, or an empty + (NULL) result if the Slot is empty. +
+ +
Failure
+
An empty (NULL) result.
+
+ +
+
opensrf.persist.stack.peek( slot_name )
+ + Returns the next value in a STACK type Slot without removing it. + +
Parameters:
+ +
slot_name
+
+ The name of the Persistance Slot from which an object should be retrieved. +
+ + +
Returns:
+ +
Success
+
+ The next object on the STACK Slot, or an empty + (NULL) result if the Slot is empty. +
+ +
Failure
+
An empty (NULL) result.
+
+ +
+
opensrf.persist.stack.peek.all( slot_name )
+ + Returns all values in a STACK type Slot without removing them. + +
Parameters:
+ +
slot_name
+
+ The name of the Persistance Slot from which the objects should be retrieved. +
+ + +
Returns:
+ +
Success
+
+ A stream of all objects on the STACK Slot, or an empty + (NULL) result if the Slot is empty. +
+ +
Failure
+
An empty (NULL) result.
+
+ +
+
opensrf.persist.stack.peek.all.atomic( slot_name )
+ + Returns all values in a STACK type Slot without removing them. + +
Parameters:
+ +
slot_name
+
+ The name of the Persistance Slot from which the objects should be retrieved. +
+ + +
Returns:
+ +
Success
+
+ A single array of all objects on the STACK Slot, or an empty + array if the Slot is empty. +
+ +
Failure
+
An empty (NULL) result.
+
+ +
+
opensrf.persist.stack.depth( slot_name )
+ + Returns the number of objects in the STACK type Slot. + +
Parameters:
+ +
slot_name
+
+ The name of the Persistance Slot in question. +
+ + +
Returns:
+ +
Success
+
The number of objects in the Persistance Slot.
+ +
Failure
+
An empty (NULL) result.
+
+ +
+
opensrf.persist.stack.size( slot_name )
+ + Returns the number bytes taken up by the JSON encoded version of + the objects in the STACK type Slot. + +
Parameters:
+ +
slot_name
+
+ The name of the Persistance Slot in question. +
+ + +
Returns:
+ +
Success
+
+ The space, in bytes, used by the JSON encoded + objects in the Persistance Slot. +
+ +
Failure
+
An empty (NULL) result.
+
+ +
+
OBJECT style Slot methods
+ + Uses the Slot in Single Object mode, storing a single object in the Slot. + +

+ + The OBJECT API-Namespace is useful for globally caching unique objects. + +

+ +
+
opensrf.persist.object.set( slot_name, object )
+ + Sets the value of a Slot. If the Slot has been used in STACK or QUEUE + mode and opensrf.persist.object.set is called then all objects currently + in the Slot will be lost. + +
Parameters:
+ +
slot_name
+
The name of the Persistance Slot to use for storing the object.
+ +
object
+
The object that should be set as the one object in the Slot.
+ + +
Returns:
+ +
Success
+
The name of the Slot that was used.
+ +
Failure
+
An empty (NULL) result.
+
+ +
+
opensrf.persist.object.get( slot_name )
+ + Removes and returns the value in an OBJECT type Slot. + +
Parameters:
+ +
slot_name
+
+ The name of the Persistance Slot from which the object should be retrieved. +
+ + +
Returns:
+ +
Success
+
+ The object in the OBJECT Slot, or an empty + (NULL) result if the Slot is empty. +
+ +
Failure
+
An empty (NULL) result.
+
+ +
+
opensrf.persist.object.peek( slot_name )
+ + Returns the value in an OBJECT type Slot without removing it. + +
Parameters:
+ +
slot_name
+
+ The name of the Persistance Slot from which the object should be retrieved. +
+ + +
Returns:
+ +
Success
+
+ The object on the OBJECT Slot, or an empty + (NULL) result if the Slot is empty. +
+ +
Failure
+
An empty (NULL) result.
+
+ +
+
opensrf.persist.object.size( slot_name )
+ + Returns the number bytes taken up by the JSON encoded version of + the object in the OBJECT type Slot. + +
Parameters:
+ +
slot_name
+
+ The name of the Persistance Slot in question. +
+ + +
Returns:
+ +
Success
+
+ The space, in bytes, used by the JSON encoded + object in the Persistance Slot. +
+ +
Failure
+
An empty (NULL) result.
+
+ +

+ + -- 2.11.0

OpenSRF Persistance Application API-Namespace

General Persistance Slot methods

QUEUE API-Namespace Slot methods

STACK style Slot methods

OBJECT style Slot methods