| |
Methods defined here:
- __init__(self, backEnd=None)
- The constructor for class ObjectStore. It takes an instance of the
class BackEnd as an optional argument. You can store and retrieve
backend-compliant objects through the instance of this class. You can
also store objects which though not being backend compliant but
contains a unique attribute "id".
Parameters:
backEnd: Instance of class BackEnd. Default being None.
Raises:
ParamException: The parameter "backEnd" is not an instance of
class BackEnd.
- create(self, classObj, params)
- Factory method to create an instance of class "classObj" using
attributes "params" and store it in ObjectStore storage. The params
should not contain value for the attribute "id".
Parameters:
classObj: Class object whose instance is to be created and stored.
params: A tuple with parameters for the constructor of the class.
Returns: Newly created object of class "classObj".
Raises:
ParamException: The parameter "classObj" is not a class object
or the parameter "params" is not a tuple object.
ObjectException: Object creation failed in the constructor.
Note: This method may also raise exceptions generated by the
constructor of the class whose object is being created.
- destroy(self, object)
- Method to destroy all data related to supplied object. Once this method
is called with an object, the object is deleted from database as well
as from ObjectStore storage. The object being supplied must be either
created through create() method of ObjectStore or stored through its
store() method.
If a callback method is registered for concerned class for deletion of
its instances, it is called. Else the object is assumed to be backend
compliant and its method deleteSelf() is called.
Parameters:
object: A python object available under ObjectStore framework which
is to be destroyed.
Returns: None.
Raises:
ParamException: The parameter "object" is not of instance type.
- registerBackEnd(self, backEnd=None)
- Method to register an instance of BackEnd to ObjectStore framework.
Params:
backEnd: An instance of class BackEnd. If it is None, currently
registered BackEnd instance, if any is removed.
Returns: None.
Raises:
ParamException: Supplied parameter backEnd is not an instance of
class BackEnd.
- registerDeletionCallback(self, classObj, callback)
- Method to register a callback function for deletion of objects of class
classObj. The callback function should take only one parameter, i.e.
an instance of supplied class. Whenever method destroy is called with a
valid instance of this class, this function will be called. If no
deletion-function is registered for a particular class, the object's
instance method deleteSelf() will be called for its destruction.
This method is defined in class BackEnd from which the class of
classObj should be derived. By passing None as a callback function,
existing deletion-callback can be de-registered.
Params:
classObj: A class object for which the deletion-callback is to be
registered.
callback: A function object which takes only one parameter; an
instance of supplied class. Normally this function should carry
out all housekeeping tasks required before deletion of the
supplied object. One such task is to set a flag (instance
attribute) on this object, proclaiming it to be dead. Finally
it must call object.deleteSelf() if the object is compliant to
backend framework. If callback is None, existing deletion-
callback, if any, is de-registered.
Returns: None.
Raises:
ParamException: The parameter "classObj" is not a class object or
"callback" is not a function object.
- registerSearchCallback(self, classObj, callback)
- Method to register a callback function for searching objects of class
classObj. The function supplied should take a dictionary as its only
parameter. The callback function will be called from method search().
The parameter "searchParams" of this method will be supplied as it is
to the callback function. By passing None as callback function,
existing search-callback function can be de-registered.
Params:
classObj: A class object for which the search-callback is to be
registered.
callback: A function object which takes only one parameter; a
dictionary. It should normally contain the attribute-value pairs
for which the matching objects are to be retrieved. This
function should return a list of ids (instance attribute id) of
matching objects of supplied class. It should return empty list
if no match is found. If None is supplied as callback, existing
callback, if any is de-registered.
Returns: None.
Raises:
ParamException: The parameter "classObj" is not a class object or
"callback" is not a function object.
- retrieve(self, classObj, objId)
- Factory method to retrieve the instance of class "classObj" having
object-id "objId". The constructor of this class must be able to take
a single parameter object-id "objId" to construct the object. All
classes compliant to backend framework can do this.
Parameters:
classObj: Class object whose instance is to be retrieved.
objId: The object-id of the object being retrieved. It is generally
integer or long under backend framework. Other custom types are
also allowed.
Returns: An instance of the the class classObj with object-id objId.
Raises:
ParamException: The parameter "classObj" is not a class object.
or the parameter "objId" is empty.
Note: This method may also raise exceptions generated by the
constructor of the class whose object is being retrieved.
- search(self, classObj, searchParams, searchRaw=0)
- Method to search and retrieve a list of matching objects/object-id of
supplied class. If a callback function is registered for this class
through method registerSearchCallback(), that function will be called
with supplied parameter "searchParams". Else the class is assumed to be
backend compliant and method dbSearch() will be called. This
method is defined in class BackEnd from which the current object is
assumed to be derived. For this, an instance of BackEnd must be
registered with ObjectStore either during its construction or later
through method registerBackEnd().
Please note that in a multi threaded application (de)registration of
search callback for a class may not be visible to all the threads
immediately. For example assume that the search-callback function is
changed/de-registered in a thread at certain instance. Then it is
possible that other thread/threads may use the old function within a
very short period of time after this change has taken place. Same is
applicable during first time registration of search-callback.
Parameters:
classObj: Class object whose instances are to be retrieved based on
the search parameters "searchParams".
searchParams: A dictionary containing search criteria in the form of
attribute-value pairs.
searchRaw: A flag which if set to 1, will make the method to return
the object-ids of the matching objects. Default is unset i.e. 0;
which means fully constructed objects would be returned.
Returns: A list of matching instances of class classObj provided the
flag searchRaw is set. Otherwise a list of object-ids. If no matches
found, an empty list is returned.
Raises:
ParamException: The parameter "classObj" is not a class object or
the parameter searchParams is not a dictionary object.
NotExistsException: An instance of class BackEnd is not found to be
registered with ObjectStore and no search-callback is registered
for "classObj".
Note: This method may raise exceptions (if any) from the function
registered for search-callback or from the constructor of
classObj.
- store(self, object, paramOK=0)
- Method to store a "new" object in the storage of ObjectStore. The object
being stored should have unique value for its attribute "id". Also it
must not be present already in the storage of ObjectStore. It means you
must not store() back an object which was obtained by method retrieve().
Also a "new" object can not be stored in place of an existing one. This
method is useful for storing objects created independently outside the
ObjectStore framework and which are not present already in its storage.
Remember that ObjectStore uses weak references to the objects being
stored. It means if actual object looses all runtime references, it will
be dropped out of the ObjectStore's storage too. ObjectStore prevents
existence of two instances of the same class by providing a uniform
interface to construct all objects in an application. If you want some
sort of caching mechanism for the objects being constructed, you need
to implement it yourself in your application.
Parameters:
object: A python object with hashable attribute "id".
paramOK: A flag to indicate that supplied parameters are valid and
do not need checkings. It should not be set in function-call.
Its there for internal use. Just ignore it.
Returns: None.
Raises:
ParamException: The parameter "object" is not of instance type.
NotExistsException: Supplied object does not contain attribute "id".
ExistsException: Supplied object exists already in the storage.
Data and non-method functions defined here:
- _ObjectStore__be = None
- _ObjectStore__initialized = 0
- __doc__ = '\n A class to maintain consistency between p...ethods of this\n class are thread-safe.\n '
- __module__ = 'prangya.objstore'
|