er.extensions.eof
Class ERXEC

java.lang.Object
  com.webobjects.eocontrol.EOObjectStore
      com.webobjects.eocontrol.EOEditingContext
          er.extensions.eof.ERXEC

All Implemented Interfaces:

EOKeyValueArchiving, EOObserving, NSDisposable, NSLocking, Serializable

public class ERXEC
extends EOEditingContext

Subclass that has every public method overridden to support automatic lock/unlock handling for you. This is very useful, as is is potentially very dangerous to rely on EOFs automatic lock handling - it will invariably lead into deadlocks. As you will need to use this class and its subclasses exclusively as your ECs, it also contains a factory class to create editing contexts. The Factory also sets a default delegate for you and is used everywhere in ERExtensions and ERDirectToWeb. The Factory is actually and interface and you would create a new EC by using: ERXEC.newEditingContext() You can also install your own Factory classes. It is recommended to subclass ERXEC.DefaultFactory and override _createEditingContext()

See Also:

Serialized Form

Nested Class Summary

static class	ERXEC.DefaultFactory Default implementation of the Factory interface.
static interface	ERXEC.Delegate Extensions for the EOEditingContext.Delegate interface.
static interface	ERXEC.Factory
static class	ERXEC.OpenEditingContextLockSignalHandler OpenEditingContextLockSignalHandler provides a signal handler that prints out open editing context locks.

Nested classes/interfaces inherited from class com.webobjects.eocontrol.EOEditingContext

EOEditingContext._EventLoggingEnabler, EOEditingContext.EditingContextEvent, EOEditingContext.Editor, EOEditingContext.MessageHandler

Nested classes/interfaces inherited from interface com.webobjects.eocontrol.EOKeyValueArchiving

EOKeyValueArchiving._NullValueSupport, EOKeyValueArchiving._NumberSupport, EOKeyValueArchiving._TimestampSupport, EOKeyValueArchiving.Awaking, EOKeyValueArchiving.FinishInitialization, EOKeyValueArchiving.Support

Field Summary

static String	EditingContextDidCreateNotification Name of the notification that is posted after editing context is created.
static String	EditingContextDidRevertChanges Name of the notification that is posted when an editing context is reverted.
static String	EditingContextFailedToSaveChanges Name of the notification that is posted when an editing context has failed to save changes.
static String	EditingContextWillSaveChangesNotification Name of the notification that is posted before an editing context is saved.
protected static ERXEC.Factory	factory holds a reference to the factory used to create editing contexts
static Logger	lockLogger logs a message when set to DEBUG, autoLocking is enabled and an EC is used without a lock.
static Logger	lockLoggerTrace logs a message with a stack trace when set to DEBUG and an EC is locked/unlocked.
static Logger	lockTrace Logs a message when set to DEBUG and an EC is locked/unlocked.
static Logger	log general logging

Fields inherited from class com.webobjects.eocontrol.EOEditingContext

_CLASS, _EditingContextDidChangeSharedEditingContextNotification, _EditingContextEditorHasChangesNotification, _IsEventLoggingEnabled, EditingContextDidSaveChangesNotification, EditingContextFlushChangesRunLoopOrdering, ObjectsChangedInEditingContextNotification

Fields inherited from class com.webobjects.eocontrol.EOObjectStore

_doAssertLock, _doAssertLockInitialized, _userInfo, _wasDisposed, DeletedKey, InsertedKey, InvalidatedAllObjectsInStoreNotification, InvalidatedKey, ObjectsChangedInStoreNotification, UpdatedKey

Fields inherited from interface com.webobjects.foundation.NSLocking

OneCentury, OneDay, OneHour, OneMinute, OneSecond, OneWeek, OneYear

Constructor Summary

ERXEC()
default constructor

ERXEC(EOObjectStore os)
alternative constructor

Method Summary

protected void	_checkOpenLockTraces()
void	_objectsChangedInStore(NSNotification nsnotification) Overridden so add a bugfix from Lenny Marks
protected void	_saveChanges()
NSArray	arrayFaultWithSourceGlobalID(EOGlobalID eoglobalid, String s, EOEditingContext eoeditingcontext) Overriden to support autoLocking.
protected boolean	autoLock(String method) Utility to actually emit the log messages and do the locking, based on the result of useAutoLock().
protected void	autoUnlock(boolean wasAutoLocked) Utility to unlock the EC is it was locked in the previous invocation.
boolean	coalesceAutoLocks() If you just use autolocking, you will end up churning locks constantly.
NSDictionary	committedSnapshotForObject(EOEnterpriseObject eoenterpriseobject) Overriden to support autoLocking.
Exception	creationTrace() If traceOpenEditingContextLocks is true, returns the stack trace from when this EC was created
NSDictionary	currentEventSnapshotForObject(EOEnterpriseObject eoenterpriseobject) Overriden to support autoLocking.
static boolean	defaultAutomaticLockUnlock()
static boolean	defaultCoalesceAutoLocks()
NSArray	deletedObjects() Overriden to support autoLocking.
void	deleteObject(EOEnterpriseObject eo) Overriden to support autoLocking and to call mightDelete() on subclasses of ERXEnterpriseObject.
void	deleteObjects(NSArray objects) Utility to delete a bunch of objects.
protected void	didSaveChanges(NSArray insertedObjects, NSArray updatedObjects, NSArray deletedObjects)
void	dispose()
void	editingContextDidForgetObjectWithGlobalID(EOEditingContext eoeditingcontext, EOGlobalID eoglobalid) Overriden to support autoLocking.
static ERXEC.Factory	factory() Gets the factory used to create editing contexts
EOEnterpriseObject	faultForGlobalID(EOGlobalID eoglobalid, EOEditingContext eoeditingcontext) Overriden to support autoLocking.
void	finalize() Overriden to support automatic autoLocking.
void	forgetObject(EOEnterpriseObject eoenterpriseobject) Overriden to support autoLocking.
EOGlobalID	globalIDForObject(EOEnterpriseObject eoenterpriseobject) Overriden to support autoLocking.
boolean	hasChanges() Overriden to support autoLocking.
void	initializeObject(EOEnterpriseObject eoenterpriseobject, EOGlobalID eoglobalid, EOEditingContext eoeditingcontext) Overriden to support autoLocking.
NSArray	insertedObjects() Overriden to support autoLocking.
void	insertObject(EOEnterpriseObject eoenterpriseobject) Overriden to support autoLocking.
void	insertObjectWithGlobalID(EOEnterpriseObject eoenterpriseobject, EOGlobalID eoglobalid) Overriden to support autoLocking.
void	invalidateAllObjects() Overriden to support autoLocking.
void	invalidateObjectsWithGlobalIDs(NSArray nsarray) Overriden to support autoLocking.
Object	invokeRemoteMethod(EOEditingContext eoeditingcontext, EOGlobalID eoglobalid, String s, Class[] aclass, Object[] aobj) Overriden to support autoLocking.
boolean	isAutoLocked() Returns whether we did autolock this instance.
void	lock() Overridden to emmit log messages and push this instance to the locked editing contexts in this thread.
int	lockCount() Returns the number of outstanding locks.
void	lockObject(EOEnterpriseObject eoenterpriseobject) Overriden to support autoLocking.
static EOEditingContext	newEditingContext() Factory method to create a new editing context.
static EOEditingContext	newEditingContext(boolean validation) Factory method to create a new editing context with validation disabled.
static EOEditingContext	newEditingContext(EOObjectStore objectStore) Creates a new editing context with the specified object store as the parent object store.
static EOEditingContext	newEditingContext(EOObjectStore parent, boolean validationEnabled) Creates a new editing context with the specified object store as the parent object store and with validation turned on or off depending on the flag passed in.
static EOEditingContext	newTolerantEditingContext()
static EOEditingContext	newTolerantEditingContext(EOObjectStore osc)
static EOEditingContext	newTolerantEditingContext(EOObjectStore parent, boolean retry, boolean merge) Factory method to create a new tolerant editing context.
EOEnterpriseObject	objectForGlobalID(EOGlobalID eoglobalid) Overriden to support autoLocking.
NSArray	objectsForSourceGlobalID(EOGlobalID eoglobalid, String s, EOEditingContext eoeditingcontext) Overriden to support autoLocking.
NSArray	objectsWithFetchSpecification(EOFetchSpecification eofetchspecification, EOEditingContext eoeditingcontext) Overriden to support autoLocking.
void	objectWillChange(Object obj) Overriden to support autoLocking.
NSArray	openLockTraces() If traceOpenEditingContextLocks is true, returns the stack trace from when this EC was locked
static void	popLockedContextForCurrentThread(EOEditingContext ec) Pops the given EC from the array of contexts to unlock.
void	processRecentChanges() Overriden to support autoLocking.
static void	pushLockedContextForCurrentThread(EOEditingContext ec) Pushes the given EC to the array of locked ECs in the current thread.
void	recordObject(EOEnterpriseObject eoenterpriseobject, EOGlobalID eoglobalid) Overriden to support autoLocking.
void	redo() Overriden to support autoLocking.
void	refaultAllObjects() Overriden to support autoLocking.
void	refaultObject(EOEnterpriseObject eoenterpriseobject) Overriden to support autoLocking.
void	refaultObject(EOEnterpriseObject eoenterpriseobject, EOGlobalID eoglobalid, EOEditingContext eoeditingcontext) Overriden to support autoLocking and to flush the cache of all ERXEnterpriseObjects.
void	refreshObject(EOEnterpriseObject eoenterpriseobject) Overriden to support autoLocking.
NSArray	registeredObjects() Overriden to support autoLocking.
static void	registerOpenEditingContextLockSignalHandler() Register the OpenEditingContextLockSignalHandler signal handle on the HUP signal.
static void	registerOpenEditingContextLockSignalHandler(String signalName) Register the OpenEditingContextLockSignalHandler signal handle on the named signal.
void	reset() Overriden to support automatic autoLocking.
void	revert() Overriden to support autoLocking and will/did revert delegate methods.
static boolean	safeLocking() Returns the value of the er.extensions.ERXEC.safeLocking property, which is the new catch-all setting that turns on all of the recommended locking settings.
void	saveChanges() Smarter version of normal saveChanges() method.
void	saveChanges(Object obj) Deprecated.
void	saveChangesInEditingContext(EOEditingContext eoeditingcontext) Overriden to support autoLocking.
void	saveChangesTolerantly()
void	saveChangesTolerantly(boolean doesRetry)
void	saveChangesTolerantly(boolean doesRetry, boolean mergesChanges) Saves changes and tries to recover from optimistic locking exceptions by refaulting the object in question, optionally merging the changed values and optionally retrying the save.
static void	saveChangesTolerantly(EOEditingContext ec)
static void	saveChangesTolerantly(EOEditingContext ec, boolean doesRetry, boolean mergesChanges)
void	setCoalesceAutoLocks(boolean value) Returns whether or not coalescing auto locks is enabled.
void	setDelegate(Object d) Sets the delegate for this context.
static void	setFactory(ERXEC.Factory aFactory) Sets the default editing context factory
void	setOptions(boolean recoversFromException, boolean doesRetry, boolean mergesChanges) Set the options for the saveChanges() operation.
void	setSharedEditingContext(EOSharedEditingContext eosharededitingcontext) Overriden to support autoLocking.
static void	setTraceOpenLocks(boolean value) Sets whether or not open editing context lock tracing is enabled.
void	setUseAutoLock(boolean value) Sets whether to use autoLocking on this EC.
static void	setUseUnlocker(boolean value)
static boolean	traceOpenLocks()
void	undo() Overriden to support autoLocking.
void	unlock() Overridden to emmit log messages and pull this instance from the locked editing contexts in this thread.
static void	unlockAllContextsForCurrentThread() Unlocks all remaining locked contexts in the current thread.
NSArray	updatedObjects() Overriden to support autoLocking.
boolean	useAutoLock() Decides on a per-EC-level if autoLocking should be used.
static boolean	useUnlocker()
protected void	willSaveChanges(NSArray insertedObjects, NSArray updatedObjects, NSArray deletedObjects)

Methods inherited from class com.webobjects.eocontrol.EOEditingContext

_clearChangedThisTransaction, _clearOriginalSnapshotAndInitializeRec, _clearOriginalSnapshotForObject, _defaultEditingContextNowInitialized, _defaultSharedEditingContextWasInitialized, _editorHasChanges, _EOAssertSafeMultiThreadedAccess, _EOAssertSafeMultiThreadedAccess, _EOAssertSafeMultiThreadedReadAccess, _globalIDChanged, _globalIDsForObjects, _initWithParentObjectStore, _insertObjectWithGlobalID, _invalidatedAllObjectsInStore, _invalidateObjectsDuringSave, _noop, _objectBasedChangeInfoForGIDInfo, _objectsInitializedInSharedContext, _processEndOfEventNotification, _processGlobalIDChanges, _processInitializedObjectsInSharedContext, _processNotificationQueue, _processObjectStoreChanges, _processRecentChanges, _resetAllChanges, _resetAllChanges, _retainCountForObjectWithGlobalID, _undoDelete, _undoManagerCheckpoint, _undoUpdate, addEditor, decodeWithKeyValueUnarchiver, defaultFetchTimestampLag, defaultParentObjectStore, delegate, editors, editorsHaveChanges, encodeObjectWithCoder, encodeWithKeyValueArchiver, faultForRawRow, faultForRawRow, fetchTimestamp, initObjectWithCoder, instancesRetainRegisteredObjects, invalidatesObjectsWhenFinalized, isObjectLockedWithGlobalID, lockObjectStore, lockObjectWithGlobalID, locksObjectsBeforeFirstModification, messageHandler, objectsWithFetchSpecification, parentObjectStore, propagatesDeletesAtEndOfEvent, readResolve, refaultObjects, refetch, refreshAllObjects, removeEditor, retainsRegisteredObjects, rootObjectStore, setDefaultFetchTimestampLag, setDefaultParentObjectStore, setFetchTimestamp, setInstancesRetainRegisteredObjects, setInvalidatesObjectsWhenFinalized, setLocksObjectsBeforeFirstModification, setMessageHandler, setPropagatesDeletesAtEndOfEvent, setRetainsRegisteredObjects, setStopsValidationAfterFirstError, setSubstitutionEditingContext, setUndoManager, setUsesContextRelativeEncoding, sharedEditingContext, stopsValidationAfterFirstError, substitutionEditingContext, tryLock, tryToSaveChanges, undoManager, unlockObjectStore, usesContextRelativeEncoding

Methods inherited from class com.webobjects.eocontrol.EOObjectStore

_checkAssertLock, _resetAssertLock, _suppressAssertLock, setUserInfo, setUserInfoForKey, userInfo, userInfoForKey

Methods inherited from class java.lang.Object

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

Field Detail

log

public static final Logger log

general logging

lockLogger

public static final Logger lockLogger

logs a message when set to DEBUG, autoLocking is enabled and an EC is used without a lock.

lockLoggerTrace

public static final Logger lockLoggerTrace

logs a message with a stack trace when set to DEBUG and an EC is locked/unlocked.

lockTrace

public static final Logger lockTrace

Logs a message when set to DEBUG and an EC is locked/unlocked.

EditingContextDidCreateNotification

public static final String EditingContextDidCreateNotification

Name of the notification that is posted after editing context is created.

See Also:

Constant Field Values

EditingContextWillSaveChangesNotification

public static final String EditingContextWillSaveChangesNotification

Name of the notification that is posted before an editing context is saved.

See Also:

Constant Field Values

EditingContextDidRevertChanges

public static final String EditingContextDidRevertChanges

Name of the notification that is posted when an editing context is reverted.

See Also:

Constant Field Values

EditingContextFailedToSaveChanges

public static final String EditingContextFailedToSaveChanges

Name of the notification that is posted when an editing context has failed to save changes.

See Also:

Constant Field Values

factory

protected static ERXEC.Factory factory

holds a reference to the factory used to create editing contexts

Constructor Detail

ERXEC

public ERXEC()

default constructor

ERXEC

public ERXEC(EOObjectStore os)

alternative constructor

Method Detail

safeLocking

public static boolean safeLocking()

Returns the value of the er.extensions.ERXEC.safeLocking property, which is the new catch-all setting that turns on all of the recommended locking settings.

useUnlocker

public static boolean useUnlocker()

setUseUnlocker

public static void setUseUnlocker(boolean value)

traceOpenLocks

public static boolean traceOpenLocks()

setTraceOpenLocks

public static void setTraceOpenLocks(boolean value)

Sets whether or not open editing context lock tracing is enabled.

pushLockedContextForCurrentThread

public static void pushLockedContextForCurrentThread(EOEditingContext ec)

Pushes the given EC to the array of locked ECs in the current thread. The ECs left over after the RR-loop will be automagically unlocked.

Parameters:

ec - locked EOEditingContext

popLockedContextForCurrentThread

public static void popLockedContextForCurrentThread(EOEditingContext ec)

Pops the given EC from the array of contexts to unlock. The ECs left over after the RR-loop will be automagically unlocked.

Parameters:

ec - unlocked EOEditingContext

unlockAllContextsForCurrentThread

public static void unlockAllContextsForCurrentThread()

Unlocks all remaining locked contexts in the current thread. You shouldn't call this yourself, but let the Unlocker handle it for you.

defaultAutomaticLockUnlock

public static boolean defaultAutomaticLockUnlock()

defaultCoalesceAutoLocks

public static boolean defaultCoalesceAutoLocks()

deleteObjects

public void deleteObjects(NSArray objects)

Utility to delete a bunch of objects.

useAutoLock

public boolean useAutoLock()

Decides on a per-EC-level if autoLocking should be used.

setUseAutoLock

public void setUseAutoLock(boolean value)

Sets whether to use autoLocking on this EC.

coalesceAutoLocks

public boolean coalesceAutoLocks()

If you just use autolocking, you will end up churning locks constantly. Additionally, you can still end up with race conditions since you're not actually locking across your entire request. Coalescing auto locks attempts to solve this problem by leaving your auto lock open after the first use. This "hanging lock" will be cleaned up at the end of the RR loop but the unlocker.

setCoalesceAutoLocks

public void setCoalesceAutoLocks(boolean value)

Returns whether or not coalescing auto locks is enabled.

lockCount

public int lockCount()

Returns the number of outstanding locks.

creationTrace

public Exception creationTrace()

If traceOpenEditingContextLocks is true, returns the stack trace from when this EC was created

openLockTraces

public NSArray openLockTraces()

If traceOpenEditingContextLocks is true, returns the stack trace from when this EC was locked

lock

public void lock()

Overridden to emmit log messages and push this instance to the locked editing contexts in this thread.

Specified by:

lock in interface NSLocking

Overrides:

lock in class EOEditingContext

unlock

public void unlock()

Overridden to emmit log messages and pull this instance from the locked editing contexts in this thread.

Specified by:

unlock in interface NSLocking

Overrides:

unlock in class EOEditingContext

autoLock

protected boolean autoLock(String method)

Utility to actually emit the log messages and do the locking, based on the result of useAutoLock().

Parameters:

method - method name which to prepend to log message

Returns:

whether we did lock automatically

autoUnlock

protected void autoUnlock(boolean wasAutoLocked)

Utility to unlock the EC is it was locked in the previous invocation.

Parameters:

wasAutoLocked - true if the EC was autolocked

isAutoLocked

public boolean isAutoLocked()

Returns whether we did autolock this instance.

Returns:

true if we were autolocked.

_checkOpenLockTraces

protected void _checkOpenLockTraces()

dispose

public void dispose()

Specified by:

dispose in interface NSDisposable

Overrides:

dispose in class EOEditingContext

finalize

public void finalize()
              throws Throwable

Overriden to support automatic autoLocking.

Overrides:

finalize in class EOEditingContext

Throws:

Throwable

reset

public void reset()

Overriden to support automatic autoLocking.

Overrides:

reset in class EOEditingContext

recordObject

public void recordObject(EOEnterpriseObject eoenterpriseobject,
                         EOGlobalID eoglobalid)

Overriden to support autoLocking.

Overrides:

recordObject in class EOEditingContext

forgetObject

public void forgetObject(EOEnterpriseObject eoenterpriseobject)

Overriden to support autoLocking.

Overrides:

forgetObject in class EOEditingContext

processRecentChanges

public void processRecentChanges()

Overriden to support autoLocking.

Overrides:

processRecentChanges in class EOEditingContext

updatedObjects

public NSArray updatedObjects()

Overriden to support autoLocking.

Overrides:

updatedObjects in class EOEditingContext

registeredObjects

public NSArray registeredObjects()

Overriden to support autoLocking.

Overrides:

registeredObjects in class EOEditingContext

insertedObjects

public NSArray insertedObjects()

Overriden to support autoLocking.

Overrides:

insertedObjects in class EOEditingContext

deletedObjects

public NSArray deletedObjects()

Overriden to support autoLocking.

Overrides:

deletedObjects in class EOEditingContext

setSharedEditingContext

public void setSharedEditingContext(