PATH Documentation > WebObjects 4.5 > EOControl Reference

EOEditingContext

Inherits from:
EOObjectStore : NSObject

Conforms to:
EOObserving

NSLocking

Declared in:
EOControl/EOEditingContext.h

Class at a Glance

An EOEditingContext object manages a graph of enterprise objects in an application; this object graph represents an internally consistent view of one or more external stores (most often a database).

Principal Attributes

Set of enterprise objects managed by the EOEditingContext
Parent EOObjectStore
Set of EOEditor objects messaged by the EOEditingContext
A message handler

Creation

- initWithParentObjectStore:

Designated initializer.

Commonly Used Methods

- objectsWithFetchSpecification:	Fetches objects from an external store.
- insertObject:	Registers a new object to be inserted into the parent EOObjectStore when changes are saved.
- deleteObject:	Registers that an object should be removed from the parent EOObjectStore when changes are saved.
- lockObject:	Attempts to lock an object in the external store.
- hasChanges	Returns YES if any of the receiver has any pending changes to the parent EOObjectStore.
- saveChanges	Commits changes made in the receiver to the parent EOObjectStore.
- revert	Removes everything from the undo stack, discards all insertions and deletions, and restores updated objects to their original values.
- objectForGlobalID:	Given a globalID, returns its associated object.
- globalIDForObject:	Given an object, returns its globalID.
- setDelegate:	Sets the receiver's delegate.
- parentObjectStore	Returns the receiver's parent EOObjectStore.
- rootObjectStore	Returns the receiver's root EOObjectStore.

Class Description

An EOEditingContext object represents a single "object space" or document in an application. Its primary responsibility is managing a graph of enterprise objects. This object graph is a group of related business objects that represent an internally consistent view of one or more external stores (usually a database).

All objects fetched from an external store are registered in an editing context along with a global identifier (EOGlobalID) that's used to uniquely identify each object to the external store. The editing context is responsible for watching for changes in its objects (using the EOObserving protocol) and recording snapshots for object-based undo. A single enterprise object instance exists in one and only one editing context, but multiple copies of an object can exist in different editing contexts. Thus object uniquing is scoped to a particular editing context.

For more information on EOEditingContext, see the sections:

Constants

In EOEditingContext.h, EOControl defines the following int constant to specifies the order in which editing contexts perform end of event processing in processRecentChanges.

EditingContextFlushChangesRunLoopOrdering

Messages with lower order numbers are processed before messages with higher order numbers. In an application built with the Application Kit, the constant order value schedules the editing context to perform its processing before the undo stack group is closed or window display is updated.

EOEditingContext.h also defines NSString constants for the names of the notifications it posts. See the section "Notifications" for more information.

Adopted Protocols

EOObserving
- objectWillChange:

NSLocking
- lock

- unlock

Method Types

Initializing an EOEditingContext

- initWithParentObjectStore:

Fetching objects

- objectsWithFetchSpecification:

Committing or discarding changes

- saveChanges

- saveChanges:

- tryToSaveChanges

- refaultObjects

- refault:

- refetch:

- revert

- revert:

- invalidateAllObjects

Registering changes

- deleteObject:

- insertObject:

- insertObject:withGlobalID:

- objectWillChange:

- processRecentChanges

Checking changes

- deletedObjects

- insertedObjects

- updatedObjects

- hasChanges

Object registration and snapshotting

- forgetObject:

- recordObject:globalID:

- committedSnapshotForObject:

- currentEventSnapshotForObject:

- objectForGlobalID:

- globalIDForObject:

- registeredObjects

Timestamping snapshots

+ defaultFetchTimestampLag

+ setDefaultFetchTimestampLag:

- fetchTimestamp

- setFetchTimestamp:

Locking objects

- lockObject:

- lockObjectWithGlobalID:editingContext:

- isObjectLockedWithGlobalID:editingContext:

- setLocksObjectsBeforeFirstModification:

- locksObjectsBeforeFirstModification

Undoing operations

- redo:

- undo:

- setUndoManager:

- undoManager

Accessing the shared editing context

- sharedEditingContext

- setSharedEditingContext:

Deletion and Validation Behavior

- setPropagatesDeletesAtEndOfEvent:

- propagatesDeletesAtEndOfEvent

- setStopsValidationAfterFirstError:

- stopsValidationAfterFirstError

Returning related object stores

- parentObjectStore

- rootObjectStore

Managing editors

- editors

- addEditor:

- removeEditor:

Setting the delegate

- setDelegate:

- delegate

Setting the message handler

- setMessageHandler:

- messageHandler

Invalidating objects

- setInvalidatesObjectsWhenFreed:

- invalidatesObjectsWhenFreed

Locking

- lock

- unlock

Working with raw rows

- faultForRawRow:entityNamed:

Unarchiving from nib

+ defaultParentObjectStore

+ setDefaultParentObjectStore:

+ setSubstitutionEditingContext:

+ substitutionEditingContext

Nested EOEditingContext support

- objectsWithFetchSpecification:editingContext:

- objectsForSourceGlobalID:relationshipName:editingContext:

- arrayFaultWithSourceGlobalID:relationshipName:editingContext:

- faultForGlobalID:editingContext:

- saveChangesInEditingContext:

- refaultObject:withGlobalID:editingContext:

- invalidateObjectsWithGlobalIDs:

- initializeObject:withGlobalID:editingContext:

Archiving and unarchiving objects

+ encodeObject:withCoder:

+ initObject:withCoder:

+ setUsesContextRelativeEncoding:

+ usesContextRelativeEncoding

Class Methods

defaultFetchTimestampLag

+ (NSTimeInterval)defaultFetchTimestampLag

Returns the default timestamp lag.

defaultParentObjectStore

+ (EOObjectStore *)defaultParentObjectStore

Returns the EOObjectStore that is the default parent object store for new editing contexts. Normally this is the EOObjectStoreCoordinator returned from the EOObjectStoreCoordinator class method defaultCoordinator.

See Also: + setDefaultParentObjectStore:

encodeObject:withCoder:

+ (void)encodeObject:(id)object withCoder:(NSCoder *)encoder

Invoked by an enterprise object object to ask the EOEditingContext to encode object using encoder. For more discussion of this subject, see "Using EOEditingContext to Archive Custom Objects in Web Objects Framework" .

initObject:withCoder:

+ (id)initObject:(id)object withCoder:(NSCoder *)decoder

Invoked by an enterprise object object to ask the EOEditingContext to initialize object from data in decoder. For more discussion of this subject, see "Using EOEditingContext to Archive Custom Objects in Web Objects Framework" .

instancesRetainRegisteredObjects

+ (BOOL)instancesRetainRegisteredObjects

Returns YES if editing contexts retain their registered objects; NO otherwise.

setDefaultFetchTimestampLag:

+ (void)setDefaultFetchTimestampLag:(NSTimeInterval)lag

Sets the default timestamp lag for newly instantiated editing contexts to lag. The default lag is 3600.0 seconds (one hour).

When a new editing context is initialized, it is assigned a fetch timestamp equal to the current time less the default timestamp lag. Setting the lag to a large number might cause every new editing context to accept very old cached data. Setting the lag to too low a value might degrade performance due to excessive fetching. A negative lag value is treated as 0.0.

setDefaultParentObjectStore:

+ (void)setDefaultParentObjectStore:(EOObjectStore *)store

Sets the default parent EOObjectStore to store. You use this method before loading a nib file to change the default parent EOObjectStores of the EOEditingContexts in the nib file. The object you supply for store can be a different EOObjectStoreCoordinator or another EOEditingContext (if you're using a nested EOEditingContext). After loading a nib with an EOEditingContext substituted as the default parent EOObjectStore, you should restore the default behavior by setting the default parent EOObjectStore to nil. For example:

[EOEditingContext setDefaultParentObjectStore:editingContext];
nibLoaded = [NSBundle loadNibNamed:@"thirdNib" owner:self];
[EOEditingContext setDefaultObjectStore:nil]; // Restore default

A default parent object store is global until it is changed again. For more discussion of this topic, see the chapter "Application Configurations" in the Enterprise Objects Framework Developer's Guide.

See Also: + defaultParentObjectStore

setInstancesRetainRegisteredObjects:

+ (void)setInstancesRetainRegisteredObjects:(BOOL)flag

If flag is YES, editing contexts retain their registered objects; if NO, they don't. Retaining objects is necessary to prevent enterprise objects from being finalized asynchronously on the Java side of the Java Bridge. The default value for flag is YES if an application contains Java code; NO otherwise.

setSubstitutionEditingContext:

+ (void)setSubstitutionEditingContext:(EOEditingContext *)anEditingContext

Assigns anEditingContext as the EOEditingContext to substitute for the one specified in a nib file you're about to load. Using this method causes all of the connections in your nib file to be redirected to anEditingContext. This can be useful when you want an interface loaded from a second nib file to use an existing EOEditingContext. After loading a nib with a substitution EOEditingContext, you should restore the default behavior by setting the substitution EOEditingContext to nil. For example:

[EOEditingContext setSubstitutionEditingContext:editingContext];
nibLoaded = [NSBundle loadNibNamed:@"thirdNib" owner:self];
[EOEditingContext setSubstitutionEditingContext:nil]; // Restore default

A substitution editing context is global until it is changed again. For more discussion of this topic, see the chapter "Application Configurations" in the Enterprise Objects Framework Developer's Guide.

See Also: + substitutionEditingContext

setUsesContextRelativeEncoding:

+ (void)setUsesContextRelativeEncoding:(BOOL)flag

Sets according to flag whether encodeObject:withCoder: uses context-relative encoding. For more discussion of this subject, see "Using EOEditingContext to Archive Custom Objects in Web Objects Framework" .

substitutionEditingContext

+ (EOEditingContext *)substitutionEditingContext

Returns the substitution EOEditingContext if one has been specified. Otherwise returns nil.

See Also: + setSubstitutionEditingContext:

usesContextRelativeEncoding

+ (BOOL)usesContextRelativeEncoding

Returns YES to indicate that encodeObject:withCoder: uses context relative encoding, NO otherwise. For more discussion of this subject, see "Using EOEditingContext to Archive Custom Objects in Web Objects Framework" .

Instance Methods

addEditor:

- (void)addEditor:(id)editor

Adds editor to the receiver's set of EOEditors. For more explanation, see the method description for editors and the EOEditors informal protocol specification.

See Also: - removeEditor:

arrayFaultWithSourceGlobalID:relationshipName:editingContext:

- (NSArray *)arrayFaultWithSourceGlobalID:(EOGlobalID *)globalID relationshipName:(NSString *)name editingContext:(EOEditingContext *)anEditingContext

Overrides the implementation inherited from EOObjectStore. If the objects associated with the EOGlobalID globalID are already registered in the receiver, returns those objects. Otherwise, propagates the message down the object store hierarchy, through the parent object store, ultimately to the associated EODatabaseContext. The EODatabaseContext creates and returns a to-many fault.

When a parent EOEditingContext receives this on behalf of a child EOEditingContext and the EOGlobalID globalID identifies a newly inserted object in the parent, the parent returns a copy of its object's relationship array with the member objects translated into objects in the child EOEditingContext.

For more information on faults, see the EOObjectStore, EODatabaseContext (EOAccess), EOFault, and EOFaultHandler class specifications.

committedSnapshotForObject:

- (NSDictionary *)committedSnapshotForObject:(id)object

Returns a dictionary containing a snapshot of object that reflects its committed values (that is, its values as they were last committed to the database). In other words, this snapshot represents the state of the object before any modifications were made to it. The snapshot is updated to the newest object state after a save.

See Also: - currentEventSnapshotForObject:

currentEventSnapshotForObject:

- (NSDictionary *)currentEventSnapshotForObject:(id)object

Returns a dictionary containing a snapshot of object that reflects its state as it was at the beginning of the current event loop. After the end of the current event-upon invocation of processRecentChanges-this snapshot is updated to hold the modified state of the object.

delegate

- (id)delegate

Returns the receiver's delegate.

See Also: - setDelegate:

deleteObject:

- (void)deleteObject:(id)object

Specifies that object should be removed from the receiver's parent EOObjectStore when changes are committed. At that time, the object will be removed from the uniquing tables.

See Also: - deletedObjects

deletedObjects

- (NSArray *)deletedObjects

Returns the objects that have been deleted from the receiver's object graph.

See Also: - updatedObjects, - insertedObjects

editors

- (NSArray *)editors

Returns the receiver's editors. Editors are special-purpose delegate objects that may contain uncommitted changes that need to be validated and applied to enterprise objects before the EOEditingContext saves changes. For example, EODisplayGroups (EOInterface) register themselves as editors with the EOEditingContext of their data sources so that they can save any changes in the key text field. For more information, see the EOEditors informal protocol specification and the EODisplayGroup class specification.

See Also: - addEditor:, - removeEditor:

faultForGlobalID:editingContext:

- (id)faultForGlobalID:(EOGlobalID *)globalID editingContext:(EOEditingContext *)anEditingContext

Overrides the implementation inherited from EOObjectStore. If the object associated with the EOGlobalID globalID is already registered in the receiver (or in the receiver's sharedEditingContext), this method returns that object. Otherwise, the method propagates the message down the object store hierarchy, through the parent object store, ultimately to the associated EODatabaseContext. The EODatabaseContext creates and returns a to-one fault.

For example, suppose you want the department object whose deptID has a particular value. The most efficient way to get it is to look it up by its globalID using faultForGlobalID:editingContext::

EOEntity *entity = [[[editingContext rootObjectStore] modelGroup]
        entityNamed:entityName];
EOGlobalID *gid = [entity globalIDForRow:[NSDictionary
        dictionaryWithObjectsAndKeys:deptIdentifier, @"deptID", nil]];
return [editingContext faultForGlobalID:gid editingContext:editingContext];

If the department object is already registered in the EOEditingContext, this code returns the object (without going to the database). If not, a fault for this object is created, and the object is fetched only when you trigger the fault.

In a nested editing context configuration, when a parent EOEditingContext is sent faultForGlobalID:editingContext: on behalf of a child EOEditingContext and globalID identifies a newly inserted object in the parent, the parent registers a copy of the object in the child.

For more discussion of this method, see the section "Working with Objects Across Multiple EOEditingContexts" . For more information on faults, see the EOObjectStore, EODatabaseContext (EOAccess), EOFault, and EOFaultHandler class specifications.

faultForRawRow:entityNamed:

- (id)faultForRawRow:(id)row entityNamed:(NSString *)entityName

Returns a fault for the raw row row by invoking faultForRawRow:entityNamed:editingContext: with self as the editing context.

fetchTimestamp

- (NSTimeInterval)fetchTimestamp

Returns the receiver's fetch timestamp.

forgetObject:

- (void)forgetObject:(id)object

Removes object from the uniquing tables and causes the receiver to remove itself as the object's observer. This method is invoked whenever an object being observed by an EOEditingContext is deallocated. Note that this method does not have the effect of releasing and freeing the object. You should never invoke this method directly. The correct way to remove an object from its editing context is to remove every reference to the object by refaulting any object that references it (using refaultObjects or invalidateAllObjects). Also note that this method does not have the effect of deleting an object-to delete an object you should either use the deleteObject: method or remove the object from an owning relationship.

globalIDForObject:

- (EOGlobalID *)globalIDForObject:object

Returns the EOGlobalID for object. All objects fetched from an external store are registered in an EOEditingContext along with a global identifier (EOGlobalID) that's used to uniquely identify each object to the external store. If object hasn't been registered in the EOEditingContext or in its sharedEditingContext (that is, if no match is found), this method returns nil. Objects are registered in an EOEditingContext using the insertObject: method, or, when fetching, with recordObject:globalID:.

See Also: - objectForGlobalID:

hasChanges

- (BOOL)hasChanges

Returns YES if any of the objects in the receiver's object graph have been modified-that is, if any objects have been inserted, deleted, or updated.

initWithParentObjectStore:

- initWithParentObjectStore:(EOObjectStore *)anObjectStore

Initializes the receiver with anObjectStore as its parent EOObjectStore and returns self. The receiver shares objects with the default shared editing context (if any) unless you change its shared editing context with setSharedEditingContext:.This method is the designated initializer for EOEditingContext. For more discussion of parent EOObjectStores, see "Other Classes that Participate in Object Graph Management" .

initializeObject:withGlobalID:editingContext:

- (void)initializeObject:(id)object withGlobalID:(EOGlobalID *)globalID editingContext:(EOEditingContext *)anEditingContext

Overrides the implementation inherited from EOObjectStore to build the properties for the object identified by globalID. When a parent EOEditingContext receives this on behalf of a child EOEditingContext (as represented by anEditingContext), and the globalID identifies an object instantiated in the parent, the parent returns properties extracted from its object and translated into the child's context. This ensures that a nested context "inherits" modified values from its parent EOEditingContext. If the receiver doesn't have object, the request is forwarded the receiver's parent EOObjectStore.

insertedObjects

- (NSArray *)insertedObjects

Returns the objects that have been inserted into the receiver's object graph.

See Also: - deletedObjects, - updatedObjects

insertObject:

- (void)insertObject:(id)object

Registers (by invoking insertObject:withGlobalID:) object to be inserted in the receiver's parent EOObjectStore the next time changes are saved. In the meantime, object is registered in the receiver with a temporary globalID.

insertObject:withGlobalID:

- (void)insertObject:object withGlobalID:(EOGlobalID *)globalID

Registers a new object identified by globalID that should be inserted in the parent EOObjectStore when changes are saved. Works by invoking recordObject:globalID:, unless the receiver already contains the object. Sends object the message awakeFromInsertionInEditingContext:. globalID must respond YES to isTemporary. When the external store commits object, it re-records it with the appropriate permanent globalID.

It is an error to insert an object that's already registered in an editing context unless you are effectively undeleting the object by reinserting it.

See Also: - insertObject:

invalidateAllObjects

- (void)invalidateAllObjects

Overrides the implementation inherited from EOObjectStore to discard the values of objects cached in memory and refault them, which causes them to be refetched from the external store the next time they're accessed. This method sends the message invalidateObjectsWithGlobalIDs: to the parent object store with the globalIDs of all of the objects cached in the receiver. When an EOEditingContext receives this message, it propagates the message down the object store hierarchy. EODatabaseContexts discard their snapshots for invalidated objects and broadcast an EOObjectsChangedInStoreNotification. (EODatabaseContext is defined in EOAccess.)

The final effect of this method is to refault all objects currently in memory. This refaulting in turn releases all objects not retained by your application or by an EODisplayGroup. The next time you access one of these objects, it's refetched from the database.

To flush the entire application's cache of all values fetched from an external store, use a statement such as the following:

[[editingContext rootObjectStore] invalidateAllObjects];

If you just want to discard uncommitted changes but you don't want to sacrifice the values cached in memory, use the EOEditingContext revert method, which reverses all changes and clears the undo stack. For more discussion of this topic, see the section "Methods for Managing the Object Graph" .

invalidateObjectsWithGlobalIDs:

- (void)invalidateObjectsWithGlobalIDs:(NSArray *)globalIDs

Overrides the implementation inherited from EOObjectStore to signal to the parent object store that the cached values for the objects identified by globalIDs should no longer be considered valid and that they should be refaulted. Invokes processRecentChanges before refaulting the objects. This message is propagated to any underlying object store, resulting in a refetch the next time the objects are accessed. Any related (child or peer) object stores are notified that the objects are no longer valid. All uncommitted changed to the objects are lost. For more discussion of this topic, see the section "Methods for Managing the Object Graph" .

See Also: - invalidateAllObjects

invalidatesObjectsWhenFreed

- (BOOL)invalidatesObjectsWhenFreed

Returns YES to indicate that the receiver clears and "booby-traps" all of the objects registered with it when the receiver is deallocated, NO otherwise. The default is YES. In this method, "invalidate" has a different meaning than it does in the other invalidate... methods. For more discussion of this topic, see the method description for setInvalidatesObjectsWhenFreed:.

isObjectLockedWithGlobalID:editingContext:

- (BOOL)isObjectLockedWithGlobalID:(EOGlobalID *)globalID editingContext:(EOEditingContext *)anEditingContext

Returns YES if the object identified by globalID in anEditingContext is locked, NO otherwise. This method works by forwarding the message isObjectLockedWithGlobalID:editingContext: to its parent object store.

lock

- (void)lock

Locks access to the receiver to prevent other threads from accessing it. If the receiver has a sharedEditingContext, the receiver takes a reader lock on it, as well. You should lock an editing context when you are accessing or modifying objects managed by the editing context. The thread-safety provided by Enterprise Objects Framework allows one thread to be active in each EOEditingContext and one thread to be active in each EODatabaseContext (EOAccess). In other words, multiple threads can access and modify objects concurrently in different editing contexts, but only one thread can access the database at a time (to save, fetch, or fault).

This method creates an NSAutoreleasePool that is released when unlock is called. Consequently, objects that have been autoreleased within the scope of a lock/unlock pair may not be valid after the unlock.

// The following code is WRONG!
[editingContext lock];
objects = [editingContext objectsWithFetchSpecification:fetchSpec];
title = [[objects objectAtIndex:0] valueForKey:@"title"];
[editingContext unlock]; NSLog(title); // WARNING: title might not be valid here.

// This code is CORRECT.
[editingContext lock];
objects = [editingContext objectsWithFetchSpecification:fetchSpec];
title = [[[objects objectAtIndex:0] valueForKey:@"title"] retain];
[editingContext unlock];
NSLog(title);
[title release]

Similarly, when you catch exceptions, you need to retain the local exception before raising because the exception is in the lock's pool.

lockObject:

- (void)lockObject:(id)anObject

Attempts to lock anObject in the external store. This method works by invoking lockObjectWithGlobalID:editingContext:. Raises an NSInvalidArgumentException if it can't find the globalID for anObject to pass to lockObjectWithGlobalID:editingContext:.

lockObjectWithGlobalID:editingContext:

- (void)lockObjectWithGlobalID:(EOGlobalID *)globalID editingContext:(EOEditingContext *)anEditingContext

Overrides the implementation inherited from EOObjectStore to attempt to lock the object identified by globalID in anEditingContext in the external store. Raises an NSInternalInconsistencyException if unable to obtain the lock. This method works by forwarding the message lockObjectWithGlobalID:editingContext: to its parent object store.

locksObjectsBeforeFirstModification

- (BOOL)locksObjectsBeforeFirstModification

Returns YES if the receiver locks object in the external store (with lockObject:) the first time object is modified.

messageHandler

- (id)messageHandler

Returns the EOEditingContext's message handler. A message handler is a special-purpose delegate responsible for presenting errors to the user. Typically, an EODisplayGroup (EOInterface) registers itself as the message handler for its EOEditingContext. For more information, see the EOMessageHandlers informal protocol specification.

See Also: - setMessageHandler:

objectForGlobalID:

- (id)objectForGlobalID:(EOGlobalID *)globalID

Returns the object identified by globalID, or nil if no object has been registered in the EOEditingContext (or its sharedEditingContext) with globalID.

See Also: - globalIDForObject:

objectsForSourceGlobalID:relationshipName:editingContext:

- (NSArray *)objectsForSourceGlobalID:(EOGlobalID *)globalID relationshipName:(NSString *)name editingContext:(EOEditingContext *)anEditingContext

Overrides the implementation inherited from EOObjectStore to service a to-many fault for a relationship named name. When a parent EOEditingContext receives a objectsForSourceGlobalID:relationshipName:editingContext: message on behalf of a child editing context and globalID matches an object instantiated in the parent, the parent returns a copy of its relationship array and translates its objects into the child editing context. This ensures that a child editing context "inherits" modified values from its parent. If the receiving editing context does not have the specified object or if the parent's relationship property is still a fault, the request is fowarded to its parent object store.

objectsWithFetchSpecification:

- (NSArray *)objectsWithFetchSpecification:(EOFetchSpecification *)fetchSpecification

Invokes objectsWithFetchSpecification:editingContext: with self as the EOEditingContext and returns the result.

objectsWithFetchSpecification:editingContext:

- (NSArray *)objectsWithFetchSpecification:(EOFetchSpecification *)fetchSpecification editingContext:(EOEditingContext *)anEditingContext

Overrides the implementation inherited from EOObjectStore to fetch objects from an external store according to the criteria specified by fetchSpecification and return them in an array. If one of these objects is already present in memory, this method doesn't overwrite its values with the new values from the database. This method raises an exception if an error occurs; the error message indicates the nature of the problem.

When an EOEditingContext receives this message, it forwards the message to its root object store. Typically the root object store is an EOObjectStoreCoordinator with underlying EODatabaseContexts. In this case, the object store coordinator forwards the request to the appropriate database context based on the entity name in fetchSpecification. The database context then obtains an EODatabaseChannel and performs the fetch, registering all fetched objects in anEditingContext or in the receiver if anEditingContext isn't provided. (Note that EODatabaseContext and EODatabaseChannel are defined in EOAccess.)

objectWillChange:

- (void)objectWillChange:(id)object

This method is automatically invoked when any of the objects registered in the receiver invokes its willChange method. This method is EOEditingContext's implementation of the EOObserving protocol.

parentObjectStore

- (EOObjectStore *)parentObjectStore

Returns the EOObjectStore from which the receiver fetches and to which it saves objects.

processRecentChanges

- (void)processRecentChanges

Forces the receiver to process pending insertions, deletions, and updates. Normally, when objects are changed, the processing of the changes is deferred until the end of the current event. At that point, an EOEditingContext moves objects to the inserted, updated, and deleted lists, delete propagation is performed, undos are registered, and EOObjectsChangedInStoreNotification and EOObjectsChangedInEditingContextNotification are posted. You can use this method to explicitly force changes to be processed. An EOEditingContext automatically invokes this method on itself before performing certain operations such as saveChanges.

propagatesDeletesAtEndOfEvent

- (BOOL)propagatesDeletesAtEndOfEvent

Returns YES if the receiver propagates deletes at the end of the event in which a change was made, NO if it propagates deletes only right before saving changes. The default is YES.

recordObject:globalID:

- (void)recordObject:(id)object globalID:(EOGlobalID *)globalID

Makes the receiver aware of an object identified by globalID existing in its parent object store. EOObjectStores (such as the access layer's EODatabaseContext) usually invoke this method for each object fetched. When it receives this message, the receiver enters the object in its uniquing table and registers itself as an observer of the object.

redo:

- (void)redo:(id)sender

Sends editingContextWillSaveChanges: messages to the receiver's editors, and sends a redo message to the receiver's NSUndoManager, asking it to reverse the latest undo operation applied to objects in the object graph.

See Also: - undo:

refault:

- (void)refault:(id)sender

Sends editingContextWillSaveChanges: messages to the receiver's editors, and invokes refaultObjects.

refaultObject:withGlobalID:editingContext:

- (void)refaultObject:(id)anObject withGlobalID:(EOGlobalID *)globalID editingContext:(EOEditingContext *)anEditingContext

Overrides the implementation inherited from EOObjectStore to refault the enterprise object object identified by globalID in anEditingContext. This method should be used with caution since refaulting an object does not remove the object snapshot from the undo stack. Objects that have been newly inserted or deleted should not be refaulted.

The main purpose of this method is to break retain cycles between enterprise objects. This means that you might still need to break retain cycles to help keep your application's memory in check. For example, suppose you have an Employee object that has a to-one relationship to its Department, and the Department object in turn has an array of Employee objects. You can use this method to break the retain cycle. Note that retain cycles are automatically broken if the EOEditingContext is finalized. For more discussion of this topic, see the section "Methods for Managing the Object Graph" .

refaultObjects

- (void)refaultObjects

Refaults all objects cached in the receiver that haven't been inserted, deleted, or updated. Invokes processRecentChanges, then invokes refaultObject:withGlobalID:editingContext: for all objects that haven't been inserted, deleted, or updated. For more discussion of this topic, see the section "Methods for Managing the Object Graph" in the class description.

refetch:

- (void)refetch:(id)sender

Sends editingContextWillSaveChanges: messages to the receiver's editors, and invokes the invalidateAllObjects method.

registeredObjects

- (NSArray *)registeredObjects

Returns the enterprise objects managed by the receiver.

removeEditor:

- (void)removeEditor:(id)editor

Unregisters editor from the receiver. For more discussion of EOEditors, see the editors method description and the EOEditors informal protocol specification.

See Also: - addEditor:

reset

- (void)reset

Forgets all objects and makes them unusable. If instancesRetainRegisteredObjects is YES, an invocation of this method is necessary to get the editing context to release all of its registered objects. This method also resets the fetchTimestamp as if the editing context were just initialized.

revert

- (void)revert

Removes everything from the undo stack, discards all insertions and deletions, and restores updated objects to their last committed values. Does not refetch from the database. Note that revert doesn't automatically cause higher level display groups (WebObject's WODisplayGroups or the interface layer's EODisplayGroups) to refetch. Display groups that allow insertion and deletion of objects need to be explicitly synchronized whenever this method is invoked on their EOEditingContext.

See Also: - invalidateAllObjects

revert:

- (void)revert:(id)sender

Sends editingContextWillSaveChanges: messages to the receiver's editors, and invokes revert.

rootObjectStore

- (EOObjectStore *)rootObjectStore

Returns the EOObjectStore at the base of the object store hierarchy (usually an EOObjectStoreCoordinator).

saveChanges

- (void)saveChanges

Sends editingContextWillSaveChanges: messages to the receiver's editors, and commits changes made in the receiver to its parent EOObjectStore by sending it the message saveChangesInEditingContext:. If the parent is an EOObjectStoreCoordinator, it guides its EOCooperatingObjectStores, typically EODatabaseContexts, through a multi-pass save operation (see the EOObjectStoreCoordinator class specification for more information). If a database error occurs, an exception is raised. The error message indicates the nature of the problem.

saveChanges:

- (void)saveChanges:(id)sender

This action method invokes saveChanges, handling an exception by passing it to the message handler. For example, if a validation error occurs, the message handler (usually an EODisplayGroup) presents an alert panel with the text of the validation exception.

See Also: - editingContext:presentErrorMessage:(EOMessageHandlers), - editingContext:shouldPresentException: (EOEditingContext Delegate)

saveChangesInEditingContext:

- (void)saveChangesInEditingContext:(EOEditingContext *)anEditingContext

Overrides the implementation inherited from EOObjectStore to tell the receiver's EOObjectStore to accept changes from a child EOEditingContext. This method shouldn't be invoked directly. It's invoked by a nested EOEditingContext when it's committing changes to a parent EOEditingContext. The receiving parent EOEditingContext incorporates all changes from the nested EOEditingContext into its own copies of the objects, but it doesn't immediately save those changes to the database. If the parent itself is later sent saveChanges, it propagates any changes received from the child along with any other changes to its parent EOObjectStore. Raises an exception if an error occurs; the error message indicates the nature of the problem.

setDelegate:

- (void)setDelegate:(id)anObject

Set the receiver's delegate to be anObject, without retaining it.

See Also: - delegate

setFetchTimestamp:

- (void)setFetchTimestamp:(NSTimeInterval)timestamp

Sets the receiver's fetch timestamp. When an editing context fetches objects from its parent object store, the parent object store can use the timestamp to determine whether to use cached data or to refetch the most current values. An editing context prefers that fetched values are at least as recent as its fetch timestamp. Note that the parent object store is free to ignore the timestamp; so this value should be considered a hint or request and not a guarantee.

Note: Changing the fetch timestamp has no effect on existing objects in the editing context; it can affect only subsequent fetches. To refresh existing objects, invoke refaultObjects before you invoke setFetchTimestamp:.

The initial value for the fetch timestamp of a new non-nested editing context is the current time less the defaultFetchTimestampLag. A nested editing context always uses its parent's fetch timestamp. setFetchTimestamp: raises if it's invoked on a nested editing context.

setSharedEditingContext:

- (void)setSharedEditingContext:(EOSharedEditingContext *)sharedEC

Sets the receiver's shared editing context. Raises if the receiver and sharedEC both contain the same object (otherwise object uniquing would be violated) or if sharedEC is not an instance of the EOSharedEditingContext class.By default, an editing context that has no shared editing context listens for EODefaultSharedEditingContextWasInitializedNotifications. If a notification is posted while the context has no registered objects, the editing context sets its shared editing context to the newly initialized default shared editing context. Invoke this method with nil to remove the receiver as an observer of this notification and to prevent the context from accessing any objects in the default shared editing context.

setInvalidatesObjectsWhenFreed:

- (void)setInvalidatesObjectsWhenFreed:(BOOL)flag

Sets according to flag whether the receiver clears and "booby-traps" all of the objects registered with it when the receiver is deallocated. If an editing context invalidates objects when it's deallocated, it sends a clearProperties message to all of its objects, thereby breaking any retain cycles between objects that would prevent them from being deallocated. This method leaves the objects in a state in which sending them any message other than dealloc or release raises an exception.

The default is YES, and as a general rule, this setting must be YES for enterprise objects with cyclic references to be freed when their EOEditingContext is freed.

Note that the word "invalidate" in this method name has a different meaning than it does in the other invalidate... methods, which discard object values and refault them.

See Also: - invalidatesObjectsWhenFreed

setLocksObjectsBeforeFirstModification:

- (void)setLocksObjectsBeforeFirstModification:(BOOL)flag

Sets according to flag whether the receiver locks object in the external store (with lockObject:) the first time object is modified. The default is NO. If flag is YES, an exception will be raised if a lock can't be obtained when object invokes willChange. There are two reasons a lock might fail: because the row is already locked in the server, or because your snapshot is out of date. If your snapshot is out of date, you can explicitly refetch the object using an EOFetchSpecification with setRefreshesRefetchedObjects: set to YES. To handle the exception, you can implement the EODatabaseContext delegate method databaseContextShouldRaiseExceptionForLockFailure:.

You should avoid using this method or pessimistic locking in an interactive end-user application. For example, a user might make a change in a text field and neglect to save it, thereby leaving the data locked in the server indefinitely. Consider using optimistic locking or application level explicit check-in/check-out instead.

setMessageHandler:

- (void)setMessageHandler:(id)handler

Set the receiver's message handler to be handler.

See Also: - messageHandler

setPropagatesDeletesAtEndOfEvent:

- (void)setPropagatesDeletesAtEndOfEvent:(BOOL)flag

Sets according to flag whether the receiver propagates deletes at the end of the event in which a change was made, or only just before saving changes.

If flag is YES, deleting an enterprise object triggers delete propagation at the end of the event in which the deletion occurred (this is the default behavior). If flag is NO, delete propagation isn't performed until saveChanges is invoked.

You can delete enterprise objects explicitly by using the deleteObject: method or implicitly by removing the enterprise object from an owning relationship. Delete propagation uses the delete rules in the EOClassDescription to determine whether objects related to the deleted object should also be deleted (for more information, see the EOClassDescription class specification and the EOEnterpriseObject interface informal protocol specification). If delete propagation fails (that is, if an enterprise object refuses to be deleted-possibly due to a deny rule), all changes made during the event are rolled back.

See Also: - propagatesDeletesAtEndOfEvent

setStopsValidationAfterFirstError:

- (void)setStopsValidationAfterFirstError:(BOOL)flag

Sets according to flag whether the receiver stops validating after the first error is encountered, or continues for all objects (validation typically occurs during a save operation). The default is YES. Setting it to NO is useful if the delegate implements editingContext:shouldPresentException: to handle the presentation of aggregate exceptions.

See Also: - stopsValidationAfterFirstError

setUndoManager:

- (void)setUndoManager:(NSUndoManager *)undoManager

Sets the receiver's NSUndoManager to undoManager. You might invoke this method with nil if your application doesn't need undo and you want to avoid the overhead of an undo stack. For more information on editing context's undo support, see the section "Undo and Redo" .

See Also: - undoManager

sharedEditingContext

- (EOSharedEditingContext *)sharedEditingContext

Returns the shared editing context used by the receiver.

stopsValidationAfterFirstError

- (BOOL)stopsValidationAfterFirstError

Returns YES to indicate that the receiver should stop validating after it encounters the first error, or NO to indicate that it should continue for all objects.

tryToSaveChanges

- (NSException *)tryToSaveChanges

Invokes the saveChanges method, and catches and returns any exceptions that are raised.

undo:

- (void)undo:(id)sender

Sends editingContextWillSaveChanges: messages to the receiver's editors, and sends an undo message to the receiver's NSUndoManager, asking it to reverse the latest uncommitted changes applied to objects in the object graph. For more information on editing context's undo support, see the section "Undo and Redo" .

See Also: redo:

undoManager

- (NSUndoManager *)undoManager

Returns the receiver's NSUndoManager.

See Also: - setUndoManager:

unlock

- (void)unlock

Unlocks access to the receiver so that other threads may access it. If the receiver has a sharedEditingContext, the receiver unlocks a reader lock on the shared context.

See Also: - lock

updatedObjects

- (NSArray *)updatedObjects

Returns the objects in the receiver's object graph that have been updated.

See Also: - deletedObjects, - insertedObjects

Notifications

The following notifications are declared (except where otherwise noted) and posted by EOEditingContext.

EOEditingContextDidSaveChangesNotification

This notification is broadcast after changes are saved to the EOEditingContext's parent EOObjectStore. The notification contains:

Notification Object: The EOEditingContext

userInfo: A dictionary with the following keys (constants defined in EOObjectStore.h) and values

Key	Value
EOUpdatedKey	An NSArray containing the changed objects
EOInsertedKey	An NSArray containing the inserted objects
EODeletedKey	An NSArray containing the deleted objects

EOInvalidatedAllObjectsInStoreNotification

This notification is defined by EOObjectStore. When posted by an EOEditingContext, it's the result of the editing context invalidating all its objects. When an EOEditingContext receives an EOInvalidatedAllObjectsInStoreNotification from its parent EOObjectStore, it clears its lists of inserted, updated, and deleted objects, and resets its undo stack. The notification contains:

Notification Object	The EOEditingContext
userInfo Dictionary	None.

An interface layer EODisplayGroup (not a WebObjects WODisplayGroup) listens for this notification to refetch its contents. See the EOObjectStore class specification for more information on this notification.

EOObjectsChangedInStoreNotification

This notification is defined by EOObjectStore. When posted by an EOEditingContext, it's the result of the editing context processing objectWillChange: observer notifications in processRecentChanges, which is usually as the end of the event in which the changes occurred. See the EOObjectStore class specification for more information on EOObjectsChangedInStoreNotification.

This notification contains:

Notification Object: The EOEditingContext

userInfo: A dictionary with the following keys (constants defined in EOObjectStore.h) and values

Key	Value
EOUpdatedKey	An NSArray of EOGlobalIDs for objects whose properties have changed. A receiving EOEditingContext typically responds by refaulting the objects.
EOInsertedKey	An NSArray of EOGlobalIDs for objects that have been inserted into the EOObjectStore.
EODeletedKey	An NSArray of EOGlobalIDs for objects that have been deleted from the EOObjectStore.
EOInvalidatedKey	An NSArray of EOGlobalIDs for objects that have been turned into faults. Invalidated objects are those for which the cached view should no longer be trusted. Invalidated objects should be refaulted so that they are refetched when they're next examined.

EOObjectsChangedInEditingContextNotification

EOCONTROL_EXTERN NSString *EOObjectsChangedInEditingContextNotification

This notification is broadcast whenever changes are made in an EOEditingContext. It's similar to EOObjectsChangedInStoreNotification, except that it contains objects rather than globalIDs. The notification contains:

Notification Object: The EOEditingContext

userInfo: A dictionary with the following keys (constants defined in EOObjectStore.h) and values

Key	Value
EOUpdatedKey	An NSArray containing the changed objects
EODeletedKey	An NSArray containing the deleted objects
EOInsertedKey	An NSArray containing the inserted objects
EOInvalidatedKey	An NSArray containing invalidated objects.

Interface layer EODisplayGroups (not WebObjects WODisplayGroups) listen for this notification to redisplay their contents.