com.webobjects.eoaccess
Interface EODatabaseContext.Delegate

Enclosing interface:

EODatabaseContext

public static interface EODatabaseContext.Delegate

This interface defines a delegate to EODatabaseContext to to handle specific requests that are ordinarily handled by EODatabaseContext. The delegate can use these methods to preempt the operations, modify results, or simply track activity.

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

The EODatabaseContext delegate methods can be used to intervene when objects are created and when they're fetched from the database. This gives one 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.

Method Summary

void	databaseContextDidFetchObjects(EODatabaseContext dbCtxt, NSArray array, EOFetchSpecification fetchSpec, EOEditingContext ec) Invoked from objectsWithFetchSpecification after fetching objects into the editing context ec using fetchSpec.
void	databaseContextDidSelectObjects(EODatabaseContext dbCtxt, EOFetchSpecification fetchSpec, EODatabaseChannel dbChannel) Invoked from the EODatabaseChannel method selectObjectsWithFetchSpecification to tell the delegate that dbChannel has selected the objects on behalf of dbCtxt as specified by fetchSpec.
boolean	databaseContextFailedToFetchObject(EODatabaseContext dbCtxt, Object object, EOGlobalID gid) Invoked when a to-one fault cannot find its data in the database.
NSDictionary	databaseContextNewPrimaryKey(EODatabaseContext dbCtxt, Object object, EOEntity entity) Invoked if the newly inserted Enterprise Object object doesn't have a primary key set.
boolean	databaseContextShouldFetchArrayFault(EODatabaseContext dbCtxt, Object object) Invoked when a fault is fired, this delegate method lets you fine-tune the behavior of batch faulting.
boolean	databaseContextShouldFetchObjectFault(EODatabaseContext dbCtxt, Object object) Invoked when a fault is fired, this delegate method lets you fine-tune the behavior of batch faulting.
NSArray	databaseContextShouldFetchObjects(EODatabaseContext dbCtxt, EOFetchSpecification fetchSpec, EOEditingContext ec) Invoked from objectsWithFetchSpecification to give the delegate the opportunity to satisfy ec's fetch request (using the criteria specified in fetchSpec) from a local cache.
boolean	databaseContextShouldHandleDatabaseException(EODatabaseContext dbCtxt, Throwable exception) Invoked when an exception is thrown that might be handled by reconnecting to the database.
boolean	databaseContextShouldInvalidateObjectWithGlobalID(EODatabaseContext dbCtxt, EOGlobalID gid, NSDictionary dic) Invoked from invalidateObjectsWithGlobalIDs .
boolean	databaseContextShouldLockObjectWithGlobalID(EODatabaseContext dbCtxt, EOGlobalID gid, NSDictionary dic) Invoked from lockObjectWithGlobalID.
boolean	databaseContextShouldRaiseExceptionForLockFailure(EODatabaseContext dbCtxt, Throwable exception) Invoked from lockObjectWithGlobalID.
boolean	databaseContextShouldSelectObjects(EODatabaseContext dbCtxt, EOFetchSpecification fetchSpec, EODatabaseChannel dbChannel) Invoked from the EODatabaseChannel method selectObjectsWithFetchSpecification to tell the delegate that the database channel dbChannel will select objects on behalf of the database context dbCtxt as specified by fetchSpec.
NSDictionary	databaseContextShouldUpdateCurrentSnapshot(EODatabaseContext dbCtxt, NSDictionary dic, NSDictionary dic2, EOGlobalID gid, EODatabaseChannel dbChannel) Invoked from the EODatabaseChannel method fetchObject when the database context already has a snapshot for a row fetched from the database.
boolean	databaseContextShouldUsePessimisticLock(EODatabaseContext dbCtxt, EOFetchSpecification fetchSpec, EODatabaseChannel dbChannel) Invoked from the EODatabaseChannel method selectObjectsWithFetchSpecification.
void	databaseContextWillFireArrayFaultForGlobalID(EODatabaseContext dbCtxt, EOGlobalID gid, EORelationship rel, EOFetchSpecification fetchSpec, EOEditingContext ec) Invoked just before the Framework-generated fetch specification, fetchSpec, is used to clear the fault for the specified globalID (gid) and relationship(rel).
void	databaseContextWillFireObjectFaultForGlobalID(EODatabaseContext dbCtxt, EOGlobalID gid, EOFetchSpecification fetchSpec, EOEditingContext ec) Invoked just before the Framework-generated fetch specification, fetchSpec, is used to clear the fault for the specified globalID, gid.
NSArray	databaseContextWillOrderAdaptorOperations(EODatabaseContext dbCtxt, NSArray databaseOps) Invoked from performChanges.
NSArray	databaseContextWillPerformAdaptorOperations(EODatabaseContext dbCtxt, NSArray adaptorOps, EOAdaptorChannel adChannel) Invoked from performChanges to allow the delegate to send a different array of EOAdaptorOperations to be executed by dbCtx.
boolean	databaseContextWillRunLoginPanelToOpenDatabaseChannel(EODatabaseContext dbCtx, EODatabaseChannel dbChannel) Allows the delegate to determine whether the database context dbCtx should run the adaptor login panel and open the adaptor channel associated with the database channel dbChannel, if the adaptor channel is not already open.

Method Detail

databaseContextDidFetchObjects

public void databaseContextDidFetchObjects(EODatabaseContext dbCtxt,
                                           NSArray array,
                                           EOFetchSpecification fetchSpec,
                                           EOEditingContext ec)

Invoked from objectsWithFetchSpecification after fetching objects into the editing context ec using fetchSpec. The array parameter contains the fetched objects. The delegate may take whatever action is needed.

Parameters:

dbCtxt - The database context.

array - The results of the fetch.

fetchSpec - The criteria to select and order a group of database records.

ec - The EOEditingContext into which the objects were fetched.

See Also:

databaseContextShouldFetchObjects(EODatabaseContext dbCtxt, EOFetchSpecification fetchSpec, EOEditingContext ec), databaseContextShouldFetchObjectFault( EODatabaseContext dbCtxt, Object object), EODatabaseContext.objectsWithFetchSpecification(EOFetchSpecification fetchSpecification, EOEditingContext anEditingContext)

databaseContextDidSelectObjects

public void databaseContextDidSelectObjects(EODatabaseContext dbCtxt,
                                            EOFetchSpecification fetchSpec,
                                            EODatabaseChannel dbChannel)

Invoked from the EODatabaseChannel method selectObjectsWithFetchSpecification to tell the delegate that dbChannel has selected the objects on behalf of dbCtxt as specified by fetchSpec. The delegate may take whatever action is needed.

Parameters:

dbCtxt - The database context.

fetchSpec - The criteria to select and order a group of database records.

dbChannel - The database channel.

See Also:

databaseContextShouldSelectObjects( EODatabaseContext dbCtxt, EOFetchSpecification fetchSpec, EODatabaseChannel dbChannel), EODatabaseChannel.selectObjectsWithFetchSpecification( EOFetchSpecification fetchSpecification, EOEditingContext context)

databaseContextFailedToFetchObject

public boolean databaseContextFailedToFetchObject(EODatabaseContext dbCtxt,
                                                  Object object,
                                                  EOGlobalID gid)

Invoked when a to-one fault cannot find its data in the database. object is a cleared fault identified by the globalID gid. If this method returns true, dbCtxt assumes that the delegate set the information into the object, and created a snapshot of it, correcting the problem.

If the delegate returns false or if the delegate method is not implemented, dbCtxt tracks the gid of the offending object. If the tracked gid is in the list of updated objects when changes to the editing context are saved, the database context throws an exception. The method missingObjectGlobalIDs can be used to get a list of objects that failed to fetch.

Parameters:

dbCtxt - The database context.

object - A cleared fault.

gid - The globalID that identifies object.

Returns:

Should return true if the faulting problem has been handled, false otherwise.

See Also:

EODatabaseContext.missingObjectGlobalIDs(), EODatabaseContext.prepareForSaveWithCoordinator(EOObjectStoreCoordinator coordinator, EOEditingContext editingContext)

databaseContextNewPrimaryKey

public NSDictionary databaseContextNewPrimaryKey(EODatabaseContext dbCtxt,
                                                 Object object,
                                                 EOEntity entity)

Invoked if the newly inserted Enterprise Object object doesn't have a primary key set. The delegate can implement custom primary key generation, or return null, in which case the database context dbCtxt will send a primaryKeyForNewRowWithEntity message to an EOAdaptorChannel to generate the key.

Should return a dictionary containing the attribute or attributes (if object has a compound primary key) that make up object's primary key, or null to have the database context generate the primary key.

Parameters:

dbCtxt - The database context.

object - A newly inserted Enterprise Object.

entity - The EOEntity object for primary key generation.

Returns:

Should return a dictionary containing the attribute or attributes that make up object's primary key, or null.

See Also:

EOAdaptorChannel.primaryKeyForNewRowWithEntity( EOEntity entity)

databaseContextShouldFetchArrayFault

public boolean databaseContextShouldFetchArrayFault(EODatabaseContext dbCtxt,
                                                    Object object)

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

Parameters:

dbCtxt - The database context.

object - The array fault to be fetched.

Returns:

Should return true to permit the database context to fetch the array fault, false otherwise.

See Also:

databaseContextShouldFetchObjectFault(EODatabaseContext dbCtxt, Object object)

databaseContextShouldFetchObjectFault

public boolean databaseContextShouldFetchObjectFault(EODatabaseContext dbCtxt,
                                                     Object object)

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 dbCtxt to fetch the fault. If the database context performs the fetch, it will batch fault according to the batch count on the entity being fetched.

Parameters:

dbCtxt - The database context.

object - The fault to be fetched.

Returns:

Should return true to permit the database context to fetch the fault, false otherwise.

See Also:

databaseContextShouldFetchArrayFault( EODatabaseContext dbCtxt, Object object), EODatabaseContext.objectsWithFetchSpecification(EOFetchSpecification fetchSpecification, EOEditingContext anEditingContext)

databaseContextShouldFetchObjects

public NSArray databaseContextShouldFetchObjects(EODatabaseContext dbCtxt,
                                                 EOFetchSpecification fetchSpec,
                                                 EOEditingContext ec)

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

Parameters:

dbCtxt - The database context.

fetchSpec - The criteria to select and order a group of database records.

ec - The EOEditingContext into which to fetch objects.

Returns:

The array of objects corresponding to fetchSpec, or null.

See Also:

databaseContextDidFetchObjects(EODatabaseContext dbCtxt, NSArray array, EOFetchSpecification fetchSpec, EOEditingContext ec), EODatabaseContext.objectsWithFetchSpecification(EOFetchSpecification fetchSpecification, EOEditingContext anEditingContext)

databaseContextShouldHandleDatabaseException

public boolean databaseContextShouldHandleDatabaseException(EODatabaseContext dbCtxt,
                                                            Throwable exception)

Invoked when an exception is thrown that might be handled by reconnecting to the database. The delegate should return true to permit the database context to handle the exception by automatically trying to reconnect to the database, for example, if the delegate determines that the exception was due to a dropped connection.

The delegate should return false to handle the exception itself with a reconnection strategy appropriate to the exception and application. In this case, the database context assumes that all reconnection and associated clean-up have been performed by the delegate and it immediately retries the operation that generated the original exception.

If exception is not one that can be handled by reconnecting to the database, the delegate should simply re-throw it. If this method is not implemented, reconnection will be handled by the response of the adaptor to isDroppedConnectionException.

Parameters:

dbCtxt - The database context.

exception - An exception thrown during database operations.

Returns:

Should return true to permit the database context to handle excpetion, false to have the delegate evaluate and handle it.

databaseContextShouldInvalidateObjectWithGlobalID

public boolean databaseContextShouldInvalidateObjectWithGlobalID(EODatabaseContext dbCtxt,
                                                                 EOGlobalID gid,
                                                                 NSDictionary dic)

Invoked from invalidateObjectsWithGlobalIDs . The delegate should return false to prevent the object as identified by gid from being invalidated, and its snapshot from being cleared.

Parameters:

dbCtxt - The database context.

gid - The globalID identifying an object to be invalidated.

dic - The snapshot of an object to be invalidated.

Returns:

false to prevent invalidation of the object identified by gid, true to permit invalidation.

See Also:

EODatabaseContext.invalidateObjectsWithGlobalIDs(NSArray globalIDs)

databaseContextShouldLockObjectWithGlobalID

public boolean databaseContextShouldLockObjectWithGlobalID(EODatabaseContext dbCtxt,
                                                           EOGlobalID gid,
                                                           NSDictionary dic)

Invoked from lockObjectWithGlobalID. The delegate should return true to proceed to lock the object identified by gid, false to cause lockObjectWithGlobalID to return without locking.

Delegates can override the locking mechanism by implementing their own locking procedure and returning false. Values from dic can be used to create a qualifier from the attributes used for locking specified for the object's entity. If custom locking is implemented, the delegate should throw an exception if it fails to lock exactly one object.

Parameters:

dbCtxt - The database context

gid - The globalID that identifies the object to lock.

dic - The current snapshot of the object identified by gid which may be used to supply attributes to implement custom locking.

Returns:

Should return true to have the database context lock the object, false to implement custom locking by the delegate, or to return without locking the object.

See Also:

EODatabaseContext.lockObjectWithGlobalID(EOGlobalID gid, EOEditingContext ec)

databaseContextShouldRaiseExceptionForLockFailure

public boolean databaseContextShouldRaiseExceptionForLockFailure(EODatabaseContext dbCtxt,
                                                                 Throwable exception)

Invoked from lockObjectWithGlobalID. This method allows the delegate to suppress exception that was thrown during dbCtxt's attempt to lock the object.

Parameters:

dbCtxt - The database context.

exception - A exception thrown due to locking failure.

Returns:

Should return true to allow exception to be thrown, false to suppress it.

See Also:

EODatabaseContext.lockObjectWithGlobalID(EOGlobalID globalID, EOEditingContext anEditingContext)

databaseContextShouldSelectObjects

public boolean databaseContextShouldSelectObjects(EODatabaseContext dbCtxt,
                                                  EOFetchSpecification fetchSpec,
                                                  EODatabaseChannel dbChannel)

Invoked from the EODatabaseChannel method selectObjectsWithFetchSpecification to tell the delegate that the database channel dbChannel will select objects on behalf of the database context dbCtxt as specified by fetchSpec. If the delegate returns true, the channel will proceed to select the object. If the delegate returns false (possibly after issuing custom SQL against the adaptor) the channel will skip the select and return immediately.

The delegate should not modify fetchSpec's qualifier or fetch order.

Parameters:

dbCtxt - The database context.

fetchSpec - The criteria to select and order a group of database records.

dbChannel - The database channel.

Returns:

Should return true to allow the select to proceed, false to cause dbChannel to return immediately.

See Also:

EODatabaseChannel.selectObjectsWithFetchSpecification( EOFetchSpecification fetchSpecification, EOEditingContext context)

databaseContextShouldUpdateCurrentSnapshot

public NSDictionary databaseContextShouldUpdateCurrentSnapshot(EODatabaseContext dbCtxt,
                                                               NSDictionary dic,
                                                               NSDictionary dic2,
                                                               EOGlobalID gid,
                                                               EODatabaseChannel dbChannel)

Invoked from the EODatabaseChannel method fetchObject when the database context already has a snapshot for a row fetched from the database. This method is invoked without first checking whether the current snapshot dic and new snapshot dic2 are equivalent.

The default behavior is not to update the current snapshot with the new snapshot. The delegate can override this behavior by returning dic2, or some other snapshot, to be recorded as the updated snapshot for the object, which is identified by the globalID gid. In this case, dbCtxt broadcasts an ObjectsChangedInStoreNotification, indicating that all objects corresponding to this globalID are now invalid.

Returning either dic or null prevents the current snapshot from being replaced.

Parameters:

dbCtxt - The database context.

dic - The current snapshot for the object identified by gid.

dic2 - The new snapshot for the object identified by gid.

gid - The globalID identifying the fetched object for which dic is the current snapshot.

dbChannel - The database channel.

Returns:

Should return dic2 or some other snapshot with which to update the snapshot recorded for gid; dic or null to leave the currently recorded snapshot unmodified.

See Also:

EODatabaseChannel.fetchObject()

databaseContextShouldUsePessimisticLock

public boolean databaseContextShouldUsePessimisticLock(EODatabaseContext dbCtxt,
                                                       EOFetchSpecification fetchSpec,
                                                       EODatabaseChannel dbChannel)

Invoked from the EODatabaseChannel method selectObjectsWithFetchSpecification. If the delegate returns true, the channel locks the rows being selected. If the delegate returns false, the channel selects the rows without locking.

The delegate should not modify fetchSpec's qualifier or fetch order.

Parameters:

dbCtxt - The database context.

fetchSpec - The criteria to select and order a group of database records.

dbChannel - The database channel.

Returns:

Should return true to instruct dbChannel to lock selected database rows, false to select without locking.

See Also:

EODatabaseChannel.selectObjectsWithFetchSpecification( EOFetchSpecification fetchSpecification, EOEditingContext context)

databaseContextWillFireArrayFaultForGlobalID

public void databaseContextWillFireArrayFaultForGlobalID(EODatabaseContext dbCtxt,
                                                         EOGlobalID gid,
                                                         EORelationship rel,
                                                         EOFetchSpecification fetchSpec,
                                                         EOEditingContext ec)

Invoked just before the Framework-generated fetch specification, fetchSpec, is used to clear the fault for the specified globalID (gid) and relationship(rel). The delegate can take whatever action is needed.

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

Parameters:

dbCtxt - The database context.

gid - The globalID identifying the array fault to be cleared.

rel - The name of the relationship associated with the array fault gid.

fetchSpec - The criteria to select and order a group of database records.

ec - The EOEditingContext.

databaseContextWillFireObjectFaultForGlobalID

public void databaseContextWillFireObjectFaultForGlobalID(EODatabaseContext dbCtxt,
                                                          EOGlobalID gid,
                                                          EOFetchSpecification fetchSpec,
                                                          EOEditingContext ec)

Invoked just before the Framework-generated fetch specification, fetchSpec, is used to clear the fault for the specified globalID, gid. The delegate can take whatever action is needed.

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

Parameters:

dbCtxt - The database context.

gid - The globalID identifying the fault to be cleared.

fetchSpec - The criteria to select and order a group of database records.

ec - The EOEditingContext.

databaseContextWillOrderAdaptorOperations

public NSArray databaseContextWillOrderAdaptorOperations(EODatabaseContext dbCtxt,
                                                         NSArray databaseOps)

Invoked from performChanges. If the delegate responds to this message, it must return an array of EOAdaptorOperations that the database context can submit to an EOAdaptorChannel for execution. The delegate can fabricate its own array by asking each of the EODatabaseOperation objects in databaseOps for its list of EOAdaptorOperations, and adding them to the array which will eventually be returned by this method.

The delegate may optimize, order, or transform the list in any way it deems necessary. This is useful for applications that need a special ordering of the EOAdaptorOperations so as not to violate any database referential integrity constraints.

Parameters:

dbCtxt - The database context.

databaseOps - An array of EODatabaseOperation objects.

Returns:

Should return an array of adaptor operations for the database context to perform.

See Also:

EODatabaseContext.performChanges(), EOAdaptorOperation, EODatabaseOperation

databaseContextWillPerformAdaptorOperations

public NSArray databaseContextWillPerformAdaptorOperations(EODatabaseContext dbCtxt,
                                                           NSArray adaptorOps,
                                                           EOAdaptorChannel adChannel)

Invoked from performChanges to allow the delegate to send a different array of EOAdaptorOperations to be executed by dbCtx. The delegate may return adaptorOps unchanged.

This method is useful for applications that need a special ordering of the EOAdaptorOperations so as not to violate any database referential integrity constraints.

Parameters:

dbCtxt - The database context.

adaptorOps - The array of adaptor operations that will be executed by default.

adChannel - An adaptor channel.

Returns:

Should return a new array of adaptor operations for the database context to execute, or adaptorOps.

See Also:

EODatabaseContext.performChanges(), EOAdaptorOperation, EOAdaptorChannel

databaseContextWillRunLoginPanelToOpenDatabaseChannel

public boolean databaseContextWillRunLoginPanelToOpenDatabaseChannel(EODatabaseContext dbCtx,
                                                                     EODatabaseChannel dbChannel)

Allows the delegate to determine whether the database context dbCtx should run the adaptor login panel and open the adaptor channel associated with the database channel dbChannel, if the adaptor channel is not already open. The delegate should return true to permit the database context to run the login panel, false to prevent it. If the delegate returns false, it is responsible for opening the adaptor channel itself.

Parameters:

dbCtx - The database context.

dbChannel - The database channel.

Returns:

Should return true to permit to run the adaptor login panel and open the adaptor channel, false to prevent it.

See Also:

EOAdaptorChannel.openChannel()