EODatabaseContext
Inherits from: EOCooperatingObjectStore (EOControl) : EOObjectStore (EOControl) : NSObject
Package: com.apple.yellow.eoaccess
Class Description
An EODatabaseContext object is an EOObjectStore (EOControl) for accessing relational databases, creating and saving objects based on EOEntity definitions in an EOModel.
An EODatabaseContext represents a single connection to a database server, and it determines the updating and locking strategy used by its EODatabaseChannel objects. An EODatabaseContext has a corresponding EODatabase object. If the server supports multiple concurrent transactions, the EODatabase object may have several database contexts. If the server and adaptor support it, a database context may in turn have several database channels, which handle access to the data on the server.
For a more information on EODatabaseContext, see the sections:
- "EODatabaseContext's Interaction with Other Classes"
- "Creating and Using an EODatabaseContext"
- "Fetching and Saving Objects"
- "Using a Custom Query"
- "Faulting"
- "Delegate Methods"
- "Snapshots"
- "Updating And Locking Strategies"
Constants
EODatabaseContext defines the following constants:
Constant | Type | Description |
UpdateWithOptimisticLocking | int
|
Identifies the locking strategy as optimistic. |
UpdateWithPessimisticLocking | int
|
Identifies the locking strategy as pessimistic |
UpdateWithNoLocking | int
|
Identifies the locking strategy as no locking |
CustomQueryExpressionHintKey | String | A key in an EOFetchSpecification's hint dictionary |
StoredProcedureNameHintKey | String | A key in an EOFetchSpecification's hint dictionary |
DatabaseContextKey | String | A key in an GenericAdaptorException 's
userInfo dictionary |
DatabaseOperationsKey | String | A key in an GenericAdaptorException 's
userInfo dictionary |
FailedDatabaseOperationKey | String | A key in an GenericAdaptorException 's
userInfo dictionary |
In addition, EODatabaseContext defines a constant for the name of the notification it posts. For more information on the notification, see "Notifications" .
Method Types
- Constructors
- EODatabaseContext
- Fetching objects
- objectsWithFetchSpecification
- objectsForSourceGlobalID
- arrayFaultWithSourceGlobalID
- faultForGlobalID
- faultForRawRow
- batchFetchRelationship
- missingObjectGlobalIDs
- Enabling shared object loading
- setSharedObjectLoadingEnabled
- isSharedObjectLoadingEnabled
- Accessing the adaptor context
- adaptorContext
- Managing the database connection
- forceConnectionWithModel
- handleDroppedConnection
- Accessing the database object
- database
- Accessing the coordinator
- coordinator
- Managing channels
- availableChannel
- registerChannel
- registeredChannels
- unregisterChannel
- hasBusyChannels
- Accessing the delegate
- setDelegate
- delegate
- setDefaultDelegate
- defaultDelegate
- Committing or discarding changes
- saveChangesInEditingContext
- invalidateAllObjects
- invalidateObjectsWithGlobalIDs
- rollbackChanges
- commitChanges
- prepareForSaveWithCoordinator
- recordUpdateForObject
- recordChangesInEditingContext
- refaultObject
- Determining if the EODatabaseContext is responsible for a particular operation
- ownsObject
- ownsGlobalID
- handlesFetchSpecification
- Recording snapshots
- recordSnapshotForGlobalID
- recordSnapshots
- recordSnapshotForSourceGlobalID
- recordToManySnapshots
- Forgetting snapshots
- forgetSnapshotForGlobalID
- forgetSnapshotsForGlobalIDs
- editingContextDidForgetObjectWithGlobalID
- Accessing snapshots
- localSnapshotForGlobalID
- localSnapshotForSourceGlobalID
- snapshotForGlobalID
- snapshotForSourceGlobalID
- Initializing objects
- initializeObject
- Obtaining an EODatabaseContext
- registeredDatabaseContextForModel
- Locking objects
- setUpdateStrategy
- updateStrategy
- registerLockedObjectWithGlobalID
- isObjectLockedWithGlobalID
- isObjectLockedWithGlobalID
- forgetAllLocks
- forgetLocksForObjectsWithGlobalIDs
- lockObjectWithGlobalID
- Returning information about objects
- valuesForKeys
- Setting the context class
- contextClassToRegister
- setContextClassToRegister
- Thread safety
- lock
- unlock
Constructors
EODatabaseContext
public EODatabaseContext(EODatabase aDatabase)
aDatabase is assigned to the new database as the EODatabase object with which the new context works. The new database context creates an EOAdaptorContext with which to communicate with the database server. Throws an exception if the underlying adaptor context can't create a corresponding adaptor channel.
See Also: database
Static Methods
contextClassToRegister
public static Class contextClassToRegister()
CooperatingObjectStoreNeeded
notification.
By default this is EODatabaseContext, but you can use setContextClassToRegister to specify
your own subclass of EODatabaseContext.When an EOObjectStoreCoordinator
sends an CooperatingObjectStoreNeeded
notification
for an EOEntity in the default model group, if contextClassToRegister is
non-null (and it should be-it makes no sense to set contextClassToRegister to null),
an instance of the that class is created, the EOModel for the EOEntity
is registered, and the context class is registered with the requesting EOObjectStoreCoordinator.
defaultDelegate
public static Object defaultDelegate()
forceConnectionWithModel
public static EODatabaseContext forceConnectionWithModel(
EOModel aModel,
NSDictionary overrides,
com.apple.yellow.eocontrol.EOEditingContext anEditingContext)
isSharedObjectLoadingEnabled
public static boolean isSharedObjectLoadingEnabled()
true
if
database contexts automatically load enterprise objects into the
default shared editing context when they load models; false
otherwise.
The objects loaded into the shared editing context are those identified
by entities' shared fetch specifications.See Also: sharedObjectFetchSpecificationNames ( EOEntity)
registeredDatabaseContextForModel
public static EODatabaseContext registeredDatabaseContextForModel(
EOModel aModel,
com.apple.yellow.eocontrol.EOEditingContext anEditingContext)
setContextClassToRegister
public static void setContextClassToRegister(Class contextClass)
setDefaultDelegate
public static void setDefaultDelegate(Object defaultDelegate)
setSharedObjectLoadingEnabled
public static void setSharedObjectLoadingEnabled(boolean flag)
true
(the database
automatically loads shared objects). The objects loaded into the
shared editing context are those identified by entities' shared
fetch specifications.See Also: sharedObjectFetchSpecificationNames ( EOEntity)
Instance Methods
adaptorContext
public EOAdaptorContext adaptorContext()
arrayFaultWithSourceGlobalID
public NSArray arrayFaultWithSourceGlobalID(
com.apple.yellow.eocontrol.EOGlobalID globalID,
String name,
com.apple.yellow.eocontrol.EOEditingContext anEditingContext)
See Also: faultForGlobalID
availableChannel
public EODatabaseChannel availableChannel()
See Also: registerChannel, registeredChannels, unregisterChannel
batchFetchRelationship
public void batchFetchRelationship(
EORelationship relationship,
NSArray objects,
com.apple.yellow.eocontrol.EOEditingContext anEditingContext)
commitChanges
public void commitChanges()
CooperatingObjectStoreNeeded
(defined
in EOControl's EOObjectStore) is posted describing the committed
changes. Raises an exception if the adaptor is unable to commit
the transaction; the error message indicates the nature of the problem.
You should never need to invoke this method directly.See Also: ownsGlobalID, rollbackChanges
coordinator
public com.apple.yellow.eocontrol.EOObjectStoreCoordinator coordinator()
database
public EODatabase database()
See Also: EODatabaseContext
delegate
public Object delegate()
See Also: setDelegate
editingContextDidForgetObjectWithGlobalID
public void editingContextDidForgetObjectWithGlobalID(
com.apple.yellow.eocontrol.EOEditingContext context,
com.apple.yellow.eocontrol.EOGlobalID gid)
See Also: decrementSnapshotCountForGlobalID (EODatabase), incrementSnapshotCountForGlobalID (EODatabase)
faultForGlobalID
public com.apple.yellow.eocontrol.EOEnterpriseObject faultForGlobalID(
com.apple.yellow.eocontrol.EOGlobalID globalID,
com.apple.yellow.eocontrol.EOEditingContext anEditingContext)
See Also: arrayFaultWithSourceGlobalID
faultForRawRow
public com.apple.yellow.eocontrol.EOEnterpriseObject faultForRawRow(
Object row,
String entityName,
com.apple.yellow.eocontrol.EOEditingContext editingContext)
forgetAllLocks
public void forgetAllLocks()
See Also: registerLockedObjectWithGlobalID, isObjectLockedWithGlobalID, isObjectLockedWithGlobalID, forgetLocksForObjectsWithGlobalIDs, lockObjectWithGlobalID, lockObject (EOEditingContext)
forgetLocksForObjectsWithGlobalIDs
public void forgetLocksForObjectsWithGlobalIDs(NSArray globalIDs)
See Also: registerLockedObjectWithGlobalID, isObjectLockedWithGlobalID, isObjectLockedWithGlobalID, forgetAllLocks, lockObjectWithGlobalID, lockObject (EOEditingContext)
forgetSnapshotForGlobalID
public void forgetSnapshotForGlobalID(com.apple.yellow.eocontrol.EOGlobalID globalID)
See Also: recordSnapshotForGlobalID, localSnapshotForGlobalID, recordSnapshots, snapshotForGlobalID:, forgetSnapshotsForGlobalIDs
forgetSnapshotsForGlobalIDs
public void forgetSnapshotsForGlobalIDs(NSArray globalIDs)
See Also: recordSnapshotForGlobalID, localSnapshotForGlobalID, recordSnapshots, snapshotForGlobalID:
handleDroppedConnection
public void handleDroppedConnection()
handlesFetchSpecification
public boolean handlesFetchSpecification(com.apple.yellow.eocontrol.EOFetchSpecification fetchSpec)
See Also: ownsObject, ownsGlobalID
hasBusyChannels
public boolean hasBusyChannels()
initializeObject
public void initializeObject(
com.apple.yellow.eocontrol.EOEnterpriseObject object, com.apple.yellow.eocontrol.EOGlobalID globalID, com.apple.yellow.eocontrol.EOEditingContext anEditingContext)
invalidateAllObjects
public void invalidateAllObjects()
InvalidatedAllObjectsInStoreNotification
,
as well as an ObjectsChangedInStoreNotification
with
the invalidated global IDs in the userInfo dictionary.
Both of these notifications are defined in EOObjectStore (EOControl).
This method works by invoking invalidateObjectsWithGlobalIDs for
all of the snapshots in the receiver's EODatabase.invalidateObjectsWithGlobalIDs
public void invalidateObjectsWithGlobalIDs(NSArray globalIDs)
ObjectsChangedInStoreNotification
(defined
in EOObjectStore), which causes the EOEditingContext containing
objects fetched from the receiver to refault those objects. The
result is that these objects will be refetched from the database
the next time they're accessed.isObjectLockedWithGlobalID
public boolean isObjectLockedWithGlobalID(com.apple.yellow.eocontrol.EOGlobalID globalID)
See Also: registerLockedObjectWithGlobalID, forgetAllLocks, isObjectLockedWithGlobalID, forgetLocksForObjectsWithGlobalIDs, lockObjectWithGlobalID, lockObject (EOEditingContext)
isObjectLockedWithGlobalID
public boolean isObjectLockedWithGlobalID(
com.apple.yellow.eocontrol.EOGlobalID globalID,
com.apple.yellow.eocontrol.EOEditingContext anEditingContext)
See Also: registerLockedObjectWithGlobalID, isObjectLockedWithGlobalID, forgetAllLocks, forgetLocksForObjectsWithGlobalIDs, lockObjectWithGlobalID, lockObject (EOEditingContext)
localSnapshotForGlobalID
public NSDictionary localSnapshotForGlobalID(com.apple.yellow.eocontrol.EOGlobalID globalID)
See Also: recordSnapshotForGlobalID, forgetSnapshotForGlobalID, recordSnapshots, snapshotForGlobalID:
localSnapshotForSourceGlobalID
public NSArray localSnapshotForSourceGlobalID(
com.apple.yellow.eocontrol.EOGlobalID globalID,
String name)
See Also: recordSnapshotForSourceGlobalID, snapshotForSourceGlobalID:relationshipName:
lock
public void lock()
See Also: unlock
lockObjectWithGlobalID
public void lockObjectWithGlobalID(
com.apple.yellow.eocontrol.EOGlobalID globalID,
com.apple.yellow.eocontrol.EOEditingContext anEditingContext)
See Also: registerLockedObjectWithGlobalID, isObjectLockedWithGlobalID, forgetAllLocks, forgetLocksForObjectsWithGlobalIDs, lockObject (EOEditingContext)
missingObjectGlobalIDs
public NSArray missingObjectGlobalIDs()
To be notified when a missing object is discovered, implement the delegate method databaseContextFailedToFetchObject.
If an application tries to save a missing object, an exception is raised.
objectsForSourceGlobalID
public NSArray objectsForSourceGlobalID(
com.apple.yellow.eocontrol.EOGlobalID globalID,
String name,
com.apple.yellow.eocontrol.EOEditingContext anEditingContext)
objectsWithFetchSpecification
public NSArray objectsWithFetchSpecification(
com.apple.yellow.eocontrol.EOFetchSpecification fetchSpecification,
com.apple.yellow.eocontrol.EOEditingContext anEditingContext)
You can fine-tune the fetching behavior by adding hints to fetchSpecification's hints dictionary. For this purpose, EODatabaseContext defines the following keys:
Constant | Corresponding value in the hints dictionary |
CustomQueryExpressionHintKey |
A String specifying raw SQL with which to perform the fetch. There is no way to pass down parameters with this hint. |
StoredProcedureNameHintKey |
A String specifying a name for a stored procedure in the model that should be used rather than building the SQL statement. The stored procedure must query the exact same attributes in the same order as EOF would query if generating the SELECT expression dynamically. If this key is supplied, other aspects of the EOFetchSpecification such as isDeep, qualifier, and sortOrderings are ignored (in that sense, this key is more of a directive than a hint). There is no way to pass down parameters with this hint. |
The class description contains additional information on using these hints. See "Using a Custom Query."
You can also use this method to implement "on-demand" locking by using a fetchSpecification that includes locking. For more discussion of this subject, see "Updating And Locking Strategies" in the class description.
Raises an exception if an error occurs; the error message indicates the nature of the problem.
See Also: objectsWithFetchSpecification (EOEditingContext)
ownsGlobalID
public boolean ownsGlobalID(com.apple.yellow.eocontrol.EOGlobalID globalID)
See Also: handlesFetchSpecification, ownsObject
ownsObject
public boolean ownsObject(com.apple.yellow.eocontrol.EOEnterpriseObject object)
See Also: ownsGlobalID, handlesFetchSpecification
performChanges
public void performChanges()
This method raises an exception if the adaptor is unable to perform the operations. The exception's userInfo dictionary contains these keys:
Key (String Constant) | Value |
DatabaseContextKey |
The EODatabaseContext object that was trying to save to its underlying repository when the exception was raised. |
DatabaseOperationsKey |
The list of database operations the EODatabaseContext was trying to perform when the failure occurred. |
FailedDatabaseOperationKey |
The database operation the EODatabaseContext failed to perform. |
The userInfo dictionary may also contain some of the keys listed in the method description for the EOAdaptorChannel method performAdaptorOperation:. For more information, see the EOAdaptorChannel class specification.
See Also: commitChanges, rollbackChanges
prepareForSaveWithCoordinator
public void prepareForSaveWithCoordinator(
com.apple.yellow.eocontrol.EOObjectStoreCoordinator coordinator,
com.apple.yellow.eocontrol.EOEditingContext anEditingContext)
recordChangesInEditingContext
public void recordChangesInEditingContext()
recordSnapshotForGlobalID
public void recordSnapshotForGlobalID(
NSDictionary aSnapshot,
com.apple.yellow.eocontrol.EOGlobalID aGlobalID)
See Also: forgetSnapshotForGlobalID, localSnapshotForGlobalID, recordSnapshots, snapshotForGlobalID:
recordSnapshotForSourceGlobalID
public void recordSnapshotForSourceGlobalID(
NSArray globalIDs,
com.apple.yellow.eocontrol.EOGlobalID globalID,
String name)
See Also: snapshotForSourceGlobalID:relationshipName:, localSnapshotForSourceGlobalID, recordToManySnapshots
recordSnapshots
public void recordSnapshots(NSDictionary snapshots)
See Also: recordSnapshotForGlobalID, localSnapshotForGlobalID, forgetSnapshotForGlobalID, snapshotForGlobalID:
recordToManySnapshots
public void recordToManySnapshots(NSDictionary snapshots)
This method only records snapshots locally (in the transaction scope). If you want to record snapshots globally, use the corresponding EODatabase method.
See Also: recordSnapshotForSourceGlobalID, snapshotForSourceGlobalID:relationshipName:, localSnapshotForSourceGlobalID
recordUpdateForObject
public void recordUpdateForObject(
com.apple.yellow.eocontrol.EOEnterpriseObject object,
NSDictionary changes)
refaultObject
public void refaultObject(
com.apple.yellow.eocontrol.EOEnterpriseObject object,
com.apple.yellow.eocontrol.EOGlobalID globalID,
com.apple.yellow.eocontrol.EOEditingContext anEditingContext)
This method should be used with caution since refaulting an object doesn't remove the object snapshot from the undo stack, after which the object snapshot may not refer to the proper object.
registerChannel
public void registerChannel(EODatabaseChannel channel)
See Also: availableChannel, registeredChannels, unregisterChannel
registeredChannels
public NSArray registeredChannels()
See Also: registerChannel, availableChannel, unregisterChannel
registerLockedObjectWithGlobalID
public void registerLockedObjectWithGlobalID(com.apple.yellow.eocontrol.EOGlobalID globalID)
See Also: forgetAllLocks, isObjectLockedWithGlobalID, forgetLocksForObjectsWithGlobalIDs, lockObjectWithGlobalID, lockObject (EOEditingContext)
rollbackChanges
public void rollbackChanges()
See Also: ownsGlobalID, commitChanges
saveChangesInEditingContext
public void saveChangesInEditingContext(com.apple.yellow.eocontrol.EOEditingContext context)
setDelegate
public void setDelegate(Object delegate)
See Also: delegate
setUpdateStrategy
public void setUpdateStrategy(int strategy)
UpdateWithOptimisticLocking
UpdateWithPessimisticLocking
UpdateWithNoLocking
Throws an exception if
the receiver has any transactions in progress or if you try to set strategy to UpdateWithPessimisticLocking
and
the receiver's EODatabase already has snapshots.
See Also: updateStrategy
snapshotForGlobalID
public NSDictionary snapshotForGlobalID(
com.apple.yellow.eocontrol.EOGlobalID globalID,
double timestamp)
public NSDictionary snapshotForGlobalID(com.apple.yellow.eocontrol.EOGlobalID globalID)
null
if there
isn't a snapshot for the globalID or if the corresponding timestamp
is less than timestamp. Searches
first locally (in the transaction scope) and then in the EODatabase. If timestamp is
not provided, DistantPastTimeInterval is used.snapshotForSourceGlobalID
public NSArray snapshotForSourceGlobalID(
com.apple.yellow.eocontrol.EOGlobalID globalId,
String name,
double timestamp)
public NSArray snapshotForSourceGlobalID(
com.apple.yellow.eocontrol.EOGlobalID globalId,
String name)
null
if
there isn't a to-many snapshot for globalId or
if the timestamp is less than timestamp.
Searches first locally (in the transaction scope) and then in the
EODatabase. If timestamp isn't
provided, DistantPastTimeInterval is used.unlock
public void unlock()
See Also: lock
unregisterChannel
public void unregisterChannel(EODatabaseChannel channel)
See Also: registerChannel, registeredChannels, availableChannel
updateStrategy
public int updateStrategy()
UpdateWithOptimisticLocking
UpdateWithPessimisticLocking
UpdateWithNoLocking
The
default strategy is UpdateWithOptimisticLocking
.
See Also: setUpdateStrategy
valuesForKeys
public NSDictionary valuesForKeys(
NSArray keys,
com.apple.yellow.eocontrol.EOEnterpriseObject object)
Notifications
DatabaseChannelNeededNotification
This notification is broadcast whenever an EODatabaseContext is asked to perform an object store operation and it doesn't have an available EODatabaseChannel. Subscribers can create a new channel and add it to the EODatabaseContext at this time.Notification Object | The EODatabaseContext. |
userInfo Dictionary | None. |