__init__(self, aDatabase)
(Constructor)

Initialization also creates it own AdaptorContext to work with, by sending to aDatabase.adaptor() the message createAdaptorContext().

Parameter 'aDatabase' should be a 'Modeling.Database' object

__unimplemented__(self)

adaptorContext(self)

availableChannel(self)

Returns an available DatabaseChannel, i.e. one in its registeredChannels() which is not busy (==has no fetch in progress). If all registeredChannels are busy or if the DatabaseContext has no registered channels, it posts the notification 'DatabaseChannelNeededNotification' ; if it can find an available channel afterwards, it simply returns it. Otherwise, a new DatabaseChannel is created, registered and returned.

See also:

DatabaseChannel.isFetchInProgress()

commitChanges(self)

Commits the transaction in progress --that transaction was opened when the ObjectStore got one of the two message 'saveChangesInEditingContext()' or 'performChanges()'.

This is the penultimate step of save changes.

Raises 'RuntimeError' if the DatabaseContext is not saving changes.

See also: saveChangesInEditingContext(),

prepareForSaveWithCoordinator(), recordChangesInEditingContext(), performChanges(), rollbackChanges() finalizeCommitChanges()

Overrides:

Modeling.CooperatingObjectStore.CooperatingObjectStore.commitChanges

coordinator(self)

Returns the current ObjectStoreCoordinator which which the DatabaseContext cooperates during the process of saving changes. The coordinator is set when prepareForSaveWithCoordinator() is called, and it is reset whenever the process aborts --either with commitChanges() or rollbackChanges().

Outside a process of save changes, this returns None.

See also: prepareForSaveWithCoordinator(), commitChanges(),

rollbackChanges(), _endTransaction()

Overrides:

Modeling.CooperatingObjectStore.CooperatingObjectStore.coordinator

database(self)

delegate(self)

dispose(self)

faultForGlobalID(self, keyGlobalID, anEditingContext)

Creates and registers a new Fault for the supplied globalID.

Raises 'ValueError' if keyGlobalID is invalid (i.e. it does not responds to message 'entityName()' --typically, if it is not a 'KeyGlobalID')

Parameters:

keyGlobalID -- a 'KeyGlobalID'

anEditingContext -- the editing context in which the fault should be

registered.

Overrides:

Modeling.ObjectStore.ObjectStore.faultForGlobalID

faultForRawRow(self, row, entityName, anEditingContext)

Turns a row (dictionary) into a real object. Any row, such as the one returned by a fetch when raw rows is activated, can be turned into a real object given that it contains the primary keys.

Parameters:

row -- a dictionary. This dictionary should have the entity's primary

keys in its keys (and their corresponding values)

entityName -- the name of the entity the row represents

anEditingContext -- The EditingContext in which the object should be

registered. Defaults to self if None or omitted.

See also: EditingContext.fetch(), FetchSpecification.setFetchesRawRows

Overrides:

Modeling.ObjectStore.ObjectStore.faultForRawRow

finalizeCommitChanges(self)

Called by the ObjectStoreCoordinator to re-synchronize the local snapshots with the (application-wide) Database's snapshots and to clean everything up.

This is the last step of saving changes. DatabaseContext's implementation forwards all changes made to its Database then empties/invalidates the internal state used during the process of saving changes. Last, it forwards the new KeyGlobalIDs (which replace the TemporaryGlobalIDs initially assigned to inserted objects) to the EditingContext.

You should never called this by yourself, it is automatically called by the framework.

forgetAllLocks(self)

forgetLocksForObjectsWithGlobalIDs(self, gIDs)

forgetSnapshotForGlobalID(self, aGlobalID)

Deletes all references for aGlobalID in the local snapshot table.

Parameter:

aGlobalID -- a GlobalID instance

Raises KeyError is aGlobalID is not registered, or RuntimeError if no process of saving changes is in progress

forgetSnapshotsForGlobalIDs(self, gIDs)

Deletes all references for each GlobalID in gIDs in the local snapshot table.

Parameter:

gIDs -- a sequence of GlobalID instances

Raises KeyError is one GlobalID in 'gIDs' is not registered, or RuntimeError if no process of saving changes is in progress

handleDroppedConnection(self)

handlesFetchSpecification(self, aFetchSpecification)

Overrides:

Modeling.CooperatingObjectStore.CooperatingObjectStore.handlesFetchSpecification

handlesObject(self, anObject)

Simply invokes ownsObject() on itself.

Conformance to the ObjectStore API.

Overrides:

Modeling.ObjectStore.ObjectStore.handlesObject

hasBusyChannels(self)

Returns 1 (true) if any of the channels() answers true to the message 'isFetchInProgress()', false otherwise.

See also: DatabaseChannel.isFetchInProgress()

initializeObject(self, aDatabaseObject, aGlobalID, anEditingContext)

Parameters:

aGlobalID -- KeyGlobalID (non temporary)

Overrides:

Modeling.ObjectStore.ObjectStore.initializeObject

invalidateAllObjects(self)

Overrides:

Modeling.ObjectStore.ObjectStore.invalidateAllObjects

invalidateObjectsWithGlobalIDs(self, gIDs)

Overrides:

Modeling.ObjectStore.ObjectStore.invalidateObjectsWithGlobalIDs

isObjectLockedWithGlobalID(self, aGlobalID, anEditingContext)

Overrides:

Modeling.ObjectStore.ObjectStore.isObjectLockedWithGlobalID

isSavingChanges(self)

Tells whether the DatabaseContext is currently saving changes.

See also: prepareForSaveWithCoordinator(), saveChangesInEditingContext(),

_endTransaction()

localSnapshotForGlobalID(self, aGlobalID)

Returns the snapshot locally registered for the supplied GlobalID.

If no snapshot was registered for that name and GlobalID, or if no process of saving changes is in progress, simply returns None.

localSnapshotForSourceGlobalID(self, aGlobalID, aName)

Returns the toMany snapshot locally registered for the supplied GlobalID and name.

Parameters:

aGlobalID -- a GlobalID instance

aName -- the name of the relationship

If no toMany snapshot was registered for that name and GlobalID, or if no process of saving changes is in progress, simply returns None.

lock(self)

Acquire the (reentrant) lock of the instance. Each call to 'lock()' must be balanced with a call to 'unlock()'.

See also: unlock()

lockObjectWithGlobalID(self, aGlobalID, anEditingContext)

Overrides:

Modeling.ObjectStore.ObjectStore.lockObjectWithGlobalID

missingObjectGlobalIDs(self)

objectsCountWithFetchSpecification(self, aFetchSpec, anEditingContext)

Returns the approximate number of objects that would be returned by objectsWithFetchSpecification() if called with the very same parameters.

About ``approximate'': the number returned is in fact the upper bound ; as the objects are not actually fetched against the database, it is not possible to determine whether some have already been deleted within anEditingContext (see objectsWithFetchSpecification() as well).

Parameters:

aFetchSpecification -- a FetchSpecification object describing the

objects to be fetched

anEditingContext -- the EditingContext in which the objects would be

fetched. This is in fact an optional argument: since no objects are fetched it is not really needed.

See also: DatabaseChannel.selectCountObjectsWithFetchSpecification()

Overrides:

Modeling.ObjectStore.ObjectStore.objectsCountWithFetchSpecification

objectsForSourceGlobalID(self, srcGlobalID, aRelationshipName, anEditingContext)

This method is dedicated for use by a toMany fault handler.

See also: AccessArrayFaultHandler

Overrides:

Modeling.ObjectStore.ObjectStore.objectsForSourceGlobalID

objectsWithFetchSpecification(self, aFetchSpec, anEditingContext)

Fetches and returns a sequence of objects corresponding to the supplied fetch specification 'aFetchSpec'. These objects are also recorded within 'anEditingContext' 's uniquing table.

If an object is already in the EditingContext, that object is returned, not the one that was fetched --unless the FetchSpecification 'aFetchSpec' is refreshing objects (not tested yet).

It does NOT discard any objects that might be deleted in the 'anEditingContext', neither does it returns the objects that were inserted in anEditingContext but not saved yet ; it is the responsability of EditingContext.objectsWithFetchSpecification() to do this.

Parameters:

aFetchSpecification -- a FetchSpecification object describing the

objects to be fetched

anEditingContext -- the EditingContext in which the fetched objects

should be registered.

Returns: the fetched objects, all of which are registered within anEditingContext.

See also: objectsCountWithFetchSpecification(),

EditingContext.objectsWithFetchSpecification()

Overrides:

Modeling.ObjectStore.ObjectStore.objectsWithFetchSpecification

ownsEntityName(self, entityName)

ownsGlobalID(self, aGlobalID)

Overrides:

Modeling.CooperatingObjectStore.CooperatingObjectStore.ownsGlobalID

ownsObject(self, anObject)

Overrides:

Modeling.CooperatingObjectStore.CooperatingObjectStore.ownsObject

performChanges(self)

This is the third and last step (apart from commitChanges() or rollbackChanges()) being triggered by the ObjectStoreCoordinator when the latter was instructed to save the changes made in an EditingContext. The 'EditingContext' instance this method works with is the one supplied when 'prepareForSaveWithCoordinator()' was called.

It depends on prepareForSaveWithCoordinator() and recordChangesInEditingContext() having been called before ; you should never need to call this method by hand.

What we do here is derive AdaptorOperations from the DatabaseOperations built on the previous step [recordChangesInEditingContext()]. These AdaptorOperations are ordered and sent to an available AdaptorChannel as the parameter for message performAdaptorOperation()

Raises 'RuntimeError' if the DatabaseContext is not saving changes.

Overrides:

Modeling.CooperatingObjectStore.CooperatingObjectStore.performChanges

prepareForSaveWithCoordinator(self, aCoordinator, anEditingContext)

This is the first step being triggered by the ObjectStoreCoordinator when it is instructed to save the changes made in an EditingContext.

See also: recordChangesInEditingContext(), performChanges(),

commitChanges(), rollbackChanges(), EditingContext.saveChanges()

(Copied from CooperatingObjectStore interface)

DatabaseContext's implementation examines objects in 'anEditingContext' ; all inserted, updated or deleted objects that are under its control (cf. ownsGlobalID()) are kept internally --until the process ends with either commitChanges() or rollbackChanges(). The DatabaseContext afterwards cooperates with an available AdaptorChannel to generate primary keys for newly inserted objects.

Raises 'RuntimeError' if the DatabaseContext is not saving changes.

Parameters:

aCoordinator -- the ObjectStoreCoordinator which called the method.

anEditingContext -- the EditingContext asking for its changes to be

saved.

Conformance to the CooperatingObjectStore interface.

See also: coordinator()

Overrides:

Modeling.CooperatingObjectStore.CooperatingObjectStore.prepareForSaveWithCoordinator

recordChangesInEditingContext(self)

Second step being triggered by the ObjectStoreCoordinator when the latter was instructed to save the changes made in an EditingContext. The 'EditingContext' instance this method works with is the one supplied when 'prepareForSaveWithCoordinator()' was called.

This method has two distinct tasks:

• it builds the set of DatabaseOperations needed to make the changes persistent,
• it also registers every changed objects into the local snapshotting table. IMPORTANT: the local snapshotting mechanism does not have any references to TemporaryGlobalID objects: new objects are detected and a brand new GlobalID is built for them, based upon the PKs values that were computed at the previous step (cf. prepareForSaveWithCoordinator()). This applies to ``regular'' snapshots and to ``toMany snapshots'' as well.

You should never need to call this method by yourself, it is automatically called by the ObjectStoreCoordinator in charge.

See also: prepareForSaveWithCoordinator(), performChanges(),

commitChanges(), rollbackChanges(), EditingContext.saveChanges() recordUpdateForObject()

Raises 'RuntimeError' if the DatabaseContext is not saving changes.

(Copied from CooperatingObjectStore interface)

DatabaseContext implementation builds all necessary DatabaseOperation objects for the observed changes. These DatabaseOperations are then examined to check whether they do not imply changes to other objects in relation with the one they were build for, and if it is the case, the DatabaseContext forwards these changes to the ObjectStoreCoordinator. You can also refer to DatabaseOperation 's documentation for a more complete discussion on this topic.

This method also always add a fake DatabaseOperation to its own set, whose operator is DATABASE_NOTHING_OPERATOR and whose globalID, object and entity all equals to the string 'fake' --this is used by recordUpdateForObject(), see this method for a complete discussion on this.

See also: DatabaseOperation,

_recordChangesInEditingContext(), _examineToManySnapshots()

Overrides:

Modeling.CooperatingObjectStore.CooperatingObjectStore.recordChangesInEditingContext

recordSnapshotForGlobalID(self, snapshot, aGlobalID)

recordSnapshotForSourceGlobalID(self, gids, aGlobalID, aName)

recordSnapshots(self, snapshots)

recordToManySnapshots(self, snapshots)

recordUpdateForObject(self, aDatabaseObject, changes)

Called by the ObjectStoreCoordinator when an other DatabaseContext (including self) needs to forward changes on a given object --this can happen, for example, when a toMany relationship that has no inverse to-one relationship is modified in a given object 'obj1', because in this case the modification implies the modification of a foreign key stored in one or more objects 'obj<i>!=obj1'.

This method is for internal use, you should not need to call it by hand. The following explanations are implementation details.

DatabaseContexts are designed in such a way that it can receive such messages before or after recordChangesInEditingContext() has processed its own changes. More precisely, when calling this method on self, recordChangesInEditingContext() takes care to process all its changes (inserted, updated or deleted objects) before it may call this method.

As a consequence:

• if recordChangesInEditingContext() has not been called yet, it just stores the pending changes to be applied, by simply storing 'changes' in a pending database operation's newRow(). These changes will be then processed when recordChangesInEditingContext() is called.
• otherwise, the behaviour depends on whether the method recordChangesInEditingContext() already created a database operation for the object. If it did, then this database operation is updated according to the supplied changes; otherwise a brand new database oeration is created and local snapshots are registered for the object.

Parameters:

aDatabaseObject -- the database object for which changes are notified

changes -- a dictionary of {attributeName: value}

See also: ObjectStoreCoordinator.forwardUpdateForObject()

recordChangesInEditingContext()

Overrides:

Modeling.CooperatingObjectStore.CooperatingObjectStore.recordUpdateForObject

registerChannel(self, aDBchannel)

Adds the supplied DatabaseChannel to the list of registeredChannels(). Raises ValueError if aDBchannel.databaseContext() is not self. If aDBChannel is already registered it silently returns.

See also: registeredChannels(), unregisterChannel()

registeredChannels(self)

Return the list of registered DatabaseChannels.

See also: registerChannels(), unregisterChannel()

registerLockedObjectWithGlobalID(self, aGlobalID)

rollbackChanges(self)

Rollbacks any changes sent at the previous step (cf. performChanges()) and cleans up the DatabaseContext's internal variables which support the process of saving changes.

Tou should not call this method by yourself, it is automatically triggered by the framework, when appropriate.

Raises 'RuntimeError' if the DatabaseContext is not saving changes.

See also: commitChanges()

Overrides:

Modeling.CooperatingObjectStore.CooperatingObjectStore.rollbackChanges

rootObjectStore(self)

Raises RuntimeError unconditionally: a DatabaseContext is not (yet) designed to be the 'rootObjectStore()' of an 'ObjectStore' hierarchy. The only possible root for an hierarchy of ObjectStores is an 'ObjectStoreCoordinator'.

See also: saveChangesInEditingContext()

Overrides:

Modeling.ObjectStore.ObjectStore.rootObjectStore

saveChangesInEditingContext(self, anEditingContext)

Unimplemented: a DatabaseContext is not (yet) designed to be the 'rootObjectStore()' of an 'ObjectStore' hierarchy. The only possible root for an hierarchy of ObjectStores is an 'ObjectStoreCoordinator'.

See also: rootObjectStore()

setDelegate(self, aDelegate)

setUpdateStrategy(self, aStrategy)

Sets the DatabaseContext's update strategy

Raise RuntimeError if the DatabaseContext is currently saving changes.

snapshotForGlobalID(self, aGlobalID, timestamp=0)

Returns the snapshot for 'aGlobalID'. Snapshots are searched within the local set of snapshots, then in the object's database.

Returned value is 'None' if no snapshot was recorded for 'aGlobalID' or if a snapshot exists with a smaller timestamp than parameter 'timestamp'

snapshotForSourceGlobalID(self, aGlobalID, relationshipName, timestamp=0)

Returns the snapshot for 'aGlobalID' and the toMany relationship 'relationshipName'. Snapshots are searched within the local set of snapshots, then in the object's database.

Returned value is 'None' if no snapshot was recorded for 'aGlobalID' and 'relationshipName' or if a snapshot exists with a smaller timestamp than parameter 'timestamp'

unlock(self)

Releases the (reentrant) lock of the instance.

See also: lock()

unregisterChannel(self, aDBChannel)

Unregister 'aDBChannel' from the list of registered DatabaseChannels.

See also: registerChannel(), registeredChannels()

updateStrategy(self)

Returns the DatabaseContext's updateStrategy

Default is UPDATE_WITH_NO_LOCKING

valuesForKeys(self, keys, aDatabaseObject)