EOEditingContext (WebObjects 5.4.2 Reference)

Overview

Package

Class

Tree

Deprecated

Index

Help

WebObjects 5.4.2

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

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:

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:

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

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

Overview

Package

Class

Tree

Deprecated

Index

Help

Last updated June 2008

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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

setSharedEditingContext

objectForGlobalID

globalIDForObject

committedSnapshotForObject

currentEventSnapshotForObject

objectWillChange

insertObjectWithGlobalID

insertObject

deleteObject

hasChanges

editorsHaveChanges

tryToSaveChanges

saveChanges

faultForGlobalID

faultForRawRow

faultForRawRow

arrayFaultWithSourceGlobalID

initializeObject

editingContextDidForgetObjectWithGlobalID

objectsForSourceGlobalID

refaultObject

refaultObject

objectsWithFetchSpecification

saveChangesInEditingContext

isObjectLockedWithGlobalID

lockObjectWithGlobalID

refaultAllObjects

com.webobjects.eocontrol
Class EOEditingContext