PATH
Documentation > WebObjects 4.5 >
EOAccess Reference
(informal protocol)
Declared in: EOAccess/EODatabaseContext.h
Protocol 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:
- databaseContext:didSelectObjectsWithFetchSpecification:databaseChannel:
- databaseContext:shouldSelectObjectsWithFetchSpecification:databaseChannel:
- databaseContext:shouldUpdateCurrentSnapshot:newSnapshot:globalID:databaseChannel:
- databaseContext:shouldUsePessimisticLockWithFetchSpecification: databaseChannel:
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 ( databaseContext:newPrimaryKeyForObject:entity:),
how and if objects are locked ( databaseContext:shouldLockObjectWithGlobalID:snapshot:),
what fetch specification is used to fetch objects ( databaseContext:shouldSelectObjectsWithFetchSpecification:databaseChannel:),
how batch faulting is performed ( databaseContext:shouldFetchArrayFault: and databaseContext:shouldFetchObjectFault:),
and so on. For more information, see the individual delegate method
descriptions.
Instance Methods
- (void)databaseContext:(EODatabaseContext
*)aDatabaseContext
didFetchObjects:(NSArray *)objects
fetchSpecification:(EOFetchSpecification
*)fetchSpecification
editingContext:(EOEditingContext
*)anEditingContext
Invoked from objectsWithFetchSpecification:editingContext: after aDatabaseContext fetches objects using
the criteria defined in fetchSpecification on
behalf of anEditingContext.
See Also:
- databaseContext:shouldFetchObjectFault:
- (void)databaseContext:(EODatabaseContext
*)aDatabaseContext
didSelectObjectsWithFetchSpecification:(EOFetchSpecification
*)fetchSpecification
databaseChannel:(EODatabaseChannel
*)channel
Invoked from the EODatabaseChannel method selectObjectsWithFetchSpecification:editingContext: to
tell the delegate that channel selected
the objects on behalf of aDatabaseContext as specified
by fetchSpecification.
See Also:
- databaseContext:shouldSelectObjectsWithFetchSpecification:databaseChannel:
- (BOOL)databaseContext:(EODatabaseContext
*)aDatabaseContext
failedToFetchObject:(id)object
globalID:(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 YES, 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 NO 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:editingContext: is
invoked, aDatabaseContext raises an
exception.
To get a list of the objects that failed to fetch, see the
method missingObjectGlobalIDs.
- (NSDictionary *)databaseContext:(EODatabaseContext
*)aDatabaseContext
newPrimaryKeyForObject:(id)object
entity:(EOEntity *)entity
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 nil, 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.
- (BOOL)databaseContext:(EODatabaseContext
*)databaseContext
shouldFetchArrayFault:(id)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:forSourceObjects:editingContext:)
and return NO, or return YES 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.
See Also:
- databaseContext:shouldFetchObjectFault:
- (BOOL)databaseContext:(EODatabaseContext
*)databaseContext
shouldFetchObjectFault:(id)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:editingContext:)
and return NO, or return YES 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.
See Also:
- databaseContext:shouldFetchArrayFault:
- (NSArray *)databaseContext:(EODatabaseContext
*)aDatabaseContext
shouldFetchObjectsWithFetchSpecification:(EOFetchSpecification
*)fetchSpecification
editingContext:(EOEditingContext
*)anEditingContext
Invoked from objectsWithFetchSpecification:editingContext: 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 nil, aDatabaseContext performs
the fetch. Otherwise, the returned array is returned as the fetch
result.
See Also:
databaseContext:didFetchObjects:fetchSpecification:editingContext:
- (BOOL)databaseContext:(EODatabaseContext
*)aDatabaseContext
shouldInvalidateObjectWithGlobalID:(EOGlobalID
*)globalId
snapshot:(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 NO.
- (BOOL)databaseContext:(EODatabaseContext
*)aDatabaseContext
shouldLockObjectWithGlobalID:(EOGlobalID
*)globalID
snapshot:(NSDictionary *)snapshot
Invoked from lockObjectWithGlobalID:editingContext:.
The delegate should return YES if it wants the operation to proceed
or NO 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 NO. Methods that override the locking mechanism should raise an
exception on the failure to lock exactly one object.
- (BOOL)databaseContext:(EODatabaseContext
*)aDatabaseContext
shouldRaiseExceptionForLockFailure:(NSException
*)exception
Invoked from lockObjectWithGlobalID:editingContext:.
This method allows the delegate to suppress an exception that
has occurred during aDatabaseContext's
attempt to lock the object.
- (BOOL)databaseContext:(EODatabaseContext
*)aDatabaseContext
shouldSelectObjectsWithFetchSpecification:(EOFetchSpecification
*)fetchSpecification
databaseChannel:(EODatabaseChannel
*)channel
Invoked from the EODatabaseChannel method selectObjectsWithFetchSpecification:editingContext: 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 YES the channel
will go ahead and select the object; if the delegate returns NO (possibly
after issuing custom SQL against the adaptor) the channel will
skip the select and return.
- (NSDictionary *)databaseContext:(EODatabaseContext
*)aDatabaseContext
shouldUpdateCurrentSnapshot:(NSDictionary
*)currentSnapshot
newSnapshot:(NSDictionary *)newSnapshot
globalID:(EOGlobalID *)globalID
databaseChannel:(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 YES-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 nil)
causes the aDatabaseContext to perform
the default behavior (that is, not updating the older snapshot).
- (BOOL)databaseContext:(EODatabaseContext
*)databaseContext
shouldUsePessimisticLockWithFetchSpecification:(EOFetchSpecification
*)fetchSpecification
databaseChannel:(EODatabaseChannel
*)channel
Invoked from the EODatabaseChannel method selectObjectsWithFetchSpecification:editingContext: 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 YES the channel locks the rows being selected; if the delegate
returns NO the channel selects the rows without locking.
- (void)databaseContext:(EODatabaseContext
*)dbContext
willFireArrayFaultForGlobalID:(EOGlobalID
*)globalID
relationship:(EORelationship *)relationship
withFetchSpecification:(EOFetchSpecification
*)fetchSpec
editingContext:(EOEditingContext
*)edContext
Invoked just before the Framework-generated
fetch specification, fetchSpec, is
used to clear the fault for the specified globalID and relationship.
| It is very dangerous to modify the fetch specification. |
- (void)databaseContext:(EODatabaseContext
*)dbContext
willFireObjectFaultForGlobalID:(EOGlobalID
*)globalID
withFetchSpecification:(EOFetchSpecification
*)fetchSpec
editingContext:(EOEditingContext
*)edContext
Invoked just before the Framework-generated
fetch specification, fetchSpec, is
used to clear the fault for the specified globalID.
| It is very dangerous to modify the fetch specification. |
- (NSArray *)databaseContext:(EODatabaseContext
*)aDatabaseContext
willOrderAdaptorOperationsFromDatabaseOperations:(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.
- (NSArray *)databaseContext:(EODatabaseContext
*)aDatabaseContext
willPerformAdaptorOperations:(NSArray
*)adaptorOperations
adaptorChannel:(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.
- (BOOL)databaseContext:(EODatabaseContext
*)aDatabaseContext
willRunLoginPanelToOpenDatabaseChannel:(EODatabaseChannel
*)channel
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 NO to stop aDatabaseContext from running
the login panel. In this case, the delegate is responsible for opening
the channel. If the delegate returns YES, aDatabaseContext runs
the login panel.