EOEditingContext (WebObjects 5.4 Reference)

Overview

Package

Class

Tree

Deprecated

Index

Help

WebObjects 5.4.1

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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

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

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<EOEnterpriseObject>`	`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<EOEditingContext.Editor>`	`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<EOEnterpriseObject>`	`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<EOGlobalID> 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 `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 `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<EOEnterpriseObject>`	`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:: EditingContextDidSaveChangesNotification, 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:: 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

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:: 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:: usesContextRelativeEncoding(), setSubstitutionEditingContext(com.webobjects.eocontrol.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:: setUsesContextRelativeEncoding(boolean), substitutionEditingContext(), 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, usesContextRelativeEncoding(), 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, usesContextRelativeEncoding(), 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:: revert(), 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:: 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:: undoManager()

undoManager

public NSUndoManager undoManager()

Returns:: the current NSUndoManager
See Also:: 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:: 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:: editors(), 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:: editors(), addEditor(java.lang.Object)

editors

public NSArray<EOEditingContext.Editor> 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

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

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

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:: refaultAllObjects(), invalidateAllObjects(), 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:: saveChanges(), ObjectsChangedInEditingContextNotification

updatedObjects

public NSArray<EOEnterpriseObject> 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()

registeredObjects

public NSArray registeredObjects()

Returns:: an array of enterprise objects known to this EOEditingContext

insertedObjects

public NSArray<EOEnterpriseObject> insertedObjects()

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

deletedObjects

public NSArray<EOEnterpriseObject> deletedObjects()

Returns:: the objects that have been deleted from this EOEditingContext's object graph
See Also:: updatedObjects(), 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:: 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:: saveChanges(), deleteObject(com.webobjects.eocontrol.EOEnterpriseObject), 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:: 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:: 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:: 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)

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

sharedEditingContext

public EOSharedEditingContext sharedEditingContext()

com.webobjects.eocontrol Class EOEditingContext

Principal Attributes

Commonly Used Methods

EditingContextFlushChangesRunLoopOrdering

ObjectsChangedInEditingContextNotification

EditingContextDidSaveChangesNotification

EOEditingContext

EOEditingContext

setInstancesRetainRegisteredObjects

instancesRetainRegisteredObjects

setRetainsRegisteredObjects

retainsRegisteredObjects

defaultFetchTimestampLag

setDefaultFetchTimestampLag

setUsesContextRelativeEncoding

usesContextRelativeEncoding

encodeObjectWithCoder

initObjectWithCoder

encodeWithKeyValueArchiver

decodeWithKeyValueUnarchiver

setInvalidatesObjectsWhenFinalized

invalidatesObjectsWhenFinalized

reset

dispose

finalize

fetchTimestamp

setFetchTimestamp

parentObjectStore

rootObjectStore

setUndoManager

Undo and Redo

undoManager

setDelegate

delegate

addEditor

removeEditor

editors

setMessageHandler

messageHandler

recordObject

forgetObject

processRecentChanges

updatedObjects

registeredObjects

insertedObjects

deletedObjects

propagatesDeletesAtEndOfEvent

setPropagatesDeletesAtEndOfEvent

stopsValidationAfterFirstError

setStopsValidationAfterFirstError

locksObjectsBeforeFirstModification

setLocksObjectsBeforeFirstModification

sharedEditingContext

com.webobjects.eocontrol
Class EOEditingContext