WebObjects 5.2

com.webobjects.eocontrol
Class EOEditingContext

java.lang.Object
  |
  +--com.webobjects.eocontrol.EOObjectStore
        |
        +--com.webobjects.eocontrol.EOEditingContext
All Implemented Interfaces:
EOKeyValueArchiving, EOObserving, NSDisposable, NSLocking, Serializable
Direct Known Subclasses:
EOSharedEditingContext

public class EOEditingContext
extends EOObjectStore
implements EOObserving, NSLocking, EOKeyValueArchiving, Serializable

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


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.
objectsWithFetchSpecification Fetches a set of objects into this context.
saveChanges Commits changes made in this context to its parent EOObjectStore.
faultForGlobalID Given a globalID, returns its associated object or creates and returns a fault for it.
globalIDForObject Given an object, returns its globalID.
revert Throws away all pending changes and restores this context to its previously commited state.


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 interface) 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:


See Also:
insertObject(com.webobjects.eocontrol.EOEnterpriseObject), deleteObject(com.webobjects.eocontrol.EOEnterpriseObject), objectsWithFetchSpecification(com.webobjects.eocontrol.EOFetchSpecification, com.webobjects.eocontrol.EOEditingContext), saveChanges(), faultForGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), globalIDForObject(com.webobjects.eocontrol.EOEnterpriseObject), revert(), EOEnterpriseObject, EOObjectStore, EOObjectStoreCoordinator, EOCooperatingObjectStore, EOObserving, Serialized Form

Inner Class Summary
static interface EOEditingContext.Delegate
          The EOEditingContext.Delegate interface defines methods that an EOEditingContext can invoke in its delegate.
static class EOEditingContext.EditingContextEvent
          A subclass provided to track events triggered by EOEditingContexts.
static interface EOEditingContext.Editor
          An interface for objects that act as higher-level editors of the objects an EOEditingContext contains.
static interface EOEditingContext.MessageHandler
          This interface is used for error reporting and determining fetch limits.
 
Inner classes inherited from class com.webobjects.eocontrol.EOKeyValueArchiving
EOKeyValueArchiving.Awaking, EOKeyValueArchiving.FinishInitialization, EOKeyValueArchiving.Support
 
Field Summary
static String EditingContextDidSaveChangesNotification
          This notification is broadcast after changes are saved to the EOEditingContext's parent EOObjectStore.
static int EditingContextFlushChangesRunLoopOrdering
          Messages with lower order numbers are processed before messages with higher order numbers.
static String ObjectsChangedInEditingContextNotification
          This notification is broadcast whenever changes are made in an EOEditingContext.
 
Fields inherited from class com.webobjects.eocontrol.EOObjectStore
DeletedKey, InsertedKey, InvalidatedAllObjectsInStoreNotification, InvalidatedKey, ObjectsChangedInStoreNotification, UpdatedKey
 
Fields inherited from interface com.webobjects.foundation.NSLocking
OneCentury, OneDay, OneHour, OneMinute, OneSecond, OneWeek, OneYear
 
Constructor Summary
EOEditingContext()
          Creates a new EOEditingContext object with the default parent object store as its parent object store.
EOEditingContext(EOObjectStore parent)
          Creates a new EOEditingContext object with parent as its parent object store.
 
Method Summary
 void addEditor(Object editor)
          Adds editor to this EOEditingContext's set of EOEditingContext.Editors.
 NSArray arrayFaultWithSourceGlobalID(EOGlobalID gid, String name, EOEditingContext context)
          Overrides the implementation inherited from EOObjectStore.
 NSDictionary committedSnapshotForObject(EOEnterpriseObject 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).
 NSDictionary currentEventSnapshotForObject(EOEnterpriseObject object)
          Returns a dictionary containing a snapshot of object that reflects its state as it was at the beginning of the current event loop.
static Object decodeWithKeyValueUnarchiver(EOKeyValueUnarchiver unarchiver)
           
static long defaultFetchTimestampLag()
           
static EOObjectStore defaultParentObjectStore()
          Returns the EOObjectStore that is the default parent object store for new editing contexts.
 Object delegate()
           
 NSArray deletedObjects()
           
 void deleteObject(EOEnterpriseObject object)
          Specifies that object should be removed from this EOEditingContext's parent EOObjectStore when changes are committed.
 void dispose()
          Invoked when the receiver should prepare itself for destruction.
 void editingContextDidForgetObjectWithGlobalID(EOEditingContext context, EOGlobalID gid)
          Invoked to inform the EOObjectStore that it can stop keeping data about an object it passed to a child.
 NSArray editors()
          Returns this EOEditingContext's list of editors.
 boolean editorsHaveChanges()
           
static void encodeObjectWithCoder(EOEnterpriseObject object, NSCoder coder)
          Invoked by an EOEnterpriseObject object to ask the EOEditingContext to encode object using encoder.
 void encodeWithKeyValueArchiver(EOKeyValueArchiver archiver)
          Deprecated. Use Java Serialization instead.
 EOEnterpriseObject faultForGlobalID(EOGlobalID gid, EOEditingContext context)
          Overrides the implementation inherited from EOObjectStore.
 EOEnterpriseObject faultForRawRow(NSDictionary row, String entityName)
          Returns a fault for the raw row row.
 EOEnterpriseObject faultForRawRow(NSDictionary row, String entityName, EOEditingContext context)
          Returns a fault for the raw row row by invoking faultForRawRow on this EOEditingContext's parent EOObjectStore with context as the editing context.
 long fetchTimestamp()
          The fetch timestamp is a hint to refresh stale data on a subsequent fetch.
protected  void finalize()
           
 void forgetObject(EOEnterpriseObject object)
          Removes object from the uniquing tables and causes this EOEditingContext to remove itself from the object's list of observers.
 EOGlobalID globalIDForObject(EOEnterpriseObject object)
          Returns the EOGlobalID associated with object in this EOEditingContext or its shared context.
 boolean hasChanges()
           
 void initializeObject(EOEnterpriseObject object, EOGlobalID gid, EOEditingContext context)
          Overrides the implementation inherited from EOObjectStore to build the properties for the object identified by gid.
static Object initObjectWithCoder(EOEnterpriseObject object, NSCoder coder)
          Invoked by an EOEnterpriseObject object to ask the EOEditingContext to initialize object from data in decoder.
 NSArray insertedObjects()
           
 void insertObject(EOEnterpriseObject object)
          Registers (by invoking insertObjectWithGlobalID) object to be inserted in this EOEditingContext's parent EOObjectStore the next time changes are saved.
 void insertObjectWithGlobalID(EOEnterpriseObject object, EOGlobalID gid)
          Registers a new object identified by globalID that should be inserted in the parent EOObjectStore when changes are saved.
static boolean instancesRetainRegisteredObjects()
           
 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.
 void invalidateObjectsWithGlobalIDs(NSArray gids)
          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.
 boolean invalidatesObjectsWhenFinalized()
          This method should not be used.
 Object invokeRemoteMethod(EOEditingContext context, EOGlobalID gid, String methodName, Class[] argumentTypes, Object[] arguments)
          Executes a remote method on the server.
 boolean isObjectLockedWithGlobalID(EOGlobalID gid, EOEditingContext context)
          Returns true if the object identified by gid in context is locked, false otherwise.
 void lock()
          Locks access to this EOEditingContext to prevent other threads from accessing it.
 void lockObject(EOEnterpriseObject object)
          Attempts to lock object in the external store.
 void lockObjectStore()
           
 void lockObjectWithGlobalID(EOGlobalID gid, EOEditingContext context)
          Overrides the implementation inherited from EOObjectStore to attempt to lock the object identified by gid in context in the external store.
 boolean locksObjectsBeforeFirstModification()
          Returns true if this EOEditingContext locks object in the external store with lockObject the first time object is modified.
 Object messageHandler()
          Returns the EOEditingContext's message handler.
 EOEnterpriseObject objectForGlobalID(EOGlobalID gid)
          Returns the EOEnterpriseObject associated with gid in this EOEditingContext or its shared context, or null if no such object exists.
 NSArray objectsForSourceGlobalID(EOGlobalID gid, String name, EOEditingContext context)
          Overrides the implementation inherited from EOObjectStore to service a to-many fault for a relationship named name.
 NSArray objectsWithFetchSpecification(EOFetchSpecification fetchSpecification)
          Equivalent to :
 NSArray objectsWithFetchSpecification(EOFetchSpecification fetchSpec, EOEditingContext context)
          Overrides the implementation inherited from EOObjectStore to fetch objects from an external store according to the criteria specified by fetchSpec and return them in an array.
 void objectWillChange(Object object)
          This method is automatically invoked when any of the objects registered in this EOEditingContext invokes its willChange method.
 EOObjectStore parentObjectStore()
           
 void processRecentChanges()
          Forces this EOEditingContext to process pending insertions, deletions, and updates.
 boolean propagatesDeletesAtEndOfEvent()
          Returns true if this EOEditingContext propagates deletes at the end of the event in which a change was made, false if it propagates deletes only right before saving changes.
protected  Object readResolve()
           
 void recordObject(EOEnterpriseObject object, EOGlobalID gid)
          Makes this EOEditingContext aware of an object identified by gid existing in its parent object store.
 void redo()
          Sends editingContextWillSaveChanges messages to this EOEditingContext's editors, and sends a redo message to its NSUndoManager, asking it to reverse the latest undo operation applied to objects in the object graph.
 void refaultAllObjects()
          Refaults all objects cached in this EOEditingContext that have not been inserted, deleted, or updated.
 void refaultObject(EOEnterpriseObject object)
           
 void refaultObject(EOEnterpriseObject object, EOGlobalID gid, EOEditingContext ctx)
          Overrides the implementation inherited from EOObjectStore to refault the enterprise object object identified by gid in ctx.
 void refaultObjects()
          Deprecated. Use refaultAllObjects instead.
 void refetch()
          Deprecated. Use refaultAllObjects instead.
 void refreshAllObjects()
           
 void refreshObject(EOEnterpriseObject eo)
           
 NSArray registeredObjects()
           
 void removeEditor(Object editor)
          Unregisters editor from this EOEditingContext.
 void reset()
          Forgets all objects and makes them unusable.
 boolean retainsRegisteredObjects()
           
 void revert()
          Sends editingContextWillSaveChanges messages to the EOEditingContext's editors, and removes everything from the undo stack, discards all insertions and deletions, and restores updated objects to their last committed values.
 EOObjectStore rootObjectStore()
          Returns the EOObjectStore at the base of the object store hierarchy (usually an EOObjectStoreCoordinator).
 void saveChanges()
          Sends editingContextWillSaveChanges messages to this EOEditingContext's editors, and commits changes made 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 If a database error occurs, a RuntimeException is thrown.
 void saveChanges(Object sender)
          Deprecated. Use saveChanges() instead.
 void saveChangesInEditingContext(EOEditingContext context)
          Overrides the implementation inherited from EOObjectStore to tell this EOEditingContext's EOObjectStore to accept changes from a child EOEditingContext.
static void setDefaultFetchTimestampLag(long lag)
          Sets the default timestamp lag for newly instantiated editing contexts to lag.
static void setDefaultParentObjectStore(EOObjectStore store)
          Sets the default parent EOObjectStore to store.
 void setDelegate(Object delegate)
          Set this EOEditingContext's delegate to be delegate.
 void setFetchTimestamp(long timestamp)
          Sets the receiver's fetch timestamp.
static void setInstancesRetainRegisteredObjects(boolean flag)
           
 void setInvalidatesObjectsWhenFinalized(boolean yn)
          This method should not be used.
 void setLocksObjectsBeforeFirstModification(boolean yn)
          Sets according to yn whether this EOEditingContext locks object in the external store (with lockObject) the first time object is modified.
 void setMessageHandler(Object handler)
          Set this EOEditingContext's message handler to be handler.
 void setPropagatesDeletesAtEndOfEvent(boolean propagatesDeletesAtEndOfEvent)
          Sets according to propagatesDeletesAtEndOfEvent whether this EOEditingContext propagates deletes at the end of the event in which a change was made, or only just before saving changes.
 void setRetainsRegisteredObjects(boolean flag)
           
 void setSharedEditingContext(EOSharedEditingContext sharedEC)
          Sets this EOEditingContext shared editing context.
 void setStopsValidationAfterFirstError(boolean yn)
          Sets according to yn whether this EOEditingContext stops validating after the first error is encountered, or continues for all objects (validation typically occurs during a save operation).
static void setSubstitutionEditingContext(EOEditingContext ec)
          Assigns ec as the global replacement EOEditingContext to substitute for one in the process of being de-serialized.
 void setUndoManager(NSUndoManager undoManager)
          Sets the receiver's NSUndoManager to undoManager.
static void setUsesContextRelativeEncoding(boolean flag)
          Sets according to flag whether Serialization or use context relative encoding.
 EOSharedEditingContext sharedEditingContext()
           
 boolean stopsValidationAfterFirstError()
           
static EOEditingContext substitutionEditingContext()
          Returns the global substitution EOEditingContext if you have been specified.
 Throwable tryToSaveChanges()
          Deprecated. Use saveChanges() instead.
 void undo()
          Sends editingContextWillSaveChanges messages to this EOEditingContext's editors, and sends an undo message to its NSUndoManager, asking it to reverse the latest uncommitted changes applied to objects in the object graph.
 NSUndoManager undoManager()
           
 void unlock()
          Unlocks access to this EOEditingContext so that other threads may access it.
 void unlockObjectStore()
           
 NSArray updatedObjects()
          Returns an array of objects in this EOEditingContext's object graph that have been updated.
static boolean usesContextRelativeEncoding()
          Returns true to indicate whether Serialization and use context relative encoding, false otherwise.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EditingContextDidSaveChangesNotification

public static final String EditingContextDidSaveChangesNotification
This notification is broadcast after changes are saved to the EOEditingContext's parent EOObjectStore. The notification contains: a notification object; an EOEditingContext; a userInfo dictionary with the following keys (constants) and values:
Key Value
EOObjectStore.UpdatedKey An NSArray containing the changed objects
EOObjectStore.InsertedKey An NSArray containing the inserted objects
EOObjectStore.DeletedKey An NSArray containing the deleted objects


EditingContextFlushChangesRunLoopOrdering

public static final int 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 also defines String constants for the names of the notifications it posts.

See Also:
EditingContextDidSaveChangesNotification, ObjectsChangedInEditingContextNotification

ObjectsChangedInEditingContextNotification

public static final String ObjectsChangedInEditingContextNotification
This notification is broadcast whenever changes are made in an EOEditingContext. It's similar to ObjectsChangedInStoreNotification, except that it contains objects rather than globalIDs. The notification contains: a notification object; an EOEditingContext; a userInfo dictionary with the following keys (constants) and values:
Key Value
EOObjectStore.UpdatedKey An NSArray containing the changed objects
EOObjectStore.DeletedKey An NSArray containing the deleted objects
EOObjectStore.InsertedKey An NSArray containing the inserted objects
EOObjectStore.InvalidatedKey An NSArray containing invalidated objects.

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


Constructor Detail

EOEditingContext

public EOEditingContext(EOObjectStore parent)
Creates a new EOEditingContext object with parent as its parent object store. Shares objects with the default shared editing context (if any) unless you change its shared editing context with setSharedEditingContext.
Parameters:
parent - the parent object store of new EOEditingContext object created
See Also:
parentObjectStore(), defaultParentObjectStore(), setSharedEditingContext(com.webobjects.eocontrol.EOSharedEditingContext), EOObjectStore

EOEditingContext

public EOEditingContext()
Creates a new EOEditingContext object with the default parent object store as its parent object store. Shares objects with the default shared editing context (if any) unless you change its shared editing context with setSharedEditingContext.
See Also:
parentObjectStore(), defaultParentObjectStore(), setSharedEditingContext(com.webobjects.eocontrol.EOSharedEditingContext), EOObjectStore
Method Detail

addEditor

public void addEditor(Object editor)
Adds editor to this EOEditingContext's set of EOEditingContext.Editors.
Parameters:
editor - the editor to be added to the editors set
See Also:
editors(), removeEditor(java.lang.Object), EOEditingContext.Editor

arrayFaultWithSourceGlobalID

public NSArray arrayFaultWithSourceGlobalID(EOGlobalID gid,
                                            String name,
                                            EOEditingContext context)
Overrides the implementation inherited from EOObjectStore. If the objects associated with gid are already registered in this EOEditingContext, it returns an array of those objects. Otherwise, this method propagates the message up 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 gid 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.

Overrides:
arrayFaultWithSourceGlobalID in class EOObjectStore
Parameters:
gid - EOGlobalID of the source object of the relationship
name - name of the relationship
context - context in which to register the fault
Returns:
array of objects associated with gid for the relationship name
See Also:
faultForGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), EOObjectStore.arrayFaultWithSourceGlobalID(com.webobjects.eocontrol.EOGlobalID, java.lang.String, com.webobjects.eocontrol.EOEditingContext)

committedSnapshotForObject

public NSDictionary committedSnapshotForObject(EOEnterpriseObject 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). 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.
Parameters:
object - Snapshot of this reflecting its committed values has to be returned.
Returns:
a dictionary containing a snapshot of object
See Also:
currentEventSnapshotForObject(com.webobjects.eocontrol.EOEnterpriseObject)

currentEventSnapshotForObject

public NSDictionary currentEventSnapshotForObject(EOEnterpriseObject 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.
Parameters:
object - Snapshot of this reflecting its state at the beginning of the current event loop has to be returned.
Returns:
a dictionary containing a snapshot of object
See Also:
committedSnapshotForObject(com.webobjects.eocontrol.EOEnterpriseObject), processRecentChanges()

decodeWithKeyValueUnarchiver

public static Object decodeWithKeyValueUnarchiver(EOKeyValueUnarchiver unarchiver)

defaultFetchTimestampLag

public static long defaultFetchTimestampLag()
Returns:
the default timestamp lag in milliseconds
See Also:
setDefaultFetchTimestampLag(long)

defaultParentObjectStore

public static 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 static method defaultCoordinator.
Returns:
the EOObjectStore that is the default parent object store
See Also:
setDefaultParentObjectStore(com.webobjects.eocontrol.EOObjectStore), substitutionEditingContext(), usesContextRelativeEncoding(), Serializable

delegate

public Object delegate()
Returns:
the current delegate.
See Also:
setDelegate(java.lang.Object)

deleteObject

public void deleteObject(EOEnterpriseObject object)
Specifies that object should be removed from this EOEditingContext's parent EOObjectStore when changes are committed. At that time, the object will be removed from the uniquing tables.
Parameters:
object - the object to be deleted
See Also:
deletedObjects()

deletedObjects

public NSArray deletedObjects()
Returns:
the objects that have been deleted from this EOEditingContext's object graph
See Also:
updatedObjects(), insertedObjects()

dispose

public void dispose()
Description copied from interface: NSDisposable
Invoked when the receiver should prepare itself for destruction. Implementations of this method should break connections that other objects have to the receiver, including unregistering for notifications, resigning as other objects' delegates, release locks and system resources, close files, and any other clean up operations.
Overrides:
dispose in class EOObjectStore

editingContextDidForgetObjectWithGlobalID

public void editingContextDidForgetObjectWithGlobalID(EOEditingContext context,
                                                      EOGlobalID gid)
Invoked to inform the EOObjectStore that it can stop keeping data about an object it passed to a child. This method should not be invoked directly. It is invoked automatically by the Framework.
Overrides:
editingContextDidForgetObjectWithGlobalID in class EOObjectStore
Parameters:
context - An EOEditingContext object manages a graph of enterprise objects in an application.
gid - a compact, universal identifier for a persistent object
See Also:
EOObjectStore.editingContextDidForgetObjectWithGlobalID(com.webobjects.eocontrol.EOEditingContext, com.webobjects.eocontrol.EOGlobalID)

editors

public NSArray editors()
Returns this EOEditingContext's list of 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.
Returns:
the receiver's editors
See Also:
addEditor(java.lang.Object), removeEditor(java.lang.Object), EOEditingContext.Editor

editorsHaveChanges

public boolean editorsHaveChanges()
Returns:
true if any of the editors associated with this EOEditingContext have pending changes.
See Also:
EOEditingContext.Editor, addEditor(java.lang.Object)

encodeObjectWithCoder

public static void encodeObjectWithCoder(EOEnterpriseObject object,
                                         NSCoder coder)
Invoked by an EOEnterpriseObject object to ask the EOEditingContext to encode object using encoder.
Parameters:
object - object to be encoded
coder - the target NSCoder
See Also:
Serializable, usesContextRelativeEncoding(), initObjectWithCoder(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.foundation.NSCoder)

encodeWithKeyValueArchiver

public void encodeWithKeyValueArchiver(EOKeyValueArchiver archiver)
Deprecated. Use Java Serialization instead.

On an EOEditingContext, this method does nothing.
Specified by:
encodeWithKeyValueArchiver in interface EOKeyValueArchiving
Parameters:
archiver - the EOKeyValueArchiver
See Also:
EOKeyValueArchiver

faultForGlobalID

public EOEnterpriseObject faultForGlobalID(EOGlobalID gid,
                                           EOEditingContext context)
Overrides the implementation inherited from EOObjectStore. If the object associated with globalID is already registered in this EOEditingContext (or its shared context), this method returns that object. Otherwise, the method propagates the message up 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. If the department object is already registered in the EOEditingContext, faultForGlobalID returns that object (without going to the database). If not, a fault for this object is created, and the object is fetched from the database only when you trigger the fault. In a nested editing context configuration, where a parent EOEditingContext is sent faultForGlobalID 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 information refer to: "Working with Objects Across Multiple EOEditingContexts"

Overrides:
faultForGlobalID in class EOObjectStore
Parameters:
gid - the identifier for the desired object
context - the EOEditingContext to search and register the fault
Returns:
object associated with the EOGlobalID
See Also:
EOObjectStore.faultForGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), EOUtilities.localInstanceOfObject(com.webobjects.eocontrol.EOEditingContext, com.webobjects.eocontrol.EOEnterpriseObject), EODatabaseContext, arrayFaultWithSourceGlobalID(com.webobjects.eocontrol.EOGlobalID, java.lang.String, com.webobjects.eocontrol.EOEditingContext), EOFaultHandler

faultForRawRow

public EOEnterpriseObject faultForRawRow(NSDictionary row,
                                         String entityName,
                                         EOEditingContext context)
Returns a fault for the raw row row by invoking faultForRawRow on this EOEditingContext's parent EOObjectStore with context as the editing context.
Overrides:
faultForRawRow in class EOObjectStore
Parameters:
row - a dictionary representing the raw row
entityName - name of the entity for which the fault is to be returned
context - the target EOEditingContext
Returns:
a fault for the raw row

faultForRawRow

public EOEnterpriseObject faultForRawRow(NSDictionary row,
                                         String entityName)
Returns a fault for the raw row row. It is equivalent to invoking
faultForRawRow(row, entityName, this);
Parameters:
row - a dictionary representing the raw row
entityName - the name of the entity to create the fault for
Returns:
a fault for the raw row
See Also:
faultForRawRow(NSDictionary row, String entityName, EOEditingContext context)

fetchTimestamp

public long fetchTimestamp()
The fetch timestamp is a hint to refresh stale data on a subsequent fetch.
Returns:
the current timestamp hint in milliseconds
See Also:
setFetchTimestamp(long)

finalize

protected void finalize()
                 throws Throwable
Overrides:
finalize in class Object

forgetObject

public void forgetObject(EOEnterpriseObject object)
Removes object from the uniquing tables and causes this EOEditingContext to remove itself from the object's list of observers. 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 refaultAllObjects or invalidateAllObjects). Also note that this method does not have the effect of deleting an object. In order to delete an object, you should either use the deleteObject method or remove the object from an owning relationship.
Parameters:
object - the object to be forgotten
See Also:
refaultAllObjects(), invalidateAllObjects(), deleteObject(com.webobjects.eocontrol.EOEnterpriseObject)

globalIDForObject

public EOGlobalID globalIDForObject(EOEnterpriseObject object)
Returns the EOGlobalID associated with object in this EOEditingContext or its shared context. 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 has not been registered in the EOEditingContext or in its shared editing context (that is, if no match is found), this method returns null. Objects are registered in an EOEditingContext using the insertObject method, or when fetching, with recordObject.
Parameters:
object - the target of the search
Returns:
the EOGlobalID for object
See Also:
EOGlobalID, objectForGlobalID(com.webobjects.eocontrol.EOGlobalID), insertObject(com.webobjects.eocontrol.EOEnterpriseObject), recordObject(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.eocontrol.EOGlobalID), sharedEditingContext()

hasChanges

public boolean hasChanges()
Returns:
true if any of the objects in this EOEditingContext's object graph have been modified that is, if any objects have been inserted, deleted, or updated

initObjectWithCoder

public static Object initObjectWithCoder(EOEnterpriseObject object,
                                         NSCoder coder)
Invoked by an EOEnterpriseObject object to ask the EOEditingContext to initialize object from data in decoder.
Parameters:
object - an enterprise object
coder - the target NSCoder object
Returns:
initializes object from data in coder
See Also:
Serializable, usesContextRelativeEncoding(), encodeObjectWithCoder(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.foundation.NSCoder)

initializeObject

public void initializeObject(EOEnterpriseObject object,
                             EOGlobalID gid,
                             EOEditingContext context)
Overrides the implementation inherited from EOObjectStore to build the properties for the object identified by gid. When a parent EOEditingContext receives this on behalf of a child EOEditingContext (as represented by context), and the gid 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 this EOEditingContext does not have object, the request is forwarded its parent EOObjectStore.
Overrides:
initializeObject in class EOObjectStore
Parameters:
object - the object identified by globalID
gid - the EOGlobalID corresponding to object
context - the EOEditingContext in which to initialize the object
See Also:
EOObjectStore.initializeObject(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext)

insertObject

public void insertObject(EOEnterpriseObject object)
Registers (by invoking insertObjectWithGlobalID) object to be inserted in this EOEditingContext's parent EOObjectStore the next time changes are saved. In the meantime, object is registered in the receiver with a temporary globalID.
Parameters:
object - object to be inserted in the receiver's parent EOObjectStore
See Also:
insertedObjects(), deletedObjects(), insertObjectWithGlobalID(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.eocontrol.EOGlobalID)

insertObjectWithGlobalID

public void insertObjectWithGlobalID(EOEnterpriseObject object,
                                     EOGlobalID gid)
Registers a new object identified by globalID that should be inserted in the parent EOObjectStore when changes are saved. Works by invoking recordObject, unless this EOEditingContext already contains the object. Sends object the message awakeFromInsertion. globalID must respond true to isTemporary. When the external store commits object, it re-records it with the appropriate permanent EOGlobalID.

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.

Parameters:
object - the new object to be identified by gid
gid - a compact, universal identifier for a persistent object
See Also:
insertObject(com.webobjects.eocontrol.EOEnterpriseObject), recordObject(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.eocontrol.EOGlobalID)

insertedObjects

public NSArray insertedObjects()
Returns:
an array of objects that have been inserted into this EOEditingContext's object graph
See Also:
deletedObjects(), updatedObjects()

instancesRetainRegisteredObjects

public static boolean instancesRetainRegisteredObjects()

invalidateAllObjects

public 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 ObjectsChangedInStoreNotification. (EODatabaseContext is defined in EOAccess.)

The final effect of this method is to refault all objects currently in memory. 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, you have to use a statement such as the following:

 EOEditingContext.rootObjectStore().invalidateAllObjects();
 
If you just want to discard uncommitted changes but do not want to sacrifice the values cached in memory, the EOEditingContext revert method is to be used, which reverses all changes and clears the undo stack.

For more information, see the sections:


Overrides:
invalidateAllObjects in class EOObjectStore
See Also:
revert(), refaultAllObjects(), invalidateObjectsWithGlobalIDs(com.webobjects.foundation.NSArray), EOObjectStore.invalidateAllObjects()

invalidateObjectsWithGlobalIDs

public void invalidateObjectsWithGlobalIDs(NSArray gids)
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 information, see the sections:


Overrides:
invalidateObjectsWithGlobalIDs in class EOObjectStore
Parameters:
gids - An array of EOGlobalIDs corresponding to objects which should be invalidated
See Also:
invalidateAllObjects(), EOObjectStore.invalidateObjectsWithGlobalIDs(com.webobjects.foundation.NSArray), processRecentChanges()

invalidatesObjectsWhenFinalized

public boolean invalidatesObjectsWhenFinalized()
This method should not be used.
Returns:
an undefined value.

invokeRemoteMethod

public Object invokeRemoteMethod(EOEditingContext context,
                                 EOGlobalID gid,
                                 String methodName,
                                 Class[] argumentTypes,
                                 Object[] arguments)
Executes a remote method on the server. This method has the side-effect of saving the changes in the receiver to the editing context in the server session. You should note that none of the arguments or the result should be enterprise objects. Instead, EOGlobalIDs are used to specify enterprise objects. The argumentTypes argument holds the types of the remote method's (specified by methodName) arguments.
Overrides:
invokeRemoteMethod in class EOObjectStore
Parameters:
context - An EOEditingContext object manages a graph of enterprise objects in an application
gid - a compact, universal identifier for a persistent object
methodName - name of the remote method to be invoked
argumentTypes - types of the remote method's arguments
arguments - argument of the remote method
Returns:
the result of the remote method invocation

isObjectLockedWithGlobalID

public boolean isObjectLockedWithGlobalID(EOGlobalID gid,
                                          EOEditingContext context)
Returns true if the object identified by gid in context is locked, false otherwise. This method works by forwarding the message isObjectLockedWithGlobalID to its parent object store.
Overrides:
isObjectLockedWithGlobalID in class EOObjectStore
Parameters:
gid - the EOGlobalID for the target object
context - the target EOEditingContext
Returns:
true if the object identified by gid in context is locked
See Also:
lockObject(com.webobjects.eocontrol.EOEnterpriseObject), lockObjectWithGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), locksObjectsBeforeFirstModification()

lock

public void lock()
Locks access to this EOEditingContext to prevent other threads from accessing it. If it has a shared editing context, this EOEditingContext 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 you to have 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).

Specified by:
lock in interface NSLocking
Overrides:
lock in class EOObjectStore
See Also:
unlock(), sharedEditingContext()

lockObject

public void lockObject(EOEnterpriseObject object)
Attempts to lock object in the external store. This method works by invoking lockObjectWithGlobalID. Throws an RuntimeException if it cannot find the globalID for object to pass to lockObjectWithGlobalID.
Parameters:
object - the object to be locked in the external store.
See Also:
lockObjectWithGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), isObjectLockedWithGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), locksObjectsBeforeFirstModification()

lockObjectStore

public void lockObjectStore()

lockObjectWithGlobalID

public void lockObjectWithGlobalID(EOGlobalID gid,
                                   EOEditingContext context)
Overrides the implementation inherited from EOObjectStore to attempt to lock the object identified by gid in context in the external store. Throws a RuntimeException if unable to obtain the lock. This method works by forwarding the message lockObjectWithGlobalID to its parent object store.
Overrides:
lockObjectWithGlobalID in class EOObjectStore
Parameters:
gid - the EOGlobalID for the target object
context - the target EOEditingContext
See Also:
lockObject(com.webobjects.eocontrol.EOEnterpriseObject), EOObjectStore.lockObjectWithGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), isObjectLockedWithGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), locksObjectsBeforeFirstModification()

locksObjectsBeforeFirstModification

public boolean locksObjectsBeforeFirstModification()
Returns true if this EOEditingContext locks object in the external store with lockObject the first time object is modified.
Returns:
true if the object is locked in the external store the first time it is modified.
See Also:
lockObjectWithGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), isObjectLockedWithGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), lockObject(com.webobjects.eocontrol.EOEnterpriseObject), setLocksObjectsBeforeFirstModification(boolean)

messageHandler

public Object 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.
Returns:
the EOEditingContext's message handler
See Also:
setMessageHandler(java.lang.Object), EOEditingContext.MessageHandler

objectForGlobalID

public EOEnterpriseObject objectForGlobalID(EOGlobalID gid)
Returns the EOEnterpriseObject associated with gid in this EOEditingContext or its shared context, or null if no such object exists.
Parameters:
gid - the identifier to search for
Returns:
the object identified by globalID, or null
See Also:
EOGlobalID, globalIDForObject(com.webobjects.eocontrol.EOEnterpriseObject), sharedEditingContext()

objectWillChange

public void objectWillChange(Object object)
This method is automatically invoked when any of the objects registered in this EOEditingContext invokes its willChange method. This method is EOEditingContext's implementation of the EOObserving interface.
Specified by:
objectWillChange in interface EOObserving
Parameters:
object - the objects registered in the receiver
See Also:
EOEnterpriseObject.willChange()

objectsForSourceGlobalID

public NSArray objectsForSourceGlobalID(EOGlobalID gid,
                                        String name,
                                        EOEditingContext context)
Overrides the implementation inherited from EOObjectStore to service a to-many fault for a relationship named name. When a parent EOEditingContext receives a objectsForSourceGlobalID message on behalf of a child editing context and gid 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.
Overrides:
objectsForSourceGlobalID in class EOObjectStore
Parameters:
gid - EOGlobalID for the source object
name - name of the relationship
context - the target EOEditingContext
Returns:
returns a copy of the source object's relationship array
See Also:
EOObjectStore.objectsForSourceGlobalID(com.webobjects.eocontrol.EOGlobalID, java.lang.String, com.webobjects.eocontrol.EOEditingContext)

objectsWithFetchSpecification

public NSArray objectsWithFetchSpecification(EOFetchSpecification fetchSpec,
                                             EOEditingContext context)
Overrides the implementation inherited from EOObjectStore to fetch objects from an external store according to the criteria specified by fetchSpec 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 throws a RuntimeException 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 fetchSpec. The database context then obtains an EODatabaseChannel and performs the fetch, registering all fetched objects in context or in the receiver if context isn't provided. (You should note that EODatabaseContext and EODatabaseChannel are defined in EOAccess.)

For more information refer to: "Fetching Objects"

Overrides:
objectsWithFetchSpecification in class EOObjectStore
Parameters:
fetchSpecification - the criteria specified for fetch
context - the destination EOEditingContext
Returns:
the objects fetched in an array
See Also:
EOObjectStore.objectsWithFetchSpecification(com.webobjects.eocontrol.EOFetchSpecification, com.webobjects.eocontrol.EOEditingContext)

objectsWithFetchSpecification

public NSArray objectsWithFetchSpecification(EOFetchSpecification fetchSpecification)
Equivalent to :
objectsWithFetchSpecification(fetchSpecification, this);
Parameters:
fetchSpecification - the criteria specified for fetch
Returns:
the objects fetched in an array
See Also:
objectsWithFetchSpecification(EOFetchSpecification fetchSpec, EOEditingContext context)

parentObjectStore

public EOObjectStore parentObjectStore()
Returns:
the EOObjectStore from which this EOEditingContext fetches records

processRecentChanges

public void processRecentChanges()
Forces this EOEditingContext 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 ObjectsChangedInStoreNotification and ObjectsChangedInEditingContextNotification 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. This method does nothing in Java Client applications.
See Also:
saveChanges(), ObjectsChangedInEditingContextNotification

propagatesDeletesAtEndOfEvent

public boolean propagatesDeletesAtEndOfEvent()
Returns true if this EOEditingContext propagates deletes at the end of the event in which a change was made, false if it propagates deletes only right before saving changes. The default is true.
Returns:
true if deletes will be propagated at the end of the event
See Also:
setPropagatesDeletesAtEndOfEvent(boolean)

readResolve

protected Object readResolve()
                      throws ObjectStreamException

recordObject

public void recordObject(EOEnterpriseObject object,
                         EOGlobalID gid)
Makes this EOEditingContext aware of an object identified by gid 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 EOEditingContext enters the object in its uniquing table and registers itself as an observer of the object.
Parameters:
object - object identified by globalID
gid - a compact, universal identifier for a persistent object

redo

public void redo()
Sends editingContextWillSaveChanges messages to this EOEditingContext's editors, and sends a redo message to its NSUndoManager, asking it to reverse the latest undo operation applied to objects in the object graph.
See Also:
undo(), editors(), revert(), EOEditingContext.Delegate.editingContextWillSaveChanges(com.webobjects.eocontrol.EOEditingContext)

refaultAllObjects

public void refaultAllObjects()
Refaults all objects cached in this EOEditingContext that have not been inserted, deleted, or updated. Invokes processRecentChanges, then invokes refaultObject for all objects that haven't been inserted, deleted, or updated.
See Also:
refaultObject(com.webobjects.eocontrol.EOEnterpriseObject), EOObjectStore.refaultObject(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), processRecentChanges()

refaultObject

public void refaultObject(EOEnterpriseObject object)

refaultObject

public void refaultObject(EOEnterpriseObject object,
                          EOGlobalID gid,
                          EOEditingContext ctx)
Overrides the implementation inherited from EOObjectStore to refault the enterprise object object identified by gid in ctx. 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 reference cycles between enterprise objects. 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 reference cycle. Note that reference cycles are automatically broken if the EOEditingContext is finalized.

For more information, see the sections:


Overrides:
refaultObject in class EOObjectStore
Parameters:
object - the enterprise object to be refaulted
gid - the EOs corresponding EOGlobalID
ctx - the target EOEditingContext
See Also:
EOObjectStore.refaultObject(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), invalidateObjectsWithGlobalIDs(com.webobjects.foundation.NSArray)

refaultObjects

public void refaultObjects()
Deprecated. Use refaultAllObjects instead.

See Also:
refaultAllObjects(), revert()

refetch

public void refetch()
Deprecated. Use refaultAllObjects instead.

See Also:
refreshAllObjects(), refaultAllObjects()

refreshAllObjects

public void refreshAllObjects()
See Also:
refaultAllObjects(), revert()

refreshObject

public void refreshObject(EOEnterpriseObject eo)
See Also:
refreshAllObjects(), refaultAllObjects()

registeredObjects

public NSArray registeredObjects()
Returns:
an array of enterprise objects known to this EOEditingContext

removeEditor

public void removeEditor(Object editor)
Unregisters editor from this EOEditingContext.
Parameters:
editor - the editor to unregister
See Also:
editors(), addEditor(java.lang.Object)

reset

public void reset()
Forgets all objects and makes them unusable. Generally revert is preferrable. This method also resets the fetchTimestamp as if the editing context were just initialized.

This method should not be invoked on an EOEditingContext which has newly inserted objects.

See Also:
revert(), fetchTimestamp()

retainsRegisteredObjects

public boolean retainsRegisteredObjects()

revert

public void revert()
Sends editingContextWillSaveChanges messages to the EOEditingContext's editors, and 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. You should note that revert does not 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:
EOEditingContext.Delegate.editingContextWillSaveChanges(com.webobjects.eocontrol.EOEditingContext), editors(), invalidateAllObjects(), refaultAllObjects()

rootObjectStore

public EOObjectStore rootObjectStore()
Returns the EOObjectStore at the base of the object store hierarchy (usually an EOObjectStoreCoordinator).
Returns:
the underlying EOObjectStore for the entire hierarchy

saveChanges

public void saveChanges()
Sends editingContextWillSaveChanges messages to this EOEditingContext's editors, and commits changes made 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 If a database error occurs, a RuntimeException is thrown. The error message indicates the nature of the problem.
See Also:
saveChangesInEditingContext(com.webobjects.eocontrol.EOEditingContext), EOEditingContext.Delegate.editingContextWillSaveChanges(com.webobjects.eocontrol.EOEditingContext), editors()

saveChanges

public void saveChanges(Object sender)
Deprecated. Use saveChanges() instead.

Invokes the no-argument version, handling an exception using 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.
Parameters:
sender - ignored
See Also:
saveChanges()

saveChangesInEditingContext

public void saveChangesInEditingContext(EOEditingContext context)
Overrides the implementation inherited from EOObjectStore to tell this EOEditingContext'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. Throws an exception if an error occurs; the error message indicates the nature of the problem.
Overrides:
saveChangesInEditingContext in class EOObjectStore
Parameters:
context - the target EOEditingContext
See Also:
saveChanges(), EOObjectStore.saveChangesInEditingContext(com.webobjects.eocontrol.EOEditingContext)

setDefaultFetchTimestampLag

public static void setDefaultFetchTimestampLag(long lag)
Sets the default timestamp lag for newly instantiated editing contexts to lag. The default lag is 3,600,000 milliseconds (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.

Parameters:
lag - the new fetch timestamp lag in milliseconds

setDefaultParentObjectStore

public static void setDefaultParentObjectStore(EOObjectStore store)
Sets the default parent EOObjectStore to store. You can use this method before de-serializing to set the default parent EOObjectStores of the EOEditingContexts in the serialized stream. The object you supply for store can be a different EOObjectStoreCoordinator or another EOEditingContext (if you are using a nested EOEditingContext). After de-serialization, you should restore the default behavior by setting the default parent EOObjectStore to null

A default parent object store is global until it is changed again.

Parameters:
store - the new global default parent EOObjectStore
See Also:
defaultParentObjectStore(), setSubstitutionEditingContext(com.webobjects.eocontrol.EOEditingContext), setUsesContextRelativeEncoding(boolean), Serializable

setDelegate

public void setDelegate(Object delegate)
Set this EOEditingContext's delegate to be delegate.
Parameters:
delegate -  

setFetchTimestamp

public void setFetchTimestamp(long 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 refaultAllObjects before you invoke setFetchTimestamp:.



The initial value for the fetch timestamp of a new nonnested 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.
Parameters:
timestamp - The new fetch timestamp value, in milliseconds

setInstancesRetainRegisteredObjects

public static void setInstancesRetainRegisteredObjects(boolean flag)

setInvalidatesObjectsWhenFinalized

public void setInvalidatesObjectsWhenFinalized(boolean yn)
This method should not be used.
Parameters:
yn - Has no effect.

setLocksObjectsBeforeFirstModification

public void setLocksObjectsBeforeFirstModification(boolean yn)

Sets according to yn whether this EOEditingContext locks object in the external store (with lockObject) the first time object is modified. The default is false. If yn is true, an exception will be thrown if a lock cannot 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 the snapshot is out of date. If the snapshot is out of date, you can explicitly refetch the object using an EOFetchSpecification with setRefreshesRefetchedObjects set to true. 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.

Parameters:
yn - decides whether this EOEditingContext locks object in the external store the first time object is modified
See Also:
lockObject(com.webobjects.eocontrol.EOEnterpriseObject), EOEnterpriseObject.willChange(), EOFetchSpecification.setRefreshesRefetchedObjects(boolean), locksObjectsBeforeFirstModification()

setMessageHandler

public void setMessageHandler(Object handler)
Set this EOEditingContext's message handler to be handler.
Parameters:
handler - The receiver's message handler is set to this.
See Also:
messageHandler(), EOEditingContext.MessageHandler

setPropagatesDeletesAtEndOfEvent

public void setPropagatesDeletesAtEndOfEvent(boolean propagatesDeletesAtEndOfEvent)

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

If propagatesDeletesAtEndOfEvent is true, deleting an enterprise object triggers delete propagation at the end of the event in which the deletion occurred (this is the default behavior). If propagatesDeletesAtEndOfEvent is false, 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. 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.

Parameters:
propagatesDeletesAtEndOfEvent - deletes should be propagated at the end of the event in which a change was made
See Also:
saveChanges(), deleteObject(com.webobjects.eocontrol.EOEnterpriseObject), propagatesDeletesAtEndOfEvent()

setRetainsRegisteredObjects

public void setRetainsRegisteredObjects(boolean flag)

setSharedEditingContext

public void setSharedEditingContext(EOSharedEditingContext sharedEC)
Sets this EOEditingContext shared editing context. Raises if this EOEditingContext 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 DefaultSharedEditingContextWasInitializedNotifications. 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 null to remove this EOEditingContext as an observer of this notification and to prevent the context from accessing any objects in the default shared editing context.

Parameters:
sharedEC - the shared editing context to be used by this EOEditingContext
See Also:
EOSharedEditingContext, EOSharedEditingContext.DefaultSharedEditingContextWasInitializedNotification

setStopsValidationAfterFirstError

public void setStopsValidationAfterFirstError(boolean yn)
Sets according to yn whether this EOEditingContext stops validating after the first error is encountered, or continues for all objects (validation typically occurs during a save operation). The default is true. Setting it to false is useful if the delegate implements editingContextShouldPresentException to handle the presentation of aggregate exceptions.
Parameters:
yn - whether this EOEditingContext stops validating after the first error is encountered
See Also:
stopsValidationAfterFirstError()

setSubstitutionEditingContext

public static void setSubstitutionEditingContext(EOEditingContext ec)
Assigns ec as the global replacement EOEditingContext to substitute for one in the process of being de-serialized. Using this method causes all of the serialized references to the serialized EOEditingContext to be redirected to ec. This can be extremely useful when you want to de-serialize the contents of an EOEditingContext into an existing one, instead of a transitory EC within the serialized stream.

After de-serializing with a substitution EOEditingContext, you should restore the default behavior by setting the substitution EOEditingContext to null.

A substitution editing context is global until it is changed again. The Enterprise Objects Frameworks do not ensure thread safe access to the substitution EC. If you expect several threads to deserialize EOEditingContexts concurrently, you should provide your own lock object to manage it.

For more information, see: "Using EOEditingContext to Archive Custom Objects in WebObjects Framework"

Parameters:
ec - the new global substitution EOEditingContext
See Also:
substitutionEditingContext(), setUsesContextRelativeEncoding(boolean), setDefaultParentObjectStore(com.webobjects.eocontrol.EOObjectStore), Serializable

setUndoManager

public void setUndoManager(NSUndoManager undoManager)
Sets the receiver's NSUndoManager to undoManager. You might invoke this method with null if the application doesn't need undo and you want to avoid the overhead of an undo stack.

Undo and Redo

EOEditingContext includes the undo, redo, and revert methods for managing changes to objects in the object graph. undo asks the EOEditingContext's NSUndoManager to reverse the latest changes to objects in the object graph. redo asks the NSUndoManager to reverse the latest undo operation. revert clears the undo stack, discards all insertions and deletions, and restores updated objects to their last committed (saved) values.

EOEditingContext's undo support is arbitrarily deep; you can undo an object repeatedly until you restore it to the state it was in when it was first created or fetched into its editing context. Even after saving, you can undo a change. To support this feature, the NSUndoManager can keep a lot of data in memory.

For example, whenever an object is removed from a relationship, the corresponding editing context creates a snapshot of the modified, source object. The snapshot, which has a reference to the removed object, is referenced by the editing context and by the undo manager. The editing context releases the reference to the snapshot when the change is saved, but the undo manager doesn't. It continues holding the snapshot, so it can undo the deletion if requested.

If the typical usage patterns for your application generate a lot of change processing, you might want to limit the undo feature to keep its memory usage in check. For example, you could clear an undo manager whenever its editing context saves. To do so, simply send the undo manager a removeAllActions message (or a removeAllActionsWithTarget message with the editing context as the argument). If your application doesn't need undo at all, you can avoid any undo overhead by setting the editing context's undo manager to null with setUndoManager.

Parameters:
undoManager - the new NSUndoManager this EOEditingContext should use
See Also:
undoManager()

setUsesContextRelativeEncoding

public static void setUsesContextRelativeEncoding(boolean flag)
Sets according to flag whether Serialization or use context relative encoding.

For more information, see: "Using EOEditingContext to Archive Custom Objects in WebObjects Framework"

Parameters:
flag - whether Serialization uses context relative encoding
See Also:
usesContextRelativeEncoding(), setSubstitutionEditingContext(com.webobjects.eocontrol.EOEditingContext), setDefaultParentObjectStore(com.webobjects.eocontrol.EOObjectStore), Serializable

sharedEditingContext

public EOSharedEditingContext sharedEditingContext()
Returns:
the shared editing context used by this EOEditingContext

stopsValidationAfterFirstError

public boolean stopsValidationAfterFirstError()
Returns:
true to indicate that the receiver should stop validating after it encounters the first error, or false to indicate that it should continue for all objects
See Also:
setStopsValidationAfterFirstError(boolean)

substitutionEditingContext

public static EOEditingContext substitutionEditingContext()
Returns the global substitution EOEditingContext if you have been specified. Otherwise returns null.

For more information, see: "Using EOEditingContext to Archive Custom Objects in WebObjects Framework"

Returns:
the current global substitution EOEditingContext
See Also:
setSubstitutionEditingContext(com.webobjects.eocontrol.EOEditingContext), usesContextRelativeEncoding(), defaultParentObjectStore(), Serializable

tryToSaveChanges

public Throwable tryToSaveChanges()
Deprecated. Use saveChanges() instead.


undo

public void undo()
Sends editingContextWillSaveChanges messages to this EOEditingContext's editors, and sends an undo message to its NSUndoManager, asking it to reverse the latest uncommitted changes applied to objects in the object graph.

Undo and Redo

EOEditingContext includes the undo, redo, and revert methods for managing changes to objects in the object graph. undo asks the EOEditingContext's NSUndoManager to reverse the latest changes to objects in the object graph. redo asks the NSUndoManager to reverse the latest undo operation. revert clears the undo stack, discards all insertions and deletions, and restores updated objects to their last committed (saved) values.

EOEditingContext's undo support is arbitrarily deep; you can undo an object repeatedly until you restore it to the state it was in when it was first created or fetched into its editing context. Even after saving, you can undo a change. To support this feature, the NSUndoManager can keep a lot of data in memory.

For example, whenever an object is removed from a relationship, the corresponding editing context creates a snapshot of the modified, source object. The snapshot, which has a reference to the removed object, is referenced by the editing context and by the undo manager. The editing context releases the reference to the snapshot when the change is saved, but the undo manager doesn't. It continues holding the snapshot, so it can undo the deletion if requested.

If the typical usage patterns for your application generate a lot of change processing, you might want to limit the undo feature to keep its memory usage in check. For example, you could clear an undo manager whenever its editing context saves. To do so, simply send the undo manager a removeAllActions message (or a removeAllActionsWithTarget message with the editing context as the argument). If your application doesn't need undo at all, you can avoid any undo overhead by setting the editing context's undo manager to null with setUndoManager.

See Also:
redo(), editors(), revert()

undoManager

public NSUndoManager undoManager()
Returns:
the current NSUndoManager
See Also:
setUndoManager(com.webobjects.foundation.NSUndoManager)

unlock

public void unlock()
Unlocks access to this EOEditingContext so that other threads may access it. If it has a shared editing context, this EOEditingContext unlocks a reader lock on the shared context as well.
Specified by:
unlock in interface NSLocking
Overrides:
unlock in class EOObjectStore
See Also:
lock(), sharedEditingContext()

unlockObjectStore

public void unlockObjectStore()

updatedObjects

public NSArray updatedObjects()
Returns an array of objects in this EOEditingContext's object graph that have been updated.
Returns:
the array of updated objects
See Also:
deletedObjects(), insertedObjects()

usesContextRelativeEncoding

public static boolean usesContextRelativeEncoding()
Returns true to indicate whether Serialization and use context relative encoding, false otherwise.

For more information, see: "Using EOEditingContext to Archive Custom Objects in WebObjects Framework"

Returns:
true when Serialization should use context relative encoding
See Also:
setUsesContextRelativeEncoding(boolean), substitutionEditingContext(), defaultParentObjectStore(), Serializable

Last updated Fri Feb 21 13:15:00 PST 2003.

Copyright © 2003 Apple Computer, Inc.