EODatabaseContext.Delegate

(informal interface)

Package:
com.webobjects.eoaccess

Interface Description

An EODatabaseContext shares its delegate with its EODatabaseChannels. These delegate methods are actually sent from EODatabaseChannel, but they're defined in EODatabaseContext for ease of access:

databaseContextDidSelectObjects

databaseContextShouldSelectObjects

databaseContextShouldUpdateCurrentSnapshot

databaseContextShouldUsePessimisticLock

You can use the EODatabaseContext delegate methods to intervene when objects are created and when they're fetched from the database. This gives you more fine-grained control over such issues as how an object's primary key is generated ( databaseContextNewPrimaryKey), how and if objects are locked ( databaseContextShouldLockObjectWithGlobalID), what fetch specification is used to fetch objects ( databaseContextShouldSelectObjects), how batch faulting is performed ( databaseContextShouldFetchArrayFault and databaseContextShouldFetchObjectFault), and so on. For more information, see the individual delegate method descriptions.

Instance Methods

databaseContextDidFetchObjects

public abstract void databaseContextDidFetchObjects( EODatabaseContext aDatabaseContext, NSArray objects, com.webobjects.eocontrol.EOFetchSpecification fetchSpecification, com.webobjects.eocontrol.EOEditingContext anEditingContext)

Invoked from objectsWithFetchSpecification after aDatabaseContext fetches objects using the criteria defined in fetchSpecification on behalf of anEditingContext.

databaseContextDidSelectObjects

public abstract void databaseContextDidSelectObjects( EODatabaseContext aDatabaseContext, com.webobjects.eocontrol.EOFetchSpecification fetchSpecification, EODatabaseChannel channel)

Invoked from the EODatabaseChannel method selectObjectsWithFetchSpecification to tell the delegate that channel selected the objects on behalf of aDatabaseContext as specified by fetchSpecification.

databaseContextFailedToFetchObject

public abstract boolean databaseContextFailedToFetchObject( EODatabaseContext aDatabaseContext, Object object, com.webobjects.eocontrol.EOGlobalID globalID)

Sent when a to-one fault cannot find its data in the database. The object is a cleared fault identified by globalID. If this method returns true, aDatabaseContext assumes that the delegate has handled the situation to its satisfaction, in whatever way it deemed appropriate (for example, by displaying an alert panel or initializing a fault object with new values). If it returns false or if the delegate method is not implemented, aDatabaseContext tracks the globalID of the offending object. If the tracked globalID is in the list of updated objects when prepareForSaveWithCoordinator is invoked, aDatabaseContext throws an exception.

To get a list of the objects that failed to fetch, see the method missingObjectGlobalIDs.

databaseContextNewPrimaryKey

public abstract NSDictionary databaseContextNewPrimaryKey( EODatabaseContext aDatabaseContext, Object object, EOEntity anEntity)

Sent when a newly inserted enterprise object doesn't already have a primary key set. This delegate method can be used to implement custom primary key generation. If the delegate is not implemented or returns null, then aDatabaseContext will send an EOAdaptorChannel a primaryKeyForNewRowWithEntity message in an attempt to generate the key.

The dictionary you return from this delegate method contains the attribute or attributes (if object has a compound primary key) that make up object's primary key.

databaseContextShouldFetchArrayFault

public abstract boolean databaseContextShouldFetchArrayFault( EODatabaseContext databaseContext, Object fault)

Invoked when a fault is fired, this delegate method lets you fine-tune the behavior of batch faulting. Delegates can fetch the array themselves (for example, by using the EODatabaseContext method batchFetchRelationship) and return false, or return true to allow the databaseContext to do the fetch itself. If databaseContext performs the fetch it will batch fault according to the batch count on the relationship being fetched.

databaseContextShouldFetchObjectFault

public abstract boolean databaseContextShouldFetchObjectFault( EODatabaseContext databaseContext, Object fault)

Invoked when a fault is fired, this delegate method lets you fine-tune the behavior of batch faulting. Delegates can fetch the fault themselves (for example, by using the EODatabaseContext method objectsWithFetchSpecification) and return false, or return true to allow databaseContext to perform the fetch. If databaseContext performs the fetch, it will batch fault according to the batch count on the entity being fetched.

databaseContextShouldFetchObjects

public abstract NSArray databaseContextShouldFetchObjects( EODatabaseContext aDatabaseContext, com.webobjects.eocontrol.EOFetchSpecification fetchSpecification, com.webobjects.eocontrol.EOEditingContext anEditingContext)

Invoked from objectsWithFetchSpecification to give the delegate the opportunity to satisfy anEditingContext's fetch request (using the criteria specified in fetchSpecification) from a local cache. If the delegate returns null, aDatabaseContext performs the fetch. Otherwise, the returned array is returned as the fetch result.

See Also: databaseContextDidFetchObjects

databaseContextShouldInvalidateObjectWithGlobalID

public abstract boolean databaseContextShouldInvalidateObjectWithGlobalID( EODatabaseContext aDatabaseContext, com.webobjects.eocontrol.EOGlobalID globalID, NSDictionary snapshot)

Invoked from invalidateObjectsWithGlobalIDs. Delegate can cause aDatabaseContext's object as identified by globalID to not be invalidated and that object's snapshot to not be cleared by returning false.

databaseContextShouldLockObjectWithGlobalID

public abstract boolean databaseContextShouldLockObjectWithGlobalID( EODatabaseContext aDatabaseContext, com.webobjects.eocontrol.EOGlobalID globalID, NSDictionary snapshot)

Invoked from lockObjectWithGlobalID. The delegate should return true if it wants the operation to proceed or false if it doesn't. Values from snapshot are used to create a qualifier from the attributes used for locking specified for the object's entity (that is, the object identified by globalID). Delegates can override the locking mechanism by implementing their own locking procedure and returning false. Methods that override the locking mechanism should throw an exception on the failure to lock exactly one object.

databaseContextShouldRaiseExceptionForLockFailure

public abstract boolean databaseContextShouldRaiseExceptionForLockFailure( EODatabaseContext aDatabaseContext, Throwable exception)

Invoked from lockObjectWithGlobalID. This method allows the delegate to suppress an exception that has occurred during aDatabaseContext's attempt to lock the object.

databaseContextShouldSelectObjects

public abstract boolean databaseContextShouldSelectObjects( EODatabaseContext aDatabaseContext, com.webobjects.eocontrol.EOFetchSpecification fetchSpecification, EODatabaseChannel channel)

Invoked from the EODatabaseChannel method selectObjectsWithFetchSpecification to tell the delegate that channel will select objects on behalf of aDatabaseContext as specified by fetchSpecification. The delegate should not modify fetchSpecification's qualifier or fetch order. If the delegate returns true the channel will go ahead and select the object; if the delegate returns false (possibly after issuing custom SQL against the adaptor) the channel will skip the select and return.

databaseContextShouldUpdateCurrentSnapshot

public abstract NSDictionary databaseContextShouldUpdateCurrentSnapshot( EODatabaseContext aDatabaseContext, NSDictionary currentSnapshot, NSDictionary newSnapshot, com.webobjects.eocontrol.EOGlobalID globalID, EODatabaseChannel channel)

Invoked from the EODatabaseChannel method fetchObject when aDatabaseContext already has a snapshot (currentSnapshot) for a row fetched from the database. This method is invoked without first checking whether the snapshots are equivalent (the check would be too expensive to do in the common case), so the receiver may be passed equivalent snapshots. The default behavior is to not update an older snapshot with newSnapshot. The delegate can override this behavior by returning a dictionary (possibly newSnapshot) that will be recorded as the updated snapshot. This results in aDatabaseContext broadcasting an EOObjectsChangedInStoreNotification, causing the object store hierarchy to invalidate existing objects (as identified by globalID) built from the obsolete snapshot. You can use this method to achieve the same effect as using a EOFetchSpecification with setRefreshesRefetchedObjects: set to true-that is, it allows you to overwrite in-memory object values with values from the database that may have been changed by someone else.

Returning currentSnapshot (or null) causes the aDatabaseContext to perform the default behavior (that is, not updating the older snapshot).

databaseContextShouldUsePessimisticLock

public abstract boolean databaseContextShouldUsePessimisticLock( EODatabaseContext databaseContext, com.webobjects.eocontrol.EOFetchSpecification fetchSpecification, EODatabaseChannel channel)

Invoked from the EODatabaseChannel method selectObjectsWithFetchSpecification regardless of the update strategy specified on channel's databaseContext. The delegate should not modify the qualifier or fetch order contained in fetchSpecification. If the delegate returns true the channel locks the rows being selected; if the delegate returns false the channel selects the rows without locking.

databaseContextWillFireArrayFaultForGlobalID

public abstract void databaseContextWillFireArrayFaultForGlobalID( EODatabaseContext dbContext, com.webobjects.eocontrol.EOGlobalID globalID, EORelationship relationship, com.webobjects.eocontrol.EOFetchSpecification fetchSpec, com.webobjects.eocontrol.EOEditingContext edContext)

Invoked just before the Framework-generated fetch specification, fetchSpec, is used to clear the fault for the specified globalID and relationship.

Note: It is very dangerous to modify the fetch specification.

databaseContextWillFireObjectFaultForGlobalID

public abstract void databaseContextWillFireObjectFaultForGlobalID( EODatabaseContext dbContext, com.webobjects.eocontrol.EOGlobalID globalID, com.webobjects.eocontrol.EOFetchSpecification fetchSpec, com.webobjects.eocontrol.EOEditingContext edContext)

Invoked just before the Framework-generated fetch specification, fetchSpec, is used to clear the fault for the specified globalID.

Note: It is very dangerous to modify the fetch specification.

databaseContextWillOrderAdaptorOperations

public abstract NSArray databaseContextWillOrderAdaptorOperations( EODatabaseContext aDatabaseContext, NSArray databaseOperations)

Sent from ownsGlobalID. If the delegate responds to this message, it must return an array of EOAdaptorOperations that aDatabaseContext can then submit to an EOAdaptorChannel for execution. The delegate can fabricate its own array by asking each of the databaseOperations for its list of EOAdaptorOperations, and adding them to the array which will eventually be returned by this method. The delegate is free to optimize, order, or transform the list in whatever way it deems necessary. This method is useful for applications that need a special ordering of the EOAdaptorOperations so as not to violate any database referential integrity constraints.

databaseContextWillPerformAdaptorOperations

public abstract NSArray databaseContextWillPerformAdaptorOperations( EODatabaseContext aDatabaseContext, NSArray adaptorOperations, EOAdaptorChannel adaptorChannel)

Sent from ownsGlobalID. The delegate can return a new adaptorOperations array which aDatabaseContext will hand to adaptorChannel for execution in place of the old array of EOAdaptorOperations. This method is useful for applications that need a special ordering of the EOAdaptorOperations so as not to violate any database referential integrity constraints.

databaseContextWillRunLoginPanelToOpenDatabaseChannel

public abstract boolean databaseContextWillRunLoginPanelToOpenDatabaseChannel( EODatabaseContext aDatabaseContext, NSArray adaptorOperations, EOAdaptorChannel adaptorChannel)

When aDatabaseContext is about to use a channel, it checks to see if the channel's corresponding EOAdaptorChannel is open. If it isn't, it attempts to open the EOAdaptorChannel by sending it an openChannel message. If that doesn't succeed, aDatabaseContext asks the EOAdaptorChannel's adaptor to run the login panel and open the channel. aDatabaseContext gives the delegate a chance to intervene in this by invoking this delegate method. The delegate can return false to stop aDatabaseContext from running the login panel. In this case, the delegate is responsible for opening the channel. If the delegate returns true, aDatabaseContext runs the login panel.