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

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

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:

• "Other Classes that Participate in Object Graph Management"
• "Programmatically Creating an EOEditingContext"
• "Using EOEditingContexts in Different Configurations"
• "Fetching Objects"
• "Managing Changes in Your Application"
• "Methods for Managing the Object Graph"
• "General Guidelines for Managing the Object Graph"
• "Using EOEditingContext to Archive Custom Objects in Web Objects Framework"

See Also:

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

Nested 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.

Nested classes/interfaces inherited from interface 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() Report whether EOEditingContext objects created by this application instance will strongly retain all EOEnterpriseObject instances registered with them.
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 : objectsWithFetchSpecification(fetchSpecification, this);.
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() This method invokes refreshObject on each registered EOEnterpriseObject in this context.
void	refreshObject(EOEnterpriseObject eo) This method invokes refaultObject on an EOEnterpriseObject which is not inserted, updated, or deleted.
NSArray	registeredObjects()
void	removeEditor(Object editor) Unregisters editor from this EOEditingContext.
void	reset() Forgets all objects and makes them unusable.
boolean	retainsRegisteredObjects() Report whether this EOEditingContext will retain strong references to all EOEnterpriseObject instances registered with it.
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 EOEditingContext.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) Set the retain policy for EOEditingContext objects created by this application instance.
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) Set the retain policy for this EOEditingContext.
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.
boolean	tryLock()
Throwable	tryToSaveChanges() Deprecated. Use EOEditingContext.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 com.webobjects.eocontrol.EOObjectStore

setUserInfo, setUserInfoForKey, userInfo, userInfoForKey

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

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:

EOEditingContext.EditingContextDidSaveChangesNotification, EOEditingContext.ObjectsChangedInEditingContextNotification, Constant Field Values

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.

See Also:

Constant Field Values

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

See Also:

Constant Field Values

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:

EOEditingContext.parentObjectStore(), EOEditingContext.defaultParentObjectStore(), EOEditingContext.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:

EOEditingContext.parentObjectStore(), EOEditingContext.defaultParentObjectStore(), EOEditingContext.setSharedEditingContext(com.webobjects.eocontrol.EOSharedEditingContext), EOObjectStore

Method Detail

setInstancesRetainRegisteredObjects

public static void setInstancesRetainRegisteredObjects(boolean flag)

Set the retain policy for EOEditingContext objects created by this application instance.

See Also:

instancesRetainRegisteredObjects

instancesRetainRegisteredObjects

public static boolean instancesRetainRegisteredObjects()

Report whether EOEditingContext objects created by this application instance will strongly retain all EOEnterpriseObject instances registered with them. By default, an EOEditingContext will retain weak references to all EOEnterpriseObjects instances registered with it. It will only keep strong references for EOEnterpriseObjects instances that have been inserted, deleted, or modified, when this change has not yet been saved to the persistent data store. So, EOs that have not been modified may be garbage-collected by the Java VM, if it decides to do so. If this method returns true, then the application will use more memory.

setRetainsRegisteredObjects

public void setRetainsRegisteredObjects(boolean flag)

Set the retain policy for this EOEditingContext. If there are objects registered with this EOEditingContext, calling this method will result in an IllegalStateException.

See Also:

setInstancesRetainRegisteredObjects

retainsRegisteredObjects

public boolean retainsRegisteredObjects()

Report whether this EOEditingContext will retain strong references to all EOEnterpriseObject instances registered with it.

See Also:

instancesRetainRegisteredObjects

defaultFetchTimestampLag

public static long defaultFetchTimestampLag()

Returns:

the default timestamp lag in milliseconds

See Also:

EOEditingContext.setDefaultFetchTimestampLag(long)

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

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:

EOEditingContext.usesContextRelativeEncoding(), EOEditingContext.setSubstitutionEditingContext(com.webobjects.eocontrol.EOEditingContext), EOEditingContext.setDefaultParentObjectStore(com.webobjects.eocontrol.EOObjectStore), Serializable

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:

EOEditingContext.setUsesContextRelativeEncoding(boolean), EOEditingContext.substitutionEditingContext(), EOEditingContext.defaultParentObjectStore(), Serializable

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, EOEditingContext.usesContextRelativeEncoding(), EOEditingContext.initObjectWithCoder(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.foundation.NSCoder)

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, EOEditingContext.usesContextRelativeEncoding(), EOEditingContext.encodeObjectWithCoder(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.foundation.NSCoder)

encodeWithKeyValueArchiver

@Deprecated
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

decodeWithKeyValueUnarchiver

public static Object decodeWithKeyValueUnarchiver(EOKeyValueUnarchiver unarchiver)

setInvalidatesObjectsWhenFinalized

public void setInvalidatesObjectsWhenFinalized(boolean yn)

This method should not be used.

Parameters:

yn - Has no effect.

invalidatesObjectsWhenFinalized

public boolean invalidatesObjectsWhenFinalized()

This method should not be used.

Returns:

an undefined value.

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:

EOEditingContext.revert(), EOEditingContext.fetchTimestamp()

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.

Specified by:

dispose in interface NSDisposable

Overrides:

dispose in class EOObjectStore

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable

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:

EOEditingContext.setFetchTimestamp(long)

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

parentObjectStore

public EOObjectStore parentObjectStore()

Returns:

the EOObjectStore from which this EOEditingContext fetches records

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

setUndoManager

public void setUndoManager(NSUndoManager undoManager)

Sets the receiver's NSUndoManager to undoManager.

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).

Parameters:

undoManager - the new NSUndoManager this EOEditingContext should use

See Also:

EOEditingContext.undoManager()

undoManager

public NSUndoManager undoManager()

Returns:

the current NSUndoManager

See Also:

EOEditingContext.setUndoManager(com.webobjects.foundation.NSUndoManager)

setDelegate

public void setDelegate(Object delegate)

Set this EOEditingContext's delegate to be delegate.

Parameters:

delegate -

delegate

public Object delegate()

Returns:

the current delegate.

See Also:

EOEditingContext.setDelegate(java.lang.Object)

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:

EOEditingContext.editors(), EOEditingContext.removeEditor(java.lang.Object), EOEditingContext.Editor

removeEditor

public void removeEditor(Object editor)

Unregisters editor from this EOEditingContext.

Parameters:

editor - the editor to unregister

See Also:

EOEditingContext.editors(), EOEditingContext.addEditor(java.lang.Object)

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:

EOEditingContext.addEditor(java.lang.Object), EOEditingContext.removeEditor(java.lang.Object), EOEditingContext.Editor

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:

EOEditingContext.messageHandler(), EOEditingContext.MessageHandler

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:

EOEditingContext.setMessageHandler(java.lang.Object), EOEditingContext.MessageHandler

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

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:

EOEditingContext.refaultAllObjects(), EOEditingContext.invalidateAllObjects(), EOEditingContext.deleteObject(com.webobjects.eocontrol.EOEnterpriseObject)

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:

EOEditingContext.saveChanges(), EOEditingContext.ObjectsChangedInEditingContextNotification

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:

EOEditingContext.deletedObjects(), EOEditingContext.insertedObjects()

registeredObjects

public NSArray registeredObjects()

Returns:

an array of enterprise objects known to this EOEditingContext

insertedObjects

public NSArray insertedObjects()

Returns:

an array of objects that have been inserted into this EOEditingContext's object graph

See Also:

EOEditingContext.deletedObjects(), EOEditingContext.updatedObjects()

deletedObjects

public NSArray deletedObjects()

Returns:

the objects that have been deleted from this EOEditingContext's object graph

See Also:

EOEditingContext.updatedObjects(), EOEditingContext.insertedObjects()

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:

EOEditingContext.setPropagatesDeletesAtEndOfEvent(boolean)

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:

EOEditingContext.saveChanges(), EOEditingContext.deleteObject(com.webobjects.eocontrol.EOEnterpriseObject), EOEditingContext.propagatesDeletesAtEndOfEvent()

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:

EOEditingContext.setStopsValidationAfterFirstError(boolean)

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:

EOEditingContext.stopsValidationAfterFirstError()

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:

EOEditingContext.lockObjectWithGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), EOEditingContext.isObjectLockedWithGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), EOEditingContext.lockObject(com.webobjects.eocontrol.EOEnterpriseObject), EOEditingContext.setLocksObjectsBeforeFirstModification(boolean)

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:

EOEditingContext.lockObject(com.webobjects.eocontrol.EOEnterpriseObject), EOEnterpriseObject.willChange(), EOFetchSpecification.setRefreshesRefetchedObjects(boolean), EOEditingContext.locksObjectsBeforeFirstModification()

sharedEditingContext

public EOSharedEditingContext sharedEditingContext()

Returns:

the shared editing context used by this EOEditingContext

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

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, EOEditingContext.globalIDForObject(com.webobjects.eocontrol.EOEnterpriseObject), EOEditingContext.sharedEditingContext()

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, EOEditingContext.objectForGlobalID(com.webobjects.eocontrol.EOGlobalID), EOEditingContext.insertObject(com.webobjects.eocontrol.EOEnterpriseObject), EOEditingContext.recordObject(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.eocontrol.EOGlobalID), EOEditingContext.sharedEditingContext()

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:

EOEditingContext.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:

EOEditingContext.committedSnapshotForObject(com.webobjects.eocontrol.EOEnterpriseObject), EOEditingContext.processRecentChanges()

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()

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:

EOEditingContext.insertObject(com.webobjects.eocontrol.EOEnterpriseObject), EOEditingContext.recordObject(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.eocontrol.EOGlobalID)

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:

EOEditingContext.insertedObjects(), EOEditingContext.deletedObjects(), EOEditingContext.insertObjectWithGlobalID(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.eocontrol.EOGlobalID)

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:

EOEditingContext.deletedObjects()

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

editorsHaveChanges

public boolean editorsHaveChanges()

Returns:

true if any of the editors associated with this EOEditingContext have pending changes.

See Also:

EOEditingContext.Editor, EOEditingContext.addEditor(java.lang.Object)

tryToSaveChanges

@Deprecated
public Throwable tryToSaveChanges()

Deprecated. Use EOEditingContext.saveChanges() instead.

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:

EOEditingContext.saveChangesInEditingContext(com.webobjects.eocontrol.EOEditingContext), EOEditingContext.Delegate.editingContextWillSaveChanges(com.webobjects.eocontrol.EOEditingContext), EOEditingContext.editors()

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"

Specified by:

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, EOEditingContext.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.

Specified by:

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

See Also:

EOEditingContext.faultForRawRow(com.webobjects.foundation.NSDictionary, java.lang.String, com.webobjects.eocontrol.EOEditingContext), EODatabaseContext.faultForRawRow(com.webobjects.foundation.NSDictionary, java.lang.String, com.webobjects.eocontrol.EOEditingContext)

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:

EOEditingContext.faultForRawRow(NSDictionary row, String entityName, EOEditingContext context)

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.

Specified by:

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:

EOEditingContext.faultForGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), EOObjectStore.arrayFaultWithSourceGlobalID(com.webobjects.eocontrol.EOGlobalID, java.lang.String, com.webobjects.eocontrol.EOEditingContext)

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.

Specified by:

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)

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.

Specified by:

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)

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.

Specified by:

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)

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:

• "Methods for Managing the Object Graph"
• "Breaking Reference Cycles"
• "Refreshing Objects"
• "Discarding the View of Objects Cached in Memory"
• "Working with Objects Across Multiple EOEditingContexts"
• "Updates from the Parent EOObjectStore"

Specified by:

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), EOEditingContext.invalidateObjectsWithGlobalIDs(com.webobjects.foundation.NSArray)

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"

Specified by:

objectsWithFetchSpecification in class EOObjectStore

Parameters:

fetchSpec - 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)

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.

Specified by:

saveChangesInEditingContext in class EOObjectStore

Parameters:

context - the target EOEditingContext

See Also:

EOEditingContext.saveChanges(), EOObjectStore.saveChangesInEditingContext(com.webobjects.eocontrol.EOEditingContext)

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.

Specified by:

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:

EOEditingContext.lockObject(com.webobjects.eocontrol.EOEnterpriseObject), EOEditingContext.lockObjectWithGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), EOEditingContext.locksObjectsBeforeFirstModification()

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.

Specified by:

lockObjectWithGlobalID in class EOObjectStore

Parameters:

gid - the EOGlobalID for the target object

context - the target EOEditingContext

See Also:

EOEditingContext.lockObject(com.webobjects.eocontrol.EOEnterpriseObject), EOObjectStore.lockObjectWithGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), EOEditingContext.isObjectLockedWithGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), EOEditingContext.locksObjectsBeforeFirstModification()

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:

EOEditingContext.refaultObject(com.webobjects.eocontrol.EOEnterpriseObject), EOObjectStore.refaultObject(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), EOEditingContext.processRecentChanges()

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:

• "Methods for Managing the Object Graph"
• "Breaking Reference Cycles"
• "Refreshing Objects"
• "Discarding the View of Objects Cached in Memory"
• "Working with Objects Across Multiple EOEditingContexts"
• "Updates from the Parent EOObjectStore"

Specified by:

invalidateObjectsWithGlobalIDs in class EOObjectStore

Parameters:

gids - An array of EOGlobalIDs corresponding to objects which should be invalidated

See Also:

EOEditingContext.invalidateAllObjects(), EOObjectStore.invalidateObjectsWithGlobalIDs(com.webobjects.foundation.NSArray), EOEditingContext.processRecentChanges()

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:

• "Methods for Managing the Object Graph"
• "Breaking Reference Cycles"
• "Refreshing Objects"
• "Discarding the View of Objects Cached in Memory"
• "Working with Objects Across Multiple EOEditingContexts"
• "Updates from the Parent EOObjectStore"

Specified by:

invalidateAllObjects in class EOObjectStore

See Also:

EOEditingContext.revert(), EOEditingContext.refaultAllObjects(), EOEditingContext.invalidateObjectsWithGlobalIDs(com.webobjects.foundation.NSArray), EOObjectStore.invalidateAllObjects()

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:

EOEditingContext.objectsWithFetchSpecification(EOFetchSpecification fetchSpec, EOEditingContext context)

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:

EOEditingContext.lockObjectWithGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), EOEditingContext.isObjectLockedWithGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), EOEditingContext.locksObjectsBeforeFirstModification()

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), EOEditingContext.editors(), EOEditingContext.invalidateAllObjects(), EOEditingContext.refaultAllObjects()

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

Specified by:

lock in class EOObjectStore

See Also:

EOEditingContext.unlock(), EOEditingContext.sharedEditingContext()

tryLock

public boolean tryLock()

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

Specified by:

unlock in class EOObjectStore

See Also:

EOEditingContext.lock(), EOEditingContext.sharedEditingContext()

lockObjectStore

public void lockObjectStore()

unlockObjectStore

public void unlockObjectStore()

saveChanges

@Deprecated
public void saveChanges(Object sender)

Deprecated. Use EOEditingContext.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:

EOEditingContext.saveChanges()

refreshObject

public void refreshObject(EOEnterpriseObject eo)

This method invokes refaultObject on an EOEnterpriseObject which is not inserted, updated, or deleted. Updated objects have their currently outstanding changes set aside, then are refaulted, and finally have their changes merged. This method ignores pending inserts or deletes. This method does not affect the acceptable level of staleness for the parent object store's cache. Use EOEditingContext.setFetchTimestamp(long) to fine tune the refetching.

See Also:

EOEditingContext.setFetchTimestamp(long), EOEditingContext.refaultObject(com.webobjects.eocontrol.EOEnterpriseObject), EOEditingContext.refreshAllObjects()

refreshAllObjects

public void refreshAllObjects()

This method invokes refreshObject on each registered EOEnterpriseObject in this context.

See Also:

EOEditingContext.refreshObject(com.webobjects.eocontrol.EOEnterpriseObject), EOEditingContext.refaultAllObjects(), EOEditingContext.revert()

refetch

@Deprecated
public void refetch()

Deprecated. Use refaultAllObjects instead.

See Also:

EOEditingContext.refreshAllObjects(), EOEditingContext.refaultAllObjects()

refaultObjects

@Deprecated
public void refaultObjects()

Deprecated. Use refaultAllObjects instead.

See Also:

EOEditingContext.refaultAllObjects(), EOEditingContext.revert()

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:

EOEditingContext.redo(), EOEditingContext.editors(), EOEditingContext.revert()

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:

EOEditingContext.undo(), EOEditingContext.editors(), EOEditingContext.revert(), EOEditingContext.Delegate.editingContextWillSaveChanges(com.webobjects.eocontrol.EOEditingContext)

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:

EOEditingContext.substitutionEditingContext(), EOEditingContext.setUsesContextRelativeEncoding(boolean), EOEditingContext.setDefaultParentObjectStore(com.webobjects.eocontrol.EOObjectStore), Serializable

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:

EOEditingContext.setSubstitutionEditingContext(com.webobjects.eocontrol.EOEditingContext), EOEditingContext.usesContextRelativeEncoding(), EOEditingContext.defaultParentObjectStore(), Serializable

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:

EOEditingContext.defaultParentObjectStore(), EOEditingContext.setSubstitutionEditingContext(com.webobjects.eocontrol.EOEditingContext), EOEditingContext.setUsesContextRelativeEncoding(boolean), Serializable

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:

EOEditingContext.setDefaultParentObjectStore(com.webobjects.eocontrol.EOObjectStore), EOEditingContext.substitutionEditingContext(), EOEditingContext.usesContextRelativeEncoding(), Serializable

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

readResolve

protected Object readResolve()
                      throws ObjectStreamException

Throws:

ObjectStreamException