| | |
- BackDB
- BackEnd
- DBConnection
- DBMap
class BackDB |
| |
Class to connect to a particular database backend and manage a pool of
database handles(connection objects).
|
| |
Methods defined here:
- _BackDB__connect = __connect(self)
- Private method to open a connection to the database server.
Parameters: None.
Returns: None.
Raises:
ConnectionException: Database connection failed.
LimitException: Maximum limit reached on connections.
- _BackDB__disconnect = __disconnect(self)
- Private method to pop one free database connection and close it.
Parameters: None.
Returns: None.
Raises:
LimitException: All db connections are in use.
Note: This method may raise database related errors too.
- __init__(self, dbId, dbURL)
- Constructor for the class BackDB. Does groundwork for managing pools
of database-handles and other relevant functionalities.
Parameters:
dbId: A unique string to identify a database backend.
dbURL: Database URL which should be of the form
rdb:dbmodule//username@password:dbhost.example.com:port/dbname
Raises:
ParamException: At least one supplied parameter is invalid.
ModuleException: Failed to load database driver module.
ConnectionException: Failed to connect to the database.
- closeFree(self, num=0)
- Method to close down free database connections. The number of
connections to be closed is supplied as an argument to this method.
If no parameter or 0 is given, all free database connections are closed
down. It returns the number of successful closure of connections. It is
not necessary that the value returned would match with the value
requested.
Parameters:
num = Number of free connections to be closed. Default is all.
Returns: The number of successful closures.
Raises:
ParamException: Supplied parameter is not a positive number.
- connect(self, id)
- A factory method to return an instance of class DBConnection
containing a database connection object. The id supplied, known
as connection-identifier is used to identify and track the connection
object.
Following steps are needed to use this framework:
1. Create BackDB instance and set various tuning parameters.
2. Call to connect() with an id and obtain a DBConnection object.
3. Use that object for various database related operations(SQL).
4. Close that DBConnection object by calling method close() of it.
5. Repeat step 2 to obtain a new DBConnection object.
6. Repeat steps 3 and 4 in that order.
In the case described above there is no guaranty that the underlying
database connection object wrapped up in the instance of DBConnection
on step 5 is the same as the one obtained in step 2. In short, it means
that you can't possess exclusive rights on a database connection for an
extended period of time by following the scheme described above.
But this method can also be used to reserve a particular database
connection exclusively for a series of operations in multiple batches.
For this, pass on the same id each time while calling method connect().
Besides that, do not call close() on any of the DBConnection object till
you want that connection to be exclusively available to you.
So the steps required are as follows:
1. Create BackDB instance and set various tuning parameters.
2. Call to connect() with an id and obtain a DBConnection object.
3. Use that object for various database related operations(SQL).
4. Call connect() with the same id and receive another DBConnection
object wrapping the same old database connection object.
5. Use this object for various database related operations(SQL).
6. Repeat steps 4 and 5 as many times as you want.
7. Call method close() on any one of the DBConnection object
obtained in above steps(2, 4 or subsequent ones).
This calling framework is helpful to use transaction facility of
underlying database. You can carry out commits and rollbacks over an
extended period of time in multiple function calls. In this case you
need not worry about the usage of the same connection by other threads
as long as supplied id is different. Though in a multi threaded
application if you supply same id in multiple threads, you must take
care to prevent simultaneous use of same database connection object by
concerned threads. In that case use re-entrant lock available in module
"threading".
Remember that if method close() is called on any one of the DBConnection
object with certain id, all objects created through the factory method
connect() with the same id is closed too.
Parameters:
id: A connection-identification string.
Returns: An instance of DBConnection object with wrapped-in database
connection object created by underlying database module.
Raises:
ParamException: Parameter id is not of string type.
ConnectionException: Database connection failed.
LimitException: The maximum limits on usage reached.
- disconnect(self, id)
- Method to release a database connection object from the exclusive
possession of some entity like DBConnection object. It should
not be called directly as far as possible. It is normally registered as
a callback function to an instance of DBConnection object which calls
it when its own close() method is invoked. Once this method is invoked
with a valid id, any instance of DBConnection object with that id,
created through the factory method connect() of BackDB instance, looses
its existence. None of them could be used further for any database
related activity. Direct call to this method from a program is only
advisable under some special cases where the normal usage is found to be
impractical.
Parameters:
id: A string specifying the id of the DBConnection objects to kill.
Returns: None.
Raises:
ParamException: No matching DBConnection object found for given id.
- getConMax(self)
- Retrieves the current limit on number of database connections.
Parameters: None
Returns: A positive number specifying the current limit on number of
database connections.
Raises: None
- getDBDriverName(self)
- Method to retrieve the name of the python database module name being
used by the instance of this class.
Parameters: None
Returns: A string containing the database driver name.
Raises: None
- getInfo(self)
- Method to retrieve status of internal data structures of this
instance. Generally this method is used for debugging only. It
should never be used to retrieve data for any other purpose as
there is no thread-locks in place during data-retrieval.
Parameters: None
Returns: String-representation of a dictionary containing name-value
pairs of public and private data of this class. Remember to not
to use this data for any purpose other than to debug this class
in a single threaded environment.
Raises: None
- getInitSQLs(self)
- Retrieves the list of initialization statements (in SQL) for database
connections.
Parameters: None
Returns: A list containing the sql statements.
Raises: None
- setConMax(self, maxLimit)
- Allows to set a maximum limit on number of database connections. If the
new limit is greater than the existing one, it will be set successfully
and the new limit is returned to the caller. If the new limit is less
than the existing one, this method may or may not set it successfully
depending on the current usage of database connections. In such cases
the limit is reduced as much as possible till the requested value is
reached and the new value is returned to the caller.
Parameters:
maxLimit: Maximum limit on number of database connections.
Returns: The new maximum limit on database connections set by this
method. It may or may not match with the requested limit.
Raises:
ParamException: Parameter maxLimit is a non-integer or it is
negative or zero.
- setInitSQLs(self, sqlList)
- Allows to set initialization statements(in SQL) for all new database
connections.
Parameters:
sqlList: A list containing the sql statements which are to be
executed once the database connection is made.
Returns: None
Raises:
ParamException: Parameter sqlList is not a list object.
Data and non-method functions defined here:
- __doc__ = '\n Class to connect to a particular database...n database handles(connection objects).\n '
- __module__ = 'backend'
|
class BackEnd |
| |
A class to handle creation of objects from an RDBMS backend. It also
handles updating the same backend, whenever changes are made to the
attributes of the objects created by it.
All user defined classes must inherit from this class to use the
backend framework. Any class which is not inherited from this class
can interact with the underlying database directly but must not make
any changes in the tables used by this framework. In short, you must
not write directly on any table which is used in the configuration
(DBMap object) as this may cause data inconsistency between the
database and the objects currently under use.
For thread-safe operations you should avoid changing attributes of
underlying DBMap object after initializing it through a configuration
file. Also ensure thread-safety of all sub-class based objects by
implementing proper object locking mechanisms.
|
| |
Methods defined here:
- _BackEnd__buildQuery_delete = __buildQuery_delete(self, className)
- Private method to build DELETE queries required to remove an existing
object of given class from the database backend.
Parameters:
className: The name of the class whose instance is to be deleted.
Returns: A list containing SQL queries.
Raises: None.
- _BackEnd__buildQuery_insert = __buildQuery_insert(self, className, tabDetails)
- Private method to build INSERT queries required to insert the
attributes of an object into the backend table. The details of
the tables and columns are passed on as a parameter along with
the name of the class whose attributes are being inserted.
Parameters:
className: The name of the class for which the attributes are being
inserted.
tabDetails: A dictionary of dictionaries. The keys of the first one
are the names of the tables. The second dictionary contains the
column-names of the table as keys and corresponding attribute-
names of the objects as values. The structure is as follows:
{table1:{col11:attr11, col21:attr21, ...}, table2:{col12:attr12,
col22:attr22, ...}, ...}
Returns: A list of SQL queries built for the table details provided.
Raises: None
- _BackEnd__buildQuery_select = __buildQuery_select(self, className, tabDetails)
- Private method to build SELECT queries required to search a table for
ids of an object based on a set of attributes. The details of the
tables and columns are passed on as a parameter along with the name of
the class whose ids are being searched.
Parameters:
className: The name of the class whose ids are being selected.
tabDetails: A dictionary of dictionaries. The keys of the first one
are the names of the tables. The second dictionary contains the
column-names of the table as keys and corresponding attribute-
names of the objects as values. The structure is as follows:
{table1:{col11:attr11, col21:attr21, ...}, table2:{col12:attr12,
col22:attr22, ...}, ...}
Returns: A string containing SQL select query built for the table
details provided.
Raises: None.
- _BackEnd__buildQuery_update = __buildQuery_update(self, className, tabDetails, attrDict)
- Private method to build UPDATE queries required to update the attributes
of an object. The details of the tables and columns are passed on as a
parameter along with the name of the class whose attributes are being
updated. Also the dictionary containing all (existing as well as to be
updated) attributes are passed too.
Parameters:
className: The name of the class whose attributes are being updated.
tabDetails: A dictionary of dictionaries. The keys of the first one
are the names of the tables. The second dictionary contains the
column-names of the table as keys and corresponding attribute-
names of the objects as values. The structure is as follows:
{table1:{col11:attr11, col21:attr21, ...}, table2:{col12:attr12,
col22:attr22, ...}, ...}
attrDict: A dictionary containing attribute-names as key and their
respective values as value.
Returns: A list of SQL queries built for the table details provided.
Raises:
ConfigException: No where clause found in update query due to
logical error in configuration.
- _BackEnd__checkConfig = __checkConfig(self, dbMap)
- Private method to test the consistency of parameters supplied through
the instance of class DBMap. Following constraints are expected on any
configuration supplied:
1. A database identification string must be present for each class whose
definition is provided in the DBMap object.
2. A non-empty DBURL must be mapped for each database identification
string which has a mapping with any class defined in the
configuration.
3. SQL for retrieval of Object-id must be present for each database
identification string supplied.
Parameter dbMap is not validated here as this is a private method and
hence it is assumed that the caller has carried out all validations
required.
Parameters:
dbMap: A fully initialized instance of class dbMap.
Returns: None.
Raises:
ConfigException: Inconsistency in configuration supplied through
dbMap.
- _BackEnd__executeDelete = __executeUpdate(self, queries, attributes, className)
- Private method to execute multiple update queries.
Parameters:
queries: A list containing query-strings to be executed. The queries
are executed in the order in which they are stored in this list.
attributes: A dictionary containing the values to be used in the
query in attribute(key) and value pairs.
className: The name of the class of this object(used to identify
the database identification string).
Returns: None
Raises:
CursorException: Cursor creation failure.
CommitException: Commit-failure on the database transaction.
ConnectionException: Database connection failed.
LimitException: The maximum limits on database connection-usage
reached.
Note: This method may raise database related errors too. See the
docstring of method BackEnd.__init__() for ways to catch these
errors.
- _BackEnd__executeInsert = __executeInsert(self, queries, attributes, className)
- Private method to execute insert queries. First query must be the one to
insert fields into the table which contains column for object id. Once
insertion is successfully completed, new id is retrieved and passed on
to the attribute dictionary, which in turn can be used for further
insertion into other tables.
Parameters:
queries: A list containing query-strings to be executed. The queries
are executed in the order in which they are stored in this list.
attributes: A dictionary containing the values to be used in the
query in attribute(key) and value pairs.
className: The name of the class of this object(used to identify
the database identification string).
Returns: None
Raises:
CursorException: Cursor creation failure.
CommitException: Commit-failure on the database transaction.
ConnectionException: Database connection failed.
LimitException: The maximum limits on database connection-usage
reached.
ObjectException: Failure in retrieving id.
Note: This method may raise database related errors too. See the
docstring of method BackEnd.__init__() for ways to catch these
errors.
- _BackEnd__executeSelect = __executeSelect(self, query, attributes, className)
- Private method to execute a select query on the database associated
with given class.
Parameters:
query: A string containing SQL query to be executed.
attributes: A dictionary containing the values to be used in the
query in attribute(key) and value pairs.
className: The name of the class of this object(used to identify
the database identification string).
Returns: A list of tuples. Each tuple contains the number of records
being selected through the query. If nothing is retrieved, An empty
list is returned.
Raises:
CursorException: Cursor creation failure.
CommitException: Commit-failure on the database transaction.
ConnectionException: Database connection failed.
LimitException: The maximum limits on database connection-usage
reached.
Note: This method may raise database related errors too. See the
docstring of method BackEnd.__init__() for ways to catch them.
- _BackEnd__executeUpdate = __executeUpdate(self, queries, attributes, className)
- Private method to execute multiple update queries.
Parameters:
queries: A list containing query-strings to be executed. The queries
are executed in the order in which they are stored in this list.
attributes: A dictionary containing the values to be used in the
query in attribute(key) and value pairs.
className: The name of the class of this object(used to identify
the database identification string).
Returns: None
Raises:
CursorException: Cursor creation failure.
CommitException: Commit-failure on the database transaction.
ConnectionException: Database connection failed.
LimitException: The maximum limits on database connection-usage
reached.
Note: This method may raise database related errors too. See the
docstring of method BackEnd.__init__() for ways to catch these
errors.
- _BackEnd__getTablesColumns = __getTablesColumns(self, className, attributes)
- Private method to fetch names of tables and their columns (with
respective attribute-names mapped) involved to build queries for a given
set of attributes.
Parameters:
className: Name of the class.
attributes: Attribute-set stored as a dictionary.
Returns: A dictionary where key is the name of the table and value is
another dictionary where key is the column-name(of that table) and
value is the corresponding attribute-name.
Raises:
NotExistsException: Certain attribute in the parameter
"attributes" is not found in the configuration for given class.
- __init__(self, dbMap=None)
- Constructor which is used to initialize the the object in two different
ways. To initialize the class members used for data management tasks,
this class is initialized with an instance of DBMap. This is called
stand-alone mode of initialization. It must be done only once in an
application. No instantiation of the classes inheriting from this class
is permitted unless stand-alone initialization is done. In threaded
applications it is advised to do stand-alone initialization in main
thread before starting any child thread. In single threaded applications
this should be done at the beginning of the program.
The second mode of initialization is called super-class initialization.
In this case the parameter dbMap is not passed on as an argument. It
happens whenever an object is initialized whose class is inherited from
this class. Here the constructor is called without arguments. The child
class must call this method explicitly at the end of its own
initialization work; i.e. it should call BackEnd.__init__(self).
Normally SQL related code is not needed to initialize an RDBMS backed
object. All is done automagically in the super class initialization.
In multi-threaded applications, you should set a re-entrant lock as
an attribute of your object (using setLock()) and use it while updating
the object-attributes through method updateSelf().
Parameters:
dbMap: A fully initialized DBMap object. Default is None.
Raises:
ParamException: The parameters dbMap is not initialized
appropriately or number of database connections specified in
configuration is not a positive non-zero integral number.
InitException: Class not initialized in stand-alone mode.
MulticallException: Constructor is called more than once in
stand-alone mode.
ConfigException: Inconsistency in configuration supplied through
dbMap.
ConnectionException: Database connection failed.
LimitException: The maximum limits on database connection usage
reached.
ClosedException: The database connection object no longer exists.
CursorException: Failure to create a Cursor object.
ObjectException: Failure to create the object from backend.
Note: This method may raise database related errors too. It can be
caught dynamically by using "dbModule.Error" in except clauses
where dbModule may be any one of the database module being used
by BackEnd. The list of all python db modules (should be
compliant to DB SIG 2) can be obtained by calling method
getDBModules().
- classes(self, ns={'BACKEND_DEBUG_LEVEL': 0, 'BackDB': <class backend.BackDB>, 'BackEnd': <class backend.BackEnd>, 'CallException': <class prangya.excgeneric.CallException>, 'ClosedException': <class prangya.excgeneric.ClosedException>, 'CommitException': <class prangya.excgeneric.CommitException>, 'ConfigException': <class prangya.excgeneric.ConfigException>, 'ConfigParser': <module 'ConfigParser' from '/usr/lib/python2.2/ConfigParser.pyc'>, 'ConnectionException': <class prangya.excgeneric.ConnectionException>, 'CursorException': <class prangya.excgeneric.CursorException>, ...})
- Method to retrieve the list of classes registered to backend. All
classes defined in the configuration must be defined at the time of
calling of this method.
Parameters:
ns: A dictionary with contents of global namespace in key-value
form. If this parameter is 'None' or empty string, a list of
available class names is returned. Else a list of class objects
retrieved from this namespace is returned.
Returns: Depending on the value of parameter 'ns', a list of backend
compliant class objects currently registered with class BackEnd or
a list of class names present in the configuration.
Raises:
ParamException: Parameter 'ns' is not a dictionary object.
InitException: Class not initialized in stand-alone mode.
NotExistsException: One of the class specified in the configuration
is not defined in global namespace or the one supplied in 'ns'.
- dbConnect(self, dbId, conStr)
- A factory method to obtain a named DBConnection object for the specified
database.
Parameters:
dbId: The database identification string.
conStr: The connection-registration string.
Returns: An instance of DBConnection class.
Raises:
ParamException: Either the parameters dbId or conStr are not valid
string objects or dbId is not registered with class BackEnd.
InitException: Class not initialized in stand-alone mode.
ConnectionException: Database connection failed.
LimitException: The maximum limits on database connection-usage
reached.
- deleteSelf(self)
- Method to delete the object (self) from the database. The object in
question, i.e. self must be compliant to the backend framework.
Please note that the object (in-memory) is not destroyed when this
method is called. It only removes the contents related to the concerned
object from backend database. It is the responsibility of the developer
to not to use in-memory object anymore e.g. by setting a destroyed flag
just before calling this method. Also follow proper thread-safe
programming procedure in a multi threaded environment.
Parameters: None.
Returns: None.
Raises:
ObjectException: Attribute "id" is not found in the object or it is
not an integer or long.
InitException: Class not initialized in stand-alone mode.
CursorException: Cursor creation failure.
CommitException: Commit-failure on the database transaction.
ConnectionException: Database connection failed.
LimitException: The maximum limits on database connection-usage
reached.
Note: This method may raise database related errors too. See the
docstring of method BackEnd.__init__() for ways to catch these
errors.
- getDBConnection(self, conStr)
- Method to obtain an instance of DBConnection class for the database
involved with this object. This method is reserved to be called through
the instance of class derived from "BackEnd" or its children. It should
not be called through an instance of "BackEnd" itself. In such
situations, use method "dbConnect()" instead.
Parameters:
conStr: A string used to identify the connection object.
Returns: An instance of DBConnection if operation succeeds.
Raises:
ParamException: Supplied parameter conStr is either empty or not a
string object.
InitException: Class BackEnd is not initialized in standalone mode.
ConnectionException: Database connection failed.
LimitException: Maximum limits on database connection-usage reached.
- getDBModules(self, dbId=None)
- Method to retrieve all (or any one of) python database modules being
used by backend framework.
Parameters:
dbId: The database identification string. Default is None.
Returns: If no parameter is supplied, a list of all python database
modules under use are returned. If parameter "dbId" is supplied,
it returns the module being used for it.
Raises:
ParamException: The parameter "dbId" is not a string object.
InitException: Class not initialized in stand-alone mode.
NotExistsException: Supplied database identification string is
not registered with backend.
- getInfo(self)
- Method to retrieve status of internal data structures of this
instance. This method is used for debugging only. It should never be
used to retrieve data for any other purpose.
Parameters: None.
Returns: String-representation of a dictionary containing name-value
pairs of public and private data of this class. Remember to not
to use this data for any other purpose than to debug this class.
Raises: None.
- insertSelf(self, attributes)
- Method to insert a set of data(attributes) into the database backend
and retrieve the new id of the object. Attributes for all not-null
columns of respective backend tables must be supplied as elements of
parameter "attributes".
Parameters:
attributes: A dictionary containing the the attributes of the
object which is to be created(inserted into database). Do not
pass on the key "id" in it. It will be removed silently.
Returns: None
Raises:
ParamException: Parameter "attributes" is not a dictionary.
InitException: Class not initialized in stand-alone mode.
NotExistsException: Certain attribute in the parameter
"attributes" is not found in the configuration for given class.
CursorException: Cursor creation failure.
CommitException: Commit-failure on the database transaction.
ConnectionException: Database connection failed.
LimitException: The maximum limits on database connection-usage
reached.
Note: This method may raise database related errors too. See the
docstring of method BackEnd.__init__() for ways to catch these
errors.
- registerId(self, id)
- Method to assign an identification number to an object of a class
derived from BackEnd. Its usually called from the constructor of the
user defined (and derived from BackEnd) class.
Parameters:
id: An integer specifying the object id. Usually represented by the
primary key of a table in the database.
Returns: None
Raises:
ParamException: The parameter id is not of type integer or long.
- searchId(self, classObj, attributes)
- Method to search and retrieve the ids of instances of "classObj"
matching the parameters supplied in "attributes".
Parameters:
classObj: A class object the ids of whose instances are to be
retrieved.
attributes: A dictionary containing the attribute-value pairs on the
basis of which search is carried out.
Returns: A list of ids if any matches are found, else empty list.
Raises:
ParamException: Parameter classObj is not a class object or
attributes is not a dictionary.
InitException: Class not initialized in stand-alone mode.
NotExistsException: Supplied class object is not registered with
BackEnd.
- setLock(self, lockName, lockObj)
- Method to set an instance based lock. This method should be called in
the constructor of the class if an instance based lock is to be created.
Parameters:
lockName: Name of the attribute holding the lock object.
lockObject: A lock object.
Returns: None.
Raises:
ParamException: Parameter "lockName" is not a string object or
parameter "lockObj" is not an instance of a class.
InitException: Class not initialized in stand-alone mode.
- updateSelf(self, attributes)
- Method to set attributes of an object along with respective columns in
database backend.
Please note that this method does not take care of thread-safety at
object level. You need to serialize this method-call explicitly by
implementing thread-locking if it is a threaded application. In that
case it is advised to acquire a re-entrant lock on the class or
instance of your class while calling this method. Once this method
returns (successfully or unsuccessfully) release that lock.
The choice of class level or instance level locks depends on the number
of objects and frequency of update of its attributes. For N number of
in-memory instances of the class, making a re-entrant lock as an
instance-attribute will consume N times the memory consumed by a single
lock object. But it will make each object independent of the other for
update purpose as multiple object-attributes can be updated
simultaneously. On the other hand if lock is a class-attribute, then for
all the instances of the class only one lock object will be used. But
this will serialize update calls at the class level. Thus attributes of
two instances of the class can not be updated simultaneously even in
multi-threaded applications.
Parameters:
attributes: A dictionary containing key-value pairs of attribute-
names and its value. You should not set the value for
attributes["id"]. If you do, the value supplied by you is
overwritten by object's own id.
Returns: None.
Raises:
ParamException: Parameters attributes is either empty or not of
dictionary type.
InitException: Class not initialized in stand-alone mode.
ObjectException: Attribute id is not found in the object.
ConnectionException: Database connection failed.
LimitException: The maximum limits on database connection-usage
reached.
CursorException: Failure to create a Cursor object.
CommitException: Commit-failure on the database transaction.
AttributeError: An attribute as specified in the configuration is
missing in the object. Usually caused by faulty constructor.
Note: This method may raise database related errors too. See the
docstring of method BackEnd.__init__() for ways to catch these
errors.
Data and non-method functions defined here:
- _BackEnd__initialized = 0
- __doc__ = '\n A class to handle creation of objects fro...ementing proper object locking mechanisms.\n '
- __module__ = 'backend'
|
class DBConnection |
| |
A dummy class to mimic the behavior of connection object whose interface-
definitions are given in python database API version 2 (DB SIG 2). The
only difference between the functionalities of these two classes are, that
the DBConnection.close() does not close the database connection as specified
in the specs. Instead it returns the actual Connection object back to the
db-pool held by class BackDB using appropriate callback.
|
| |
Methods defined here:
- __init__(self, name, dbCon=0)
- The constructor takes one argument name, which is a string containing
a unique name to distinguish this object from other similar objects.
The uniqueness of name is a prime criteria for proper functioning of
this class in conjunction with class BackDB.
Parameters:
name: A unique string used to identify the instance of this class.
dbCon: A database connection object.
Raises:
ParamException: Parameter "name" is not of string type.
- close(self)
- Method to return the actual connection object associated with
this instance to the creator object; i.e. to an instance of
BackDB. While created in a method in BackDB class, the instance
of DBConnection was assigned a callback method object for this
closing event. This method is stored in instance-attribute
__close_callback. It is invoked here with the id of the object.
This effectively takes away the database connection object from
this instance of DBConnection. The actual connection object is in
fact returned back to the pool of free database connections. Any
exception raised in callback method is not catchable and hence is
ignored silently.
If the attribute holding the callback method is not found,
no error is raised and the instance of DBConnection class is
silently flagged off as closed.
Parameters: None.
Returns: None.
Raises: None.
- commit(self)
- Wrapper method to commit transactions over a database connection. It
calls the commit() method of underlying database connection object.
Parameters: None.
Returns: None.
Raises:
CommitException: Failed to commit the pending transactions.
ClosedException: The database connection object no longer exists.
- cursor(self)
- Wrapper method to create a Cursor object using the underlying database
connection.
Parameters: None
Returns: An instance of the Cursor object defined in the underlying
database module.
Raises:
ClosedException: The database connection object no longer exists.
CursorException: Failure to create a Cursor object.
- isAlive(self)
- Method to check whether this instance is alive for database queries
or not.
Parameters: None
Returns: True(1) if object is alive, else false(0).
Raises: None.
- rollback(self)
- Wrapper method to rollback to the start of any pending transactions
over a database connection.
Parameters: None.
Returns: None.
Raises:
ClosedException: The database connection object no longer exists.
- setCallbackOnClose(self, method)
- Method to set a callback handler when the instance of this class is
effectively terminated by a call to its close() method.
Parameter:
method: A user-defined function object or method object.
Returns: None.
Raises:
ClosedException: The database connection object no longer exists.
ParamException: The parameter supplied is not either a method
object or function object.
- setDBCon(self, dbCon)
- Method to associate a database Connection object with the instance of
this class.
Parameter:
dbCon: Database Connection object returned by db driver module.
Returns: None.
Raises:
ClosedException: The database connection object no
longer exists.
ParamException: The parameter dbCon is not an object.
ExistsException: The DBConnection object is already
associated with another connection object.
Data and non-method functions defined here:
- __doc__ = '\n A dummy class to mimic the behavior of co...y class BackDB using appropriate callback.\n '
- __module__ = 'backend'
|
class DBMap |
| |
A class to set and get constraints involved in mapping objects of
a particular class to corresponding database in the backend. The
objects are identified with their class names and databases with their
identification strings used to initialize instances of class BackDB.
Almost all functionalities of DBMap is oriented towards fulfilling
the requirements posed by classes BackDB and BackEnd defined in this
module. Its an integral part of backend framework.
A configuration file with a structure similar to Windows' ini files
are used to represent these mappings. All syntax rules applicable
for windows.ini file is applicable here too. For example sections are
enclosed in rectangular braces([]), lines beginning with semi-colon(;)
are comments, options and values are separated with equal(=) sign,
blank lines are ignored etc. A sample configuration file is given
below.
; <= Configuration file begins.
; Sample configuration file(dbmap.ini) which can be supplied to the
; constructor of class DBMap. Most of the following discussion involves
; using class DBMap along with class BackEnd. DBMap holds just the details
; required for correct functioning of BackEnd. You can consider it just as
; an interpreter and storage manager for configuration data.
[Object-Database Map]
; Class names are mapped to corresponding databases. Here "school" and
; "office" are database identification strings.
Teacher = school
Student = school
Supplier = office
Item = office
[Database-DBURL Map]
; Each database identification string requires corresponding DBURL for
; opening a connection to that database. Here school points to a postgres
; database named schooldb while office points to a mysql one named officedb.
school = rdb:pgdb//user1@password1:pgserver.example.com:5432/schooldb
office = rdb:MySQLdb//user2@password2:localhost:3306/officedb
[Database-NumConnection Map]
; Maximum number of database connections allowed for the application to
; use. It should be fixed for each database.
school = 12
office = 8
[Database-InitSQLs Map]
; SQL to be executed for the first time the connection is made. Multiple
; SQL statements can be specified with colon(:) as the separator. For
; switching off auto-commit in mysql, following statement is used.
office = SET AUTOCOMMIT=0
; If a particular database does not require any initialization, do not
; mention it in this section as we are not mentioning "school" here.
[Database-LastIdSQL Map]
; SQL to be executed for retrieving the last id inserted into the table.
; The macro {TABLE} expands to the correct table name used for storing the
; id of the class for which query is being built. The query must be such
; that only one record of only one column is fetched, which is the id
; itself. Following entries show the queries for postgres and mysql
; respectively. Usually the entry for postgres (i.e. "school") works for
; any SQL-82 compliant RDBMS.
school = SELECT id FROM {TABLE} ORDER BY id DESC LIMIT 1
office = SELECT last_insert_id()
[Class personnel.Teacher]
; Attributes of Teacher object. This class is defined in module file
; personnel.py.
id = teachers.id
name = teachers.name
subject = tsmaps.subjectId
maxQualification = tqmaps.qId
; Since three tables are involved, there must be two relationship-
; definitions separated by commas. They show the relationships amongst the
; columns of these three tables.
{Relations} = tsmaps.teacherId=teachers.id,tqmaps.teacherId=teachers.id
; A sequence in postgres named "teachers_seq" is used to get unique ids for
; each records in table teachers. Following shows the value to be used in
; insertion queries for attribute id.
{IdInsertValue} = nextval('teachers_seq')
; Delete operation on an instance of class Teacher should delete records
; from tables "teachers", "tsmaps" and "tqmaps". So mention those table-
; names here. If some tables are to be ignored, do not mention them.
; Absence of this entry means you do not want to delete the object
; concerned. The order of listing may be important for successful deletion
; of records. The deletion on the table storing object-id will always be
; carried out last irrespective of its position in the listing. Also any
; space character present in the table listing will be removed silently.
{DeleteOnTables} = teachers,tsmaps,tqmaps
[Class personnel.Student]
; Attributes of Student object. Attributes of it are stored in single table.
; Hence no relationship is required. It is also defined in personnel.py.
id = students.id
age = students.age
minorFlag = students.minor
lastGrade = students.lastgrade
credit = students.netcredit
primarysubject = prisubjects.subject_id
remarks = students.remarks
{IdInsertValue} = nextval('students_seq')
{DeleteOnTables} = students
; Datatype of attribute "credit" is float and it is defined as such in the
; backend database table. Floats and doubles are uncomparable data types.
; They can not be used in the where clause of a select or update query.
; You must mention such table-column names (separated by commas) here.
{UncompTabCols} = students.netcredit
; Due to some reasons if you do not wish to insert data into a
; table even if its column holds certain attribute of the object; you can
; do that. List such table names here separated by commas. Obviously its
; optional. Same is true for the next option too.
{NoInsertOnTables} = foo, bar, baz
; Similar mechanism is available for updating the backend. If you do not
; wish to update certain tables while updating the attributes of the object,
; list them here separated by commas.
{NoUpdateOnTables} = foo,bar
[Class business.Supplier]
; Attributes of Supplier object. This class is defined in business.py.
id = suppliers.id
name = suppliers.name
address = suppliers.address
remarks = suppliers.remarks
{DeleteOnTables} = suppliers
; Since database is mysql, passing empty string in an auto-increment field
; works correctly.
{IdInsertValue} = ''
[Class __main__.Item]
; Attributes of Item object. This class is defined in a file which is passed
; to the python interpreter directly, hence the module name "__main__".
id = items.id
name = items.name
batchNo = items.batchno
price = items.price
{IdInsertValue} = ''
{DeleteOnTables} = items
; <= Configuration file ends.
It is possible to initialize an empty instance of this class. Then using
the given interfaces(methods) that instance can be populated with required
data and finally it can be written into a file on disk. This file can be
read back to create the same object in future.
For simplicity, no thread-safety measures are available in this class.
Hence do not change attributes of the instance of this class or
re-initialize it in multiple threads. All initialization should be done
in main thread before spawning others. You have been warned in advance.
|
| |
Methods defined here:
- __getitem__(self, item)
- Method to let the instance of this class mimic the behavior of a
dictionary to retrieve data relevant to class attributes to database
mappings.
Parameters:
item: The name of the class(class section name in config file).
Returns: A dictionary containing the attribute maps of that class,
provided it exists in the config file. Else raises exception.
Raises:
ParamException: The parameter item is not of string type.
KeyError: If parameter item is not specified in the config file.
- __init__(self, configFile)
- Constructor to initialize class to database mappings either from a
configuration file or with empty parameters. Its not necessary to have
a file in advance. You can create an empty DBMap object and then set
respective values into it. Then the whole configuration can be written
to the file whose name and path is supplied in the constructor.
Parameters:
configFile: The full path of the configuration file for mappings.
Raises:
ParamException: The parameter configFile is not of string type or
required permissions not found on that file or the directory
containing it.
- __setitem__(self, item, value)
- Method to (implicitly) add a class name to the configuration and
initialize it with a given value.
Parameters:
item: The name of the class to be added into the configuration.
value: The initialization value. It must be a dictionary.
Returns: None.
Raises:
ParamException: The parameter item is not of string type or value
is not of dictionary type.
- attributes(self, className)
- Method to retrieve the list of attributes defined in the
configuration file for the given class.
Parameters:
className: The name of the class whose attribute-names are to be
retrieved.
Returns: A list containing the attributes of the given class.
Raises:
ParamException: The parameter className is not of string type.
KeyError: The parameter className is not found in configuration.
- classes(self)
- Method to retrieve the list of classes defined in the configuration
file.
Parameters: None.
Returns: A list containing the names of the classes defined in the
config file.
Raises: None.
- columnIsUncomparable(self, className, tableName, columnName)
- Method to test whether supplied column of given table associated with
given class is uncomparable or not.
Parameters:
className: The name of the class.
tableName: The name of the table. Invalid table name does not raise
any exception. In such case the return value is 0.
columnName: The name of the column which is to be tested. Invalid
column name does not raise any exception. In such case the
return value is 0.
Returns: 1 if column is uncomparable. In all the other cases including
invalid table or column names, 0.
Raises:
ParamException: Any of the parameters "className", "tableName" or
"columnName" are either empty or not string objects.
NotExistsException: Supplied class-name is not found in the
configuration.
- dbURLs(self)
- Method to retrieve all pairs of database identification string and
corresponding DBURL.
Parameters: None.
Returns: A list of pairs of database identification string and
respective DBURL(in tuple form).
Raises: None.
- getAttributeName(self, className, tableName, columnName)
- Method to obtain the name of the attribute of certain object of class
className used to store the data of given column(columnName) of table
(tableName).
Parameters:
className: Name of the class whose instance is under consideration.
tableName: Name of the database table whose certain column is given.
columnName: Name of the column of given table.
Returns: A string specifying the name of the attribute being requested.
Raises:
ParamException: The parameters className, tableName or columnName
are not string objects.
ConfigException: Failure to retrieve the attribute-name due to
inconsistency in the configuration.
- getDBId(self, className)
- Method to retrieve the database identification string associated with
a class.
Parameters:
className: The name of the class(class section name in config file).
Returns: Database identification string.
Raises:
ParamException: The parameter className is not of string type.
KeyError: If parameter className is not found in the configuration.
- getDBURL(self, dbId)
- Method to retrieve the DBURL for a database identified by dbId.
Parameters:
dbId: The database identification string.
Returns: DBURL.
Raises:
ParamException: The parameter dbId is not of string type.
KeyError: If parameter dbId is not found in the configuration.
- getDeleteOnTables(self, className)
- Method to retrieve the list of table names from which respective records
are to be deleted whenever the object of given class is deleted from the
backend.
Parameters:
className: Name of the class for which the list of tables is to be
retrieved.
Returns: A list of table names. Empty list if no table names defined for
deletion in configuration.
Raises:
ParamException: The parameter className is not of string type.
NotExistsException: The parameter className is not found in the
configuration.
- getIdInsertValue(self, className)
- Method to retrieve the value to be used in SQL (for insert query) for
attribute id of given class.
Parameters:
className: Name of the class.
Returns: A string to be used in insert query as value for attribute id
of given class.
Raises:
ParamException: The parameter className is not of string type.
NotExistsException: If parameter className is not found in the
configuration.
- getInfo(self)
- Method to retrieve status of internal data structures of this
instance. Generally this method is used for debugging only. It
should never be used to retrieve data for any other purpose.
Parameters: None.
Returns: String-representation of a dictionary containing name-value
pairs of public and private data of this class. Remember to not
to use this data for any other purpose than to debug this class.
Raises: None.
- getInitSQLs(self, dbId)
- Method to retrieve the SQL statements required to initialize a database
as soon as a new connection is made.
Parameters:
dbId: Database identification string of the database for which the
initialization statements(SQLs) are to be retrieved.
Returns: A list of SQL statements.
Raises:
ParamException: The parameter dbId is not of string type.
NotExistsException: If parameter dbId is not found in the
configuration.
- getLastIdSQL(self, dbId)
- Method to retrieve the SQL statement required to obtain the last
(object)id inserted into the database table.
Parameters:
dbId: Database identification string of the database for which the
id-retrieval statement(SQL) is to be obtained.
Returns: An SQL statement or and empty string if none available.
Raises:
ParamException: The parameter dbId is not of string type.
NotExistsException: If parameter dbId is not found in the
configuration.
- getNoInsertOnTables(self, className)
- Method to retrieve the list of tables into which the records should not
be inserted while creating a new object of given class.
Parameters:
className: Name of the class.
Returns: A list containing the table names.
Raises:
ParamException: The parameter className is not of string type.
NotExistsException: The parameter className is not found in the
configuration.
- getNoUpdateOnTables(self, className)
- Method to retrieve the list of tables whose fields should not be
updated while updating certain attribute(s) of a object of given class.
Parameters:
className: Name of the class.
Returns: A list containing the table names.
Raises:
ParamException: The parameter className is not of string type.
NotExistsException: The parameter className is not found in the
configuration.
- getNumConnection(self, dbId)
- Method to retrieve the maximum number of connection permitted for a
database identified by dbId.
Parameters:
dbId: The database identification string.
Returns: An integer specifying the maximum number of database
connections permitted for given database.
Raises:
ParamException: The parameter dbId is not of string type.
KeyError: The parameter dbId is not found in the configuration.
- getRelations(self, className)
- Method to retrieve the list of relationships amongst table-columns for
given class.
Parameters:
className: Name of the class.
Returns: List of strings specifying table-column relationships for given
class.
Raises:
ParamException: The parameter className is not of string type.
KeyError: If parameter className is not found in the configuration.
- getUncomparables(self, className, tableName=None)
- Method to retrieve the list of columns having uncomparable data types
like float or double.
Parameters:
className: Name of the class.
tableName: Name of the table. Default is None.
Returns: A list or dictionary containing details of uncomparable columns
of tables involved for given class. If table name is provided, then
a list of uncomparable columns in that table are returned. Else a
dictionary with table-name as key and a list of such columns as
value is returned.
Raises:
ParamException: The parameter className or tableName are not of
string type.
NotExistsException: The parameter className is not found in the
configuration.
- read(self, confFile=None)
- Method to populate the internal data structures of this class with the
data obtained from the configuration file.
Parameters:
configFile: The optional configuration file. Default is None.
Returns: None.
Raises:
ParamException: The parameter confFile is not of string type.
FileException: Error in accessing the configuration file.
ConfigException: Inconsistency or error in configuration file.
ConfigParser.DuplicateSectionError: Duplicate sections found in the
configuration file.
ConfigParser.MissingSectionHeaderError: Config file contains no
section headers.
ConfigParser.ParsingError: Failure in configuration file parsing.
- setDBId(self, className, idString)
- Method to associate a class with a database identification string.
The description-entry for that class must exist in the configuration
already, either from configuration file or through the method
__setitem__().
Parameters:
className: The name of the class which is to be mapped to given
database identification string.
idString: The database identification string.
Returns: None.
Raises:
ParamException: The parameter className or idString is not of
string type.
- setDBURL(self, dbId, dbURL)
- Method to associate a database with a DBURL used to access it.
Parameters:
dbId: The database identification string for which the DBURL is
being set.
dbURL: The DBURL.
Returns: None.
Raises:
ParamException: The parameter dbId or dbURL is not of string type.
- setDeleteOnTables(self, className, tabList)
- Method to set the list of table names from which respective records
are to be deleted whenever the object of given class is deleted from the
backend. Please make sure that the table-names passed on are the correct
one for the class involved. No test is being carried out to check it.
Wrong table names may produce unpredictable results including data
corruption. Though empty list is allowed. In such cases there would be
no delete operations possible on instances of corresponding class.
Parameters:
className: Name of the class for which the list of tables is to be
set.
tabList: The list of tables involved in object-deletion.
Returns: None.
Raises:
ParamException: The parameters className is not of string type or
the parameter tabList is not of list type.
NotExistsException: The parameter className is not found in the
configuration.
- setIdInsertValue(self, className, insertVal)
- Method to set id-value for insert query for attribute id of given class.
Parameters:
className: The name of the class for which the id-value is is being
set.
insertVal: A string to be used as id-value in insert query for given
class.
Returns: None.
Raises:
ParamException: The parameters insertVal or className are not of
string types.
- setInitSQLs(self, dbId, sqlList)
- Method to set the SQL statements needed to initialize a database
as soon as a new connection is made.
Parameters:
dbId: Database identification string of the database for which the
initialization statements(SQLs) are to be set.
sqlList: List of sql statements.
Returns: None
Raises:
ParamException: The parameter dbId is not of string type or the
parameters sqlList is not of list type.
NotExistsException: If parameter dbId is not found in the
configuration.
- setLastIdSQL(self, dbId, sql)
- Method to set the SQL statement needed to retrieve last inserted object
id from a table.
Parameters:
dbId: Database identification string of the database for which the
id-retrieval statement(SQL) is to be set.
sql: SQL statement.
Returns: None
Raises:
ParamException: The parameter dbId or sql is not of string type.
NotExistsException: The parameter dbId is not found in the
configuration.
- setNoInsertOnTables(self, className, tabList)
- Method to set the list of table names for a particular class into which
records will not be entered while creating a new object of supplied
class. Please make sure that the table-names passed on are the correct
ones for the class involved. No test is being carried out to check it.
Wrong table names may produce unpredictable results including data
corruption. Though empty list is allowed which will reset the dictionary
self._noInsTables to empty.
Parameters:
className: The name of the class for which table list is to be set.
tabList: The list of tables which should not be touched while
inserting new data for a newly created object. It will be added
to the existing table-names in the configuration. If tabList
is an empty list, all the existing table-names will be removed
from the configuration.
Returns: None.
Raises:
ParamException: The parameters className is not of string type or
the parameter tabList is not of list type.
NotExistsException: The parameter className is not found in the
configuration.
- setNoUpdateOnTables(self, className, tabList)
- Method to set the list of table names for a particular class which
should not be touched while updating certain attribute(s) of the object
of supplied class. Please make sure that the table-names supplied are
the correct ones for the class involved. No test is being carried out
to check its validity. Wrong table names may produce unpredictable
results including data corruption. Though empty list is allowed which
will reset the dictionary self._noInsTables to empty.
Parameters:
className: The name of the class for which table list is to be set.
tabList: The list of tables which should not be touched while
updating attribute(s) of the object of the given class. It will
be added to the existing table-names in the configuration. If
tabList is an empty list, all the existing table-names will be
removed from the configuration.
Returns: None.
Raises:
ParamException: The parameters className is not of string type or
the parameter tabList is not of list type.
NotExistsException: The parameter className is not found in the
configuration.
- setNumConnection(self, dbId, numCon)
- Method to set limit on maximum number of connections for given database.
Parameters:
dbId: The database identification string for which the number of
connection is being set.
numCon: Integer specifying the number of connection.
Returns: None.
Raises:
ParamException: The parameters dbId or numCon are not of string
type or integer type respectively.
- setRelations(self, className, relations)
- Method to set table-column relationships for a particular class.
Parameters:
className: The name of the class for which the table-column
relationship is being set.
relations: A list containing all table-column relationships meant
for a class.
Returns: None.
Raises:
ParamException: The parameters className or relations are not of
string type or list type respectively.
- setUncomparables(self, className, tableName, columnList)
- Method to set or remove uncomparable column types for a class and table.
Parameters:
className: Name of the class which must not be "None" or empty
string.
tableName: Name of the table which can be "None" or empty string if
all existing uncomparable column details for given class are to
be removed from existing configuration. If it is empty or "None"
then parameter "columnList" is not used or tested.
columnList: A list containing the columns of given table. If it is
"None" or empty, then all existing (uncomparable) columns for
the given table are removed from the configuration. Else
supplied ones are set after removing existing columns for the
given table.
Returns: None.
Raises:
ParamException: The parameters className or tableName are not string
objects or columnList is not list object.
NotExistsException: The parameter className is not found in the
configuration.
- write(self, confFile=None)
- Method to write current configuration into the config file. If the file
is not specified in the arguments, the one supplied to the method
__init__ is used instead.
Parameters:
confFile = The full path of the file into which the configuration
is to be written. Default is None.
Returns: None.
Raises:
ParamException: The parameter confFile is not of string type.
IOError: Failure in opening/writing configuration file.
Data and non-method functions defined here:
- __doc__ = '\n A class to set and get constraints involv...g others. You have been warned in advance.\n '
- __module__ = 'backend'
| |