PATH
Documentation > WebObjects 4.5 >
EOAdaptor Reference
(informal interface)
Package:
com.apple.yellow.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
public abstract void databaseContextDidFetchObjects(
EODatabaseContext aDatabaseContext,
NSArray objects,
com.apple.yellow.eocontrol.EOFetchSpecification fetchSpecification,
com.apple.yellow.eocontrol.EOEditingContext anEditingContext)
Invoked from
objectsWithFetchSpecification after
aDatabaseContext fetches
objects using
the criteria defined in
fetchSpecification on
behalf of
anEditingContext.
See Also:
databaseContextShouldFetchObjectFault
public abstract void databaseContextDidSelectObjects(
EODatabaseContext aDatabaseContext,
com.apple.yellow.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.
See Also:
databaseContextShouldSelectObjects
public abstract boolean databaseContextFailedToFetchObject(
EODatabaseContext aDatabaseContext,
Object object,
com.apple.yellow.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.
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.
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.
See Also:
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.
See Also:
databaseContextShouldFetchArrayFault
public abstract NSArray databaseContextShouldFetchObjects(
EODatabaseContext aDatabaseContext,
com.apple.yellow.eocontrol.EOFetchSpecification fetchSpecification,
com.apple.yellow.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
public abstract boolean databaseContextShouldInvalidateObjectWithGlobalID(
EODatabaseContext aDatabaseContext,
com.apple.yellow.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.
public abstract boolean databaseContextShouldLockObjectWithGlobalID(
EODatabaseContext aDatabaseContext,
com.apple.yellow.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.
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.
public abstract boolean databaseContextShouldSelectObjects(
EODatabaseContext aDatabaseContext,
com.apple.yellow.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.
public abstract NSDictionary databaseContextShouldUpdateCurrentSnapshot(
EODatabaseContext aDatabaseContext,
NSDictionary currentSnapshot,
NSDictionary newSnapshot,
com.apple.yellow.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).
public abstract boolean databaseContextShouldUsePessimisticLock(
EODatabaseContext databaseContext,
com.apple.yellow.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.
public abstract void databaseContextWillFireArrayFaultForGlobalID(
EODatabaseContext dbContext,
com.apple.yellow.eocontrol.EOGlobalID globalID,
EORelationship relationship,
com.apple.yellow.eocontrol.EOFetchSpecification fetchSpec,
com.apple.yellow.eocontrol.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. |
public abstract void databaseContextWillFireObjectFaultForGlobalID(
EODatabaseContext dbContext,
com.apple.yellow.eocontrol.EOGlobalID globalID,
com.apple.yellow.eocontrol.EOFetchSpecification fetchSpec,
com.apple.yellow.eocontrol.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. |
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.
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.
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.
