__init__(self, parentObjectStore=None)
(Constructor)

Initializes an 'EditingContext'.

Parameter 'parentObjectStore'

determines which 'ObjectStore' the receiver will use to fetch its data and to save changes made in it ; the default (i.e. when the parameter is omitted or equals to 'None') is to use the one returned by 'defaultParentObjectStore()' --which in turn defaults to the application-wide shared 'CooperatingObjectStore.defaultCoordinator()'.

Note that the parent 'ObjectStore' of an 'EditingContext' cannot be changed during the whole object's lifetime.

You will typically use the default behaviour, or provide an parent 'EditingContext' to make the newly created 'EditingContext' a child of the former one (not supported yet __TBD).

Implementation Note:

The object graph is hold by 4 variables:

• the UniquingTable holds the whole graphs

• _insertedObjects

• _deletedObjects

• _updatedObjects: these three variables only reference GlobaldIDs

  More than that: there should only be empty intersections between each one and an other, or many methods could fail or mis-behave in an uncontrolled way!! Last, but not least, please note that the union of these 3 sets is a subset of the whole graph (which additionally holds objects that were fetched but are still unmodified).

• Additionally, each of these last three attributes has its equivalent for changes that were not yet processed (e.g. _pendingUpdatedObjects). These changes are moved to the

Additional notes:

__TBD This is not that good... in fact there should be some
__TBD 'ObjectGraph' object here to manage these.

__TBD Plus: the way it is implemented here is naive and certainly
__TBD sub-sub-optimal in terms of run-time efficiency (data structures
__TBD imply time-consuming treatments). refactoring will be done in
__TBD the future, for the moment I need to concentrate on features...

Overrides:

__builtin__.object.__init__

__del__(self)
(Destructor)

__unimplemented__(self)

allDeletedGlobalIDs(self)

Returns a sequence made of GlobalIDs of objects that have been deleted into the EditingContext and that have not been made persistent yet.

The GlobalIDs returned are those identifying objects who were marked as deleted within the EditingContext, while deletedGlobalIDs() only returns the GlobalIDs for objects that were marked as deleted before the last invocation of processRecentChanges() (or saveChanges()).

See also: deletedGlobalIDs(), allDeletedObjects()

allDeletedObjects(self)

Returns a sequence made of objects that were removed from the graph of objects managed by the EditingContext.

allDeletedObjects() returns all the objects that have been marked as deleted within the EditingContext, while deletedObjects() only returns the objects that were marked as deleted before the last invocation of processRecentChanges() (or saveChanges()).

See also: insertedObjects(), updatedObjects(), hasChanges

allInsertedGlobalIDs(self)

Returns a sequence made of GlobalIDs of objects that have been inserted into the EditingContext and that have not been made persistent yet.

The GlobalIDs returned are those identifying objects who were marked as inserted within the EditingContext, while insertedGlobalIDs() only returns the GlobalIDs for objects that were marked as inserted before the last invocation of processRecentChanges() (or saveChanges()).

See also: insertedObjects(), allInsertedObjects()

allInsertedObjects(self)

Returns a sequence made of the objects that have been inserted into the EditingContext and that have not been made persistent yet.

allInsertedObjects() returns all the objects that have been marked as inserted within the EditingContext, while insertedObjects() only returns the objects that were marked as inserted before the last invocation of processRecentChanges() (or saveChanges()).

See also: deletedObjects(), updatedObjects(), hasChanges()

allUpdatedGlobalIDs(self)

Returns a sequence made of GlobalIDs of objects that have been updated into the EditingContext and that have not been made persistent yet.

The GlobalIDs returned are those identifying objects who were marked as updated within the EditingContext, while updatedGlobalIDs() only returns the GlobalIDs for objects that were marked as updated before the last invocation of processRecentChanges() (or saveChanges()).

See also: updatedObjects(), allUpdatedObjects()

allUpdatedObjects(self)

Returns a sequence made of the objects that are marked for update.

allUpdatedObjects() returns all the objects that have been marked for update within the EditingContext, while updatedObjects() only returns the objects that were marked for update before the last invocation of processRecentChanges() (typically, after saveChanges()).

See also: deletedObjects(), insertedObjects(), hasChanges()

arrayFaultWithSourceGlobalID(self, aGlobalID, aRelationshipName, anEditingContext)

Overrides:

Modeling.ObjectStore.ObjectStore.arrayFaultWithSourceGlobalID

autoInsertion(self)

If true, processRecentChanges() will search for newly created objects related to updated&inserted objects in the EditingContext, and these new objects will in turn be automatically inserted in the EditingContext.

Default is false.

delete(self, anObject)

Informs the 'EditingContext' that the supplied object should be marked as deleted, so that it will actually be deleted when the receiver saves changes. This is not an error to mark an object as deleted more than once: this will be silently ignored.

Parameter 'anObject' should already be registered within the 'EditingContext' ; if not, ObjectNotRegisteredError is raised.

Both methods deleteObject() and delete() are completely equivalent.

deletedGlobalIDs(self)

Returns a sequence made of GlobalIDs of objects that were removed from the graph of objects managed by the EditingContext.

The GlobalIDs returned are those indentifying objects who were marked as deleted before the last invocation of processRecentChanges() (or saveChanges()). If you want to get all deleted GlobalIDs, see allDeletedGlobalIDs().

See also: deletedObjects()

deletedObjects(self)

Returns a sequence made of objects that were removed from the graph of objects managed by the EditingContext.

The objects returned are those who were marked as deleted before the last invocation of processRecentChanges() (typically after saveChanges()). If you want to get all deleted objects, see allDeletedObjects().

See also: insertedObjects(), updatedObjects(), hasChanges

deleteObject(self, anObject)

Informs the 'EditingContext' that the supplied object should be marked as deleted, so that it will actually be deleted when the receiver saves changes. This is not an error to mark an object as deleted more than once: this will be silently ignored.

Parameter 'anObject' should already be registered within the 'EditingContext' ; if not, ObjectNotRegisteredError is raised.

Both methods deleteObject() and delete() are completely equivalent.

dispose(self)

faultForGlobalID(self, aGlobalID, anEditingContext=None)

Searches for an object registered within the EditingContext with the supplied GlobalID, and returns it if it is found. If not, forwards the message to the parentObjectStore (usually an ObjectStoreCoordinator).

If anEditingContext is a child of self,

Overrides:

Modeling.ObjectStore.ObjectStore.faultForGlobalID

faultForRawRow(self, row, entityName, anEditingContext=None)

Turns a row (dictionary) into a real object. Any row, such as the one returned by a fetch when raw rows is actvated, 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 -- (optional) The EditingContext in which the object

should be registered. Defaults to self if None or omitted.

Overrides:

Modeling.ObjectStore.ObjectStore.faultForRawRow

fetch(self, entityName, qualifier=None, isDeep=0, rawRows=0)

Returns the objects identified by the following parameters:

entityName -- the corresponding entity's name (see also isDeep, below)

qualifier -- a string qualifying the objects to be fetched (a instance

of Qualifier can also be supplied)

isDeep -- shall the fetch be made against the entity and its

sub-entities?

fetchCount(self, entityName, qualifier=None, isDeep=0)

Returns the approximate number of objects that would be returned by fetch() 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 (in which case objectsWithFetchSpecification() would not return them --see its documentation as well).

Returns the objects identified by the following parameters:

entityName -- the corresponding entity's name (see also isDeep, below)

qualifier -- a string qualifying the objects to be fetched (a instance

of Qualifier can also be supplied)

isDeep -- shall the fetch be made against the entity and its

sub-entities?

forgetObject(self, anObject)

Inverse for recordObject(): removes itself from the observers of 'anObject', removes the object and its GlobalID from the UniquingTable, and removes the weakref for self stored in 'anObject'.

Parameter:

anObject -- a CustomObject instance

You should never call this method by yourself: it is for internal use only (e.g. at the end of the process of saving changes, DatabaseContexts uses this to inform the EditingContext of any changes that occured on objects' globalIDs --which is always the case when an inserted object has been saved in the DB)

globalIDForObject(self, anObject)

handleNotification(self, notification)

hasChanges(self)

Tells whether some changes have been made in the graph of objects the EditingContext manages, whose have not been made persistent yet (i.e. newly inserted objects, some that have been modified or some that have been removed from the graph of objects

This method does not make any difference between processed and unprocessed changes ; to know if there are some unprocessed changes, use 'hasUnprocessedChanges()' instead.

See also: deletedObjects(), insertedObjects(), updatedObjects(),

hasUnprocessedChanges()

hasUnprocessedChanges(self)

Tells whether the EditingContext knows that some changes were made to its graph of objects that were not processed yet

See also: processRecentChanges()

initializeObject(self, anObject, aGlobalID, anEditingContext)

Forwards the message to the parentObjectStore(), with the following exception: if 'anEditingContext' 's 'parentObjectStore()' is 'self', i.e. it is a child of 'self', and if 'self' already has an real object (not a fault) with that globalID, the values of this object is used to initialize 'anObject'.

Conformance to the ObjectStore API

Parameters:

anObject -- a CustomObject instance

aGlobalID -- the GlobalID of 'anObject'

anEditingContext -- the EditingContext which holds 'anObject'

Overrides:

Modeling.ObjectStore.ObjectStore.initializeObject

insert(self, anObject)

Inserts a new object within the graph of objects. The 'EditingContext' generates a 'TemporaryGlobalID' for that object, registers the object as a new one in its graph of objects and registers itself as an observer for that object (see ObserverCenter).

An object should not be inserted more than once. The only valid situation where an object can be re-inserted is when this object has previously been marked as deleted (hence un-deleting the object), otherwise 'ValueError' is raised.

However, if self.propagateInsertionWithEditingContext() is true, a RuntimeWarning is issued, rather than raising ValueError. In that case, the warning message will refer to the caller of 'insertObject'. If you want to turn these warnings to real exceptions (e.g. for systematic tracking of such situations), simply put the following statement in your app.'s init. code:

import warnings
warnings.filterwarnings(action='error', category=RuntimeWarning)

or start 'python' with argument '-W error::RuntimeWarning::0'. (see the documentation for standard module warnings for further details)

Both methods insertObject() and insert() are completely equivalent.

insertedGlobalIDs(self)

Returns a sequence made of GlobalIDs of objects that have been inserted into the EditingContext and that have not been made persistent yet.

The GlobalIDs returned are those indentifying objects who were marked as inserted before the last invocation of processRecentChanges() (or saveChanges()). If you want to get all inserted GlobalIDs, see allInsertedGlobalIDs().

See also: insertedObjects()

insertedObjects(self)

Returns a sequence made of the objects that have been inserted into the EditingContext and that have not been made persistent yet.

The objects returned are those who were marked as inserted before the last invocation of processRecentChanges() (typically, after saveChanges()). If you want to get all inserted objects, see allInsertedObjects().

See also: deletedObjects(), updatedObjects(), hasChanges()

insertObject(self, anObject)

Inserts a new object within the graph of objects. The 'EditingContext' generates a 'TemporaryGlobalID' for that object, registers the object as a new one in its graph of objects and registers itself as an observer for that object (see ObserverCenter).

An object should not be inserted more than once. The only valid situation where an object can be re-inserted is when this object has previously been marked as deleted (hence un-deleting the object), otherwise 'ValueError' is raised.

However, if self.propagateInsertionWithEditingContext() is true, a RuntimeWarning is issued, rather than raising ValueError. In that case, the warning message will refer to the caller of 'insertObject'. If you want to turn these warnings to real exceptions (e.g. for systematic tracking of such situations), simply put the following statement in your app.'s init. code:

import warnings
warnings.filterwarnings(action='error', category=RuntimeWarning)

or start 'python' with argument '-W error::RuntimeWarning::0'. (see the documentation for standard module warnings for further details)

Both methods insertObject() and insert() are completely equivalent.

insertObjectWithGlobalID(self, anObject, aTemporaryGlobalID)

You should normally not call this method directly. To insert an object, use 'insertObject()' instead.

Parameter:

'aTemporaryGlobalID' -- must respond 'true' to message 'isTemporary'

(the method raises 'ValueError' otherwise)

invalidatesObjectsWhenFinalized(self)

isaChildOf(self, anEditingContext)

Tells whether self is a child of anEditingContext, either directly (anEditingContext is its parent) or indirectly (anEditingContext is its grand-parent, or grand-grand-parent, etc.).

Note that self is not a child of self.

lock(self)

Acquire the reentrant-lock for the EditingContext. Calls to 'lock()' should be balanced with the same number of 'unlock()' for the lock to be released. Use this if you need to use the EditingContext in a multi-threaded environment.

See also: unlock()

objectForGlobalID(self, aGlobalID)

objectsCountWithFetchSpecification(self, aFetchSpecification, anEditingContext=None)

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 (in which case objectsWithFetchSpecification() would not return them --see its documentation as well).

Forwards the message to the parentObjectStore(), usually an ObjectStoreCoordinator.

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.

Overrides:

Modeling.ObjectStore.ObjectStore.objectsCountWithFetchSpecification

objectsWithFetchSpecification(self, aFetchSpecification, anEditingContext=None)

Returns the objects matching the supplied FetchSpecification.

Note that returned objects are:

• objects that are already stored in the database. If some, if not all, of these objects are already registered within the EditingContext, they are returned as-is --meaning that, if they have been modified after they have been fetched from the database, these modifications are NOT overridden.
• new objects that are inserted in the EditingContext (see insertObject()) but that are not saved yet.

Objects that are marked as deleted (cf. deleteObject()) in the EditingContext are not returned.

When a nested EditingContext fetches objects, the result set will contain the objects that are inserted in the parent (or the parent's parent, etc.), and objects which are marked as deleted in parent will not be part of the result set.

If parameter 'anEditingContext' is omitted or 'None', it defaults to 'self', then the message is forwarded down the hierarchy of ObjectStores, i.e. to the 'parentObjectStore()'

Conformance to the ObjectStore API

See also: DatabaseContext.objectsWithFetchSpecifications()

Overrides:

Modeling.ObjectStore.ObjectStore.objectsWithFetchSpecification

objectWillChange(self, anObject)

ObservingInterface implementation

Automatically invoked when an object is about to change its state.

Silently ignores changes if they occur on an inserted, deleted or already updated objects.

Simply logs (at warning level) if the EditingContext receives a notification of changes for an object which is not in its uniquing table (hence, not in its graph of objects) -- __TBD this behaviour should probably be changed, since it should never happen at all.

ownsObject(self, anObject)

Overrides:

Modeling.ObjectStore.ObjectStore.ownsObject

parentObjectStore(self)

processRecentChanges(self)

Examines the graph of objects and take appropriate actions.

This includes:

• registers all unprocessed changes: inserted, updated and deleted objects
• if propagatesInsertionForRelatedObjects() is true, it searches the inserted and updated objects's relationships for newly created objects, which are in turn inserted into the EditingContext, if needed.
• for all deleted objects, cascade the delete if this needs to be done
• __TBD registers undo informations
• posts 'ObjectsChangedInEditingContextNotification' and 'ObjectsChangedInStoreNotification'

This method is also automatically called when the EditingContext is instructed to save changes.

See also: saveChanges(), saveChangesInEditingContext()

ClassDescription.propagateDeleteForObject() ClassDescription.propagateInsertionForObject()

propagatesInsertionForRelatedObjects(self)

If true, processRecentChanges() will search for newly created objects related to updated&inserted objects in the EditingContext, and these new objects will in turn be automatically inserted in the EditingContext.

Default is false.

recordObject(self, anObject, aGlobalID)

Make the editing context aware of this object by adding itself as an observer for it and by adding it to the uniquing table.

You should never need to invoke this method directly, it it automatically called within the framework when it needs to. To insert an object into the graph of objects, use 'insertObject()' instead.

See also: insertObject()

redo(self)

Unimplemented yet

Raises if no UndoManager is assigned to the EditingContext

See also: redo(), setUndoManager()

registeredObjects(self)

rootObjectStore(self)

Returns the 'ObjectStoreCoordinator' in the underlying hierarchy of 'ObjectStore'.

Forwards the 'rootObjectStore' message to the 'parentObjectStore()', which in turn does the same thing, until the 'ObjectStoreCoordinator' is found.

Conformance to the ObjectStore API

See also: ObjectStoreCoordinator.rootObjectStore()

Overrides:

Modeling.ObjectStore.ObjectStore.rootObjectStore

saveChanges(self)

Tells the EditingContext to save the changes made within the graph of objects it is responsible for. It first sends the 'processRecentChanges' message to itself, then validates the changes against the constraints defined both in the model and in possible custom validation methods, and finally calls its parent objects store's 'saveChangesInEditingContext()' method.

Raises Validation.ValidationException if the validation process failed, or a RuntimeError if something failed during the process of saving changes in the underlying database(s).

See also: saveChangesInEditingContext(), processRecentChanges(),

parentObjectStore(), validateChanges()

saveChangesInEditingContext(self, anEditingContext)

Called on the parent EditingContext when a child EditingContext saves changes.

Exceptions that can be raised:

• ValueError if 'anEditingContext' is not a child of self

Note: this method also automatically locks 'self' before actually

saving the changes ; this makes it possible for two children of a single EC to safely save their changes in two different threads without having to worry about explicitly locking the parent EC.

See also: saveChanges(), processRecentChanges()

setAutoInsertion(self, bool)

See propagatesInsertionForRelatedObjects() for details.

If 'bool' is true and self.propagatesInsertionForRelatedObjects() is false, all updated and inserted objects are sent the 'propagateInsertionWithEditingContext' message ; this can take some time.

We suggest that you do not change the behaviour after you started working with objects within the EditingContext ; it is probably better to choose to set it to true or false right after the EditingContext is created.

Parameter:

bool -- a boolean value

setInvalidatesObjectsWhenFinalized(self, aBool)

See also: invalidatesObjectsWhenFinalized()

setPropagatesInsertionForRelatedObjects(self, bool)

See propagatesInsertionForRelatedObjects() for details.

If 'bool' is true and self.propagatesInsertionForRelatedObjects() is false, all updated and inserted objects are sent the 'propagateInsertionWithEditingContext' message ; this can take some time.

We suggest that you do not change the behaviour after you started working with objects within the EditingContext ; it is probably better to choose to set it to true or false right after the EditingContext is created.

Parameter:

bool -- a boolean value

setUndoManager(self, anUndoManager)

Unimplemented yet

See also: undoManager()

undo(self)

Unimplemented yet

Raises if no UndoManager is assigned to the EditingContext

See also: redo(), setUndoManager()

undoManager(self)

unlock(self)

Releases the lock for the EditingContext.

See also: lock()

updatedGlobalIDs(self)

Returns a sequence made of GlobalIDs of objects that have changed since the last saveChanges(), or since the EditingContext was created.

The GlobalIDs returned are those indentifying objects who were marked as updated before the last invocation of processRecentChanges() (or saveChanges()). If you want to get all updated GlobalIDs, see allUpdatedGlobalIDs().

See also: allUpdatedGlobalIDs(), updatedObjects()

updatedObjects(self)

Returns a sequence made of the objects that have changed since the last invocation of processRecentChanges (typically, after the last saveChanges()).

If you want to get all updated objects, including those marked after the last invocation of processRecentChanges(), see allUpdatedObjects().

See also: deletedObjects(), insertedObjects(), hasChanges()

validateChanges(self)

Performs validation on all objects in the EditingContext.

This is automatically called by saveChanges() before changes are forwarded to the database(s). You should rarely need to call it yourself. If you do, you must make sure that processRecentChanges() is called before, since this method does not process pending changes.

The validation process stops after the first error.

See also: processRecentChanges(), saveChanges()