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.