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.
