# -*- coding: iso-8859-1 -*-
#-----------------------------------------------------------------------------
# Modeling Framework: an Object-Relational Bridge for python
#
# Copyright (c) 2001-2004 Sbastien Bigaret <sbigaret@users.sourceforge.net>
# All rights reserved.
#
# This file is part of the Modeling Framework.
#
# This code is distributed under a "3-clause BSD"-style license;
# see the LICENSE file for details.
#-----------------------------------------------------------------------------
"""
AdaptorContext API
Notifications
AdaptorChannelBeginTransactionNotification
AdaptorChannelCommitTransactionNotification
AdaptorChannelRollbackTransactionNotification
CVS information
$Id: AdaptorChannel.py 932 2004-07-20 06:21:57Z sbigaret $
"""
__version__='$Revision: 932 $'[11:-2]
try:
from Interface import Base
except:
class Base:
pass
class IAdaptorChannel(Base):
"""
Implemented, can be overriden (better not, if possible)
setDelegate
Should be overriden:
attributesToFetch
cancelFetch
closeChannel
deleteRowsDescribedByQualifier
describeModelWithTableNames
describeResults
describeStoredProcedureNames
describeTableNames
evaluateExpression
executeStoredProcedure
fetchRow
insertRow
isFetchInProgress
isOpen
openChannel
primaryKeysForNewRowsWithEntity
returnValuesForLastStoredProcedureInvocation
selectAttributes
setAttributesToFetch
updateValuesInRowsDescribedByQualifier
"""
def __init__(self, anAdaptorContext):
"""
"""
def adaptorContext(self):
"""
"""
def addStoredProceduresNamed(self, storedProcedureNames, aModel):
"""
"""
def attributesToFetch(self):
"""
"""
def cancelFetch(self):
"""
"""
def closeChannel(self):
"""
Implemented by concrete AdaptorChannels to close the channel.
Implementation should follow the following recommendations regarding
this method's side-effects:
- when a channel closes, it should cancels any operation that might
be in progress,
- the method should silently accept closing an already closed channel
- when the channel is closed, it should send to its AdaptorContext
the 'adaptorChannelDidClose()' message if and only if the channel was
indeed opened when it receives the message
abstract
"""
def delegate(self):
"""
"""
def deleteRowDescribedByQualifier(self, aQualifier, anEntity):
"""
Calls 'deleteRowsDescribedByQualifier()' on itself and make sure that one
and only one row was deleted. If the returned value from
'deleteRowsDescribedByQualifier()' is not one, it raises
GeneralAdaptorException.
Subclasses should not override this method.
Parameters: see deleteRowsDescribedByQualifier()
"""
def deleteRowsDescribedByQualifier(self, aQualifier, anEntity):
"""
Implemented by subclasses to delete the rows identified by the parameters.
This method returns the number of rows deleted.
Parameters:
aQualifier -- a Qualifier object describing the rows to delete
anEntity -- the Entity corresponding to the type of the objects
to-be-deleted (hence, identifies the database table from which rows
should be deleted)
See also: deleteRowDescribedByQualifier(), performAdaptorOperation()
"""
def describeModelWithTableNames(self, tableNames):
"""
"""
def describeResults(self):
"""
"""
def describeStoredProcedureNames(self):
"""
"""
def describeTableNames(self):
"""
"""
def dictionaryWithObjectsForAttributes(self, objects, attributes):
"""
"""
def evaluateExpression(self, anSQLexpression):
"""
Extract the SQL statement from 'anSQLexpression' and sends it to the
database for execution.
If its AdaptorContext did not have an opened transaction when this
method is called, it should automatically start a new transaction which is
ended before the method returns.
Note that this method is not used at all by the framework itself, thus
subclasses have no obligation to implement it.
Parameter:
anSQLexpression -- the SQLExpression object to execute
See also: SQLExpression.statement(), AdaptorContext.hasOpenTransaction()
"""
def executeStoredProcedure(self, aStoredProcedure, values):
"""
"""
def fetchRow(self):
"""
When there is no more result, this method should return 'None' and
do whatever is necessary to make sure that 'isFetchInProgress()'
returns false.
"""
def insertRow(self, row, anEntity):
"""
"""
def isFetchInProgress(self):
"""
"""
def isOpen(self):
"""
abstract
"""
def lockRowComparingAttributes(self, atts, anEntity, aQualifier, snapshot):
"""
"""
def openChannel(self):
"""
Implemented by subclasses to make sure that the Adaptor Layer (mainly,
AdaptorChannel and its context) has a working connection/channel to
the Database.
This method should silently returns if everything was already set.
Raises if the communication channel cannot be opened ; reasons for this
to happen can be (non exhaustively):
- the Adaptor's connection dictionary is incomplete or wrong (bad
password e.g.)
- the database server is not available
abstract
"""
def performAdaptorOperation(self, anAdaptorOperation):
"""
Examines 'anAdaptorOperation' and executes the corresponding method.
Given that 'operator' is anAdaptorOperation.operator(), and that constants
used below (such as 'ADAPTOR_INSERT_OPERATOR') are defined in class
DatabaseOperation, this is how things work:
- if 'operator' is 'ADAPTOR_INSERT_OPERATOR', we call insertRow()
- if 'operator' is 'ADAPTOR_DELETE_OPERATOR', we call
deleteRowDescribedByQualifier()
AdaptorChannel provide a default implementation for this method, and
subclasses should not override this method.
Raises GeneralAdaptorException in case of failure
Parameter:
adaptorOperation -- the AdaptorOperation to execute
See also: performAdaptorOperations(), DatabaseOperation
"""
def performAdaptorOperations(self, adaptorOperations):
"""
Iterates on each item in 'adaptorOperations' and calls
'performAdaptorOperation()' with that item as a parameter.
AdaptorChannel provide a default implementation for this method, and
subclasses should not override this method.
Parameter:
adaptorOperations -- a sequence of AdaptorOperation objects
"""
def primaryKeysForNewRowsWithEntity(self, count, anEntity):
"""
Implemented by subclasses to return a list of dictionaries, whose keys are
PK attributes' names and values the corresponding PK value.
Since the framework does not handle compound primary keys, it should
return an empty list if 'anEntity' defines more than one PK.
See also:
SchemaGeneration.primaryKeySupportStatementsForEntityGroup()
"""
def returnValuesForLastStoredProcedureInvocation(self):
"""
"""
def rowCountForSelectAttributes(self, attributes, aFetchSpecification,
shouldLock, anEntity):
"""
Implemented by concrete adaptors to return the number of rows that would
be fetched if selectAttributes() is called with the same arguments.
Parameters: see selectAttributes()
"""
def selectAttributes(self, attributes, aFetchSpecification, shouldLock,
anEntity):
"""
Implemented by concrete AdaptorChannels to select...
Parameters:
- 'attributes'
- 'aFetchSpecification'
- 'shouldLock'
- 'anEntity': it overrides the one set in 'aFetchSpecification' (in
fact, aFetchSpecification's entityName is not used at all ; however,
parameter 'anEntity' is either the same than aFetchSpecification's
one, or one of its subclass).
abstract
"""
def setAttributesToFetch(self, attributes):
"""
"""
def setDelegate(self, aDelegate):
"""
"""
def updateValuesInRowDescribedByQualifier(self, row, aQualifier, anEntity):
"""
Calls 'updateValuesInRowsDescribedByQualifier' on itself and make sure
that one and only one row was updated. If the returned value from
'updateValuesInRowsDescribedByQualifier' is not exactly one, it raises
GeneralAdaptorException.
Subclasses should not override this method.
Parameters: see updateValuesInRowsDescribedByQualifier
"""
def updateValuesInRowsDescribedByQualifier(self, row, aQualifier, anEntity):
"""
Implemented by subclasses to update the rows identified by the parameters.
This method returns the number of updated rows.
Parameters:
row --
aQualifier -- a Qualifier object describing the rows to update
anEntity -- the Entity corresponding to the type of the objects to be
updated (hence, identifies the database table from which rows should
be updated)
See also: updateValuesInRowDescribedByQualifier(),
performAdaptorOperation()
"""
|