EODatabaseContext

Inherits from: EOCooperatingObjectStore
Implements:
NSDisposable
NSLocking
NSDisposable
NSLocking

Package: com.webobjects.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:

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

DatabaseChannelNeededNotification String Description forthcoming.

In addition, EODatabaseContext defines a constant for the name of the notification it posts. For more information on the notification, see "Notifications" (page 163).

Method Types

ConstructorsEODatabaseContextFetching objectsobjectsWithFetchSpecification objectsForSourceGlobalID arrayFaultWithSourceGlobalID faultForGlobalID faultForRawRow batchFetchRelationship missingObjectGlobalIDsEnabling shared object loadingsetSharedObjectLoadingEnabled isSharedObjectLoadingEnabledAccessing the adaptor contextadaptorContextManaging the database connectionforceConnectionWithModel handleDroppedConnectionAccessing the database objectdatabaseAccessing the coordinatorcoordinatorManaging channelsavailableChannel registerChannel registeredChannels unregisterChannel hasBusyChannelsAccessing the delegatesetDelegate delegate setDefaultDelegate defaultDelegateCommitting or discarding changessaveChangesInEditingContext invalidateAllObjects invalidateObjectsWithGlobalIDs rollbackChanges commitChanges prepareForSaveWithCoordinator recordUpdateForObject recordChangesInEditingContext refaultObjectDetermining if the EODatabaseContext is responsible for a particular operationownsObject ownsGlobalID handlesFetchSpecificationRecording snapshotsrecordSnapshotForGlobalID recordSnapshots recordSnapshotForSourceGlobalID recordToManySnapshotsForgetting snapshotsforgetSnapshotForGlobalID forgetSnapshotsForGlobalIDs editingContextDidForgetObjectWithGlobalIDAccessing snapshotslocalSnapshotForGlobalID localSnapshotForSourceGlobalID snapshotForGlobalID snapshotForSourceGlobalIDInitializing objectsinitializeObjectObtaining an EODatabaseContextregisteredDatabaseContextForModelLocking objectssetUpdateStrategy updateStrategy registerLockedObjectWithGlobalID isObjectLockedWithGlobalID isObjectLockedWithGlobalID forgetAllLocks forgetLocksForObjectsWithGlobalIDs lockObjectWithGlobalIDReturning information about objectsvaluesForKeysSetting the context classcontextClassToRegister setContextClassToRegisterThread safetylock unlock

Constructors

EODatabaseContext

public EODatabaseContext(EODatabase aDatabase)

Creates and returns a new EODatabaseContext. Typically, you don't need to programmatically create database contexts. Rather, they are created automatically by the control layer. See "Creating and Using an EODatabaseContext" for more information.

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()

Returns the class that is registered with an EOObjectStoreCoordinator when the coordinator broadcasts an 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()

Returns the default delegate-the object assigned as delegate to new EODatabaseContext instances.

forceConnectionWithModel

public static EODatabaseContext forceConnectionWithModel( EOModel aModel, NSDictionary overrides, com.webobjects.eocontrol.EOEditingContext anEditingContext)

Forces the stack of objects in the EOAccess layer to be instantiated, if necessary, and then makes a connection to the database. If there is an existing connection for amodel, it is first closed and then reconnected. The new connection dictionary is effectively made up of the model's connection dictionary, overlaid with overrides. All compatible models in the model's group also are associated with the new connection (so they share the same adaptor). Returns the EODatabaseContext associated with the model for anEditingContext.

isSharedObjectLoadingEnabled

public static boolean isSharedObjectLoadingEnabled()

Returns 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.webobjects.eocontrol.EOEditingContext anEditingContext)

Finds the EOObjectStoreCoordinator (EOControl) for anEditingContext and checks to see if it already contains an EODatabaseContext cooperating store for aModel. If it does, it returns that EODatabaseContext. Otherwise it instantiates a new EODatabaseContext, adds it to the EOObjectStoreCoordinator, and returns the EODatabaseContext.

public static EODatabaseContext registeredDatabaseContextForModel( EOModel aModel, com.webobjects.eocontrol.EOObjectStoreCoordinator objectStoreCoord)

Description forthcoming.

setContextClassToRegister

public static void setContextClassToRegister(Class contextClass)

Sets to contextClass the "contextClassToRegister." For more discussion of this topic, see the method description for contextClassToRegister.

setDefaultDelegate

public static void setDefaultDelegate(Object defaultDelegate)

Sets the default delegate to defaultDelegate-the object assigned as delegate to new instances of EODatabaseContext.

setSharedObjectLoadingEnabled

public static void setSharedObjectLoadingEnabled(boolean flag)

Sets according to flag whether database contexts automatically load enterprise objects into the default shared editing context when they load models. The default is 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()

Returns the EOAdaptorContext used by the EODatabaseContext for communication with the database server.

arrayFaultWithSourceGlobalID

public NSArray arrayFaultWithSourceGlobalID( com.webobjects.eocontrol.EOGlobalID globalID, String name, com.webobjects.eocontrol.EOEditingContext anEditingContext)

Overrides the inherited implementation to create a to-many fault for anEditingContext. name must correspond to an EORelationship in the EOEntity for the specified globalID.

See Also: faultForGlobalID

availableChannel

public EODatabaseChannel availableChannel()

Returns an EODatabaseChannel that's registered with the receiver and that isn't busy. If the method can't find a channel that meets these criteria, it posts an DatabaseChannelNeededNotification in the hopes that someone will provide a new channel. After posting the notification, the receiver checks its list of channels again. If there are still no available channels, the receiver creates an EODatabaseChannel itself. However, if the list is not empty and there are no available channels, the method returns null.

batchFetchRelationship

public void batchFetchRelationship( EORelationship relationship, NSArray objects, com.webobjects.eocontrol.EOEditingContext anEditingContext)

Clear all the faults for the relationship of anEditingContext's objects and performs a single, efficient, fetch (at most two fetches, if the relationship is many-to-many). This method provides a way to fetch the same relationship for multiple objects. For example, given an array of Employee objects, this method can fetch all of their departments with one round trip to the server, rather than asking the server for each of the employee's departments individually.

commitChanges

public void commitChanges()

Overrides the inherited implementation to instruct the adaptor to commit the transaction. If the commit is successful, any primary and foreign key changes are written back to the saved objects, database locks are released, and an 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.webobjects.eocontrol.EOObjectStoreCoordinator coordinator()

Returns the receiver's EOObjectStoreCoordinator (EOControl) or null if there is none. This method is only valid during a save operation.

database

public EODatabase database()

Returns the receiver's EODatabase.

See Also: EODatabaseContext

delegate

public Object delegate()

Returns the receiver's delegate.

See Also: setDelegate

dispose

public void dispose()

Conformance to NSDisposable.

editingContextDidForgetObjectWithGlobalID

public void editingContextDidForgetObjectWithGlobalID( com.webobjects.eocontrol.EOEditingContext context, com.webobjects.eocontrol.EOGlobalID gid)

Overrides the inherited implementation. Invoked when context is no longer using the object corresponding to gid. EODatabaseContext's implementation destroys related data (such as snapshots) if no other objects are using it. Don't invoke this method; it is invoked automatically by the Framework.

See Also: decrementSnapshotCountForGlobalID (EODatabase), incrementSnapshotCountForGlobalID (EODatabase)

faultForGlobalID

public com.webobjects.eocontrol.EOEnterpriseObject faultForGlobalID( com.webobjects.eocontrol.EOGlobalID globalID, com.webobjects.eocontrol.EOEditingContext anEditingContext)

Overrides the inherited implementation to create a to-one fault for the object identified by globalID and register it in anEditingContext.

See Also: arrayFaultWithSourceGlobalID

faultForRawRow

public com.webobjects.eocontrol.EOEnterpriseObject faultForRawRow( NSDictionary row, String entityName, com.webobjects.eocontrol.EOEditingContext editingContext)

Returns a fault for a raw row. row is the raw data, in the form of an NSDictionary. entityName is the name of the appropriate entity for the EO you want to create (as a fault). editingContext is the EOEditingContext in which to create the fault.

forgetAllLocks

public void forgetAllLocks()

Clears all of the receiver's locks. Doesn't cause the locks to be forgotten in the server, only in the receiver. This method is useful when something has happened to cause the server to forget the locks and the receiver needs to be synced up. This method is invoked whenever a transaction is committed or rolled back.

forgetLocksForObjectsWithGlobalIDs

public void forgetLocksForObjectsWithGlobalIDs(NSArray globalIDs)

Clears the locks made for the enterprise objects identified by each of the EOGlobalIDs in globalIDs. Doesn't cause the locks to be forgotten in the server, only in the receiver.

See Also: registerLockedObjectWithGlobalID, isObjectLockedWithGlobalID, isObjectLockedWithGlobalID, forgetAllLocks, lockObjectWithGlobalID, lockObject (EOEditingContext)

forgetSnapshotForGlobalID

public void forgetSnapshotForGlobalID(com.webobjects.eocontrol.EOGlobalID globalID)

Deletes the snapshot made for the enterprise object identified by globalID.

forgetSnapshotsForGlobalIDs

public void forgetSnapshotsForGlobalIDs(NSArray globalIDs)

Deletes the snapshots made for the enterprise objects identified by globalIDs, an array of EOGlobalID objects.

handleDroppedConnection

public void handleDroppedConnection()

Cleans up after a database connection is dropped by releasing the receiver's adaptor context and database channels, and then creating a new adaptor context. Don't invoke this method; it's invoked automatically by the Framework.

handlesFetchSpecification

public boolean handlesFetchSpecification(com.webobjects.eocontrol.EOFetchSpecification fetchSpec)

Overrides the inherited implementation to return true if the receiver is responsible for fetching the objects described by the entity name in fetchSpec.

See Also: ownsObject, ownsGlobalID

hasBusyChannels

public boolean hasBusyChannels()

Returns true if the receiver's EOAdaptorContext has channels that have outstanding operations (that is, have a fetch in progress), false otherwise.

initializeObject

public void initializeObject( com.webobjects.eocontrol.EOEnterpriseObject object, com.webobjects.eocontrol.EOGlobalID globalID, com.webobjects.eocontrol.EOEditingContext anEditingContext)

Overrides the inherited implementation initialize object for anEditingContext by filling it with properties based on row data fetched from the adaptor. The snapshot for globalID is looked up and those attributes in the snapshot that are marked as class properties in the EOEntity are assigned to object. For relationship class properties, faults are constructed and assigned to the object.

invalidateAllObjects

public void invalidateAllObjects()

Overrides the inherited implementation to discard all snapshots in the receiver's EODatabase, forget all locks, and post an 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)

Overrides the inherited implementation to discard the snapshots for the objects identified by the EOGlobalIDs in globalIDs and broadcasts an 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.webobjects.eocontrol.EOGlobalID globalID)

Returns true if the enterprise object identified by globalID is locked, false otherwise.

See Also: registerLockedObjectWithGlobalID, forgetAllLocks, isObjectLockedWithGlobalID, forgetLocksForObjectsWithGlobalIDs, lockObjectWithGlobalID, lockObject (EOEditingContext)

isObjectLockedWithGlobalID

public boolean isObjectLockedWithGlobalID( com.webobjects.eocontrol.EOGlobalID globalID, com.webobjects.eocontrol.EOEditingContext anEditingContext)

Overrides the EOObjectStore method isObjectLockedWithGlobalID:editingContext: to return true if the database row corresponding to globalID has been locked in an open transaction held by the receiver.

See Also: registerLockedObjectWithGlobalID, isObjectLockedWithGlobalID, forgetAllLocks, forgetLocksForObjectsWithGlobalIDs, lockObjectWithGlobalID, lockObject (EOEditingContext)

localSnapshotForGlobalID

public NSDictionary localSnapshotForGlobalID(com.webobjects.eocontrol.EOGlobalID globalID)

Returns the snapshot for the object identified by globalID, if there is one; else returns null. Only searches locally (in the transaction scope), not in the EODatabase.

localSnapshotForSourceGlobalID

public NSArray localSnapshotForSourceGlobalID( com.webobjects.eocontrol.EOGlobalID globalID, String name)

Returns an array that is the snapshot for the objects at the destination of the to-many relationship named name, which is a property of the object identified by globalID. The returned array contains the globalIDs of the destination objects. If there is no snapshot, returns null. Only searches locally (in the transaction scope), not in the EODatabase.

lock

public void lock()

Used internally to protect access to the receiver in a multi-threaded environment. Do not confuse this with any methods which work with the database locking mechanism.

See Also: unlock

lockObjectWithGlobalID

public void lockObjectWithGlobalID( com.webobjects.eocontrol.EOGlobalID globalID, com.webobjects.eocontrol.EOEditingContext anEditingContext)

Overrides the inherited implementation to attempt to lock the database row corresponding to globalID in the underlying database server, on behalf of anEditingContext. If a transaction is not already open at the time of the lock request, the transaction is begun and is held open until either commitChanges or invalidateAllObjects is invoked. At that point all locks are released. Throws an exception if unable to obtain the lock.

See Also: registerLockedObjectWithGlobalID, isObjectLockedWithGlobalID, forgetAllLocks, forgetLocksForObjectsWithGlobalIDs, lockObject (EOEditingContext)

missingObjectGlobalIDs

public NSArray missingObjectGlobalIDs()

Returns the globalIDs of any "missing" enterprise objects, or an empty array if no missing objects are known to the receiver. An object is "missing" when a fault fires and the corresponding row for the fault isn't found in the database.

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.webobjects.eocontrol.EOGlobalID globalID, String name, com.webobjects.eocontrol.EOEditingContext anEditingContext)

Overrides the inherited implementation to service a to-many fault. The snapshot for the source object identified by globalID is located and the EORelationship named name is used to construct a qualifier from that snapshot. This qualifier is then used to fetch the requested objects into anEditingContext using the method objectsWithFetchSpecification.

objectsWithFetchSpecification

public NSArray objectsWithFetchSpecification( com.webobjects.eocontrol.EOFetchSpecification fetchSpecification, com.webobjects.eocontrol.EOEditingContext anEditingContext)

Overrides the inherited implementation to fetch objects from an external store into anEditingContext. The receiver obtains an available EODatabaseChannel and issues a fetch with fetchSpecification. If one of these objects is already present in memory, by default this method doesn't overwrite its values with the new values from the database (you can change this behavior; see the setRefreshesRefetchedObjects method in the EOFetchSpecification class specification).

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.webobjects.eocontrol.EOGlobalID globalID)

Overrides the inherited implementation to return true if the receiver is responsible for fetching and saving the object identified by globalID, false otherwise. The receiver is determined to be responsible if globalID is a subclass of EOKeyGlobalID and globalID has an entity from one of the receiver's EODatabase's EOModels.

See Also: handlesFetchSpecification, ownsObject

ownsObject

public boolean ownsObject(com.webobjects.eocontrol.EOEnterpriseObject object)

Overrides the inherited implementation to return true if the receiver is responsible for fetching and saving object, false otherwise. The receiver is determined to be responsible if the entity corresponding to object is in one of the receiver's EODatabase's EOModels.

See Also: ownsGlobalID, handlesFetchSpecification

performChanges

public void performChanges()

Overrides the inherited implementation to construct EOAdaptorOperations from the EODatabaseOperations produced during recordChangesInEditingContext and recordUpdateForObject. Invokes the delegate method databaseContextWillOrderAdaptorOperations to give the delegate an opportunity to construct alternative EOAdaptorOperations from the EODatabaseOperations. Then invokes the delegate method databaseContextWillPerformAdaptorOperations to let the delegate substitute its own array of EOAdaptorOperations. Gives the EOAdaptorOperations to an available EOAdaptorChannel for execution. If the save succeeds, updates the snapshots in the receiver to reflect the new state of the server. You should never need to invoke this method directly.

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.webobjects.eocontrol.EOObjectStoreCoordinator coordinator, com.webobjects.eocontrol.EOEditingContext anEditingContext)

Overrides the inherited implementation to do whatever is necessary to prepare to save changes. If needed, generates primary keys for any new objects in anEditingContext that are owned by the receiver. This method is invoked before the object graph is analyzed and foreign key assignments are performed. You should never need to invoke this method directly.

recordChangesInEditingContext

public void recordChangesInEditingContext()

Overrides the inherited implementation to construct a list of EODatabaseOperations for all changes to objects in the EOEditingContext that are owned by the receiver. Forwards any relationship changes discovered but not owned by the receiver to the EOObjectStoreCoordinator. This method is typically invoked in the course of an EOObjectStoreCoordinator saving changes through its saveChangesInEditingContext method. It's invoked after prepareForSaveWithCoordinator and before ownsGlobalID. You should never need to invoke this method directly.

recordSnapshotForGlobalID

public void recordSnapshotForGlobalID( NSDictionary aSnapshot, com.webobjects.eocontrol.EOGlobalID aGlobalID)

Records aSnapshot under globalID. This method only records snapshots locally (in the transaction scope). If you want to record snapshots globally, use the corresponding EODatabase method.

recordSnapshotForSourceGlobalID

public void recordSnapshotForSourceGlobalID( NSArray globalIDs, com.webobjects.eocontrol.EOGlobalID globalID, String name)

For the object identified by globalID, records an NSArray of globalIDs for the to-many relationship named name. These globalIDs identify the objects at the destination of the relationship. This method only records snapshots locally (in the transaction scope). If you want to record snapshots globally, use the corresponding EODatabase method.

recordSnapshots

public void recordSnapshots(NSDictionary snapshots)

Records the objects in snapshots, a dictionary of snapshots. The snapshots argument's keys are GlobalIDs and its values are the corresponding snapshots represented as NSDictionaries. This method only records snapshots locally (in the transaction scope). If you want to record snapshots globally, use the corresponding EODatabase method.

recordToManySnapshots

public void recordToManySnapshots(NSDictionary snapshots)

Records the objects in snapshots. snapshots should be an NSDictionary of NSDictionaries, in which the top-level dictionary has as its key the globaID of the enterprise object for which to-many relationships are being recorded. The key's value is a dictionary whose keys are the names of the Enterprise Object's to-many relationships. Each of these keys in turn has as its value an array of globalIDs that identify the objects at the destination of the relationship.

This method only records snapshots locally (in the transaction scope). If you want to record snapshots globally, use the corresponding EODatabase method.

recordUpdateForObject

public void recordUpdateForObject( com.webobjects.eocontrol.EOEnterpriseObject object, NSDictionary changes)

Overrides the inherited implementation to communicate to the receiver that changes from another EOCooperatingObjectStore (through the EOObjectStoreCoordinator) need to be made to an object in the receiver. For example, an insert of an object in a relationship property might require changing a foreign key property in an object owned by another cooperating store. This method can be invoked any time after prepareForSaveWithCoordinator and before ownsGlobalID.

refaultObject

public void refaultObject( com.webobjects.eocontrol.EOEnterpriseObject object, com.webobjects.eocontrol.EOGlobalID globalID, com.webobjects.eocontrol.EOEditingContext anEditingContext)

Overrides the inherited implementation to refault the enterprise object identified by globalID in anEditingContext. Newly-inserted objects should not be refaulted, since they can't be refetched from the external store. If you attempt to do this, an exception will be raised. Don't refault to-many relationship arrays, just recreate them.

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)

Registers channel, which means that it adds it to the pool of available channels used to service fetch and fault requests. You use this method if you need to perform more than one fetch simultaneously.

registeredChannels

public NSArray registeredChannels()

Returns all of the EODatabaseChannels that have been registered for use with the receiver.

registerLockedObjectWithGlobalID

public void registerLockedObjectWithGlobalID(com.webobjects.eocontrol.EOGlobalID globalID)

Registers as a locked object the enterprise object identified by globalID. This method is used internally to keep track of objects corresponding to rows that are locked in the database.

See Also: forgetAllLocks, isObjectLockedWithGlobalID, forgetLocksForObjectsWithGlobalIDs, lockObjectWithGlobalID, lockObject (EOEditingContext)

rollbackChanges

public void rollbackChanges()

Overrides the inherited implementation to instruct the adaptor to roll back the transaction. Rolls back any changed snapshots, and releases all locks.

See Also: ownsGlobalID, commitChanges

saveChangesInEditingContext

public void saveChangesInEditingContext(com.webobjects.eocontrol.EOEditingContext context)

Overrides the inherited implementation to save the changes made in context. This message is sent by an EOEditingContext to its EOObjectStore to commit changes. Normally an editing context doesn't send this message to an EODatabaseContext, but to an EOObjectStoreCoordinator. Raises an exception if an error occurs; the error message indicates the nature of the problem.

setDelegate

public void setDelegate(Object delegate)

Sets the receiver's delegate to delegate, and propagates the delegate to all of the receiver's EODatabaseChannels. EODatabaseChannels share the delegate of their EODatabaseContext.

See Also: delegate

setUpdateStrategy

public void setUpdateStrategy(int strategy)

Sets the update strategy used by the EODatabaseContext to strategy. See "Updating And Locking Strategies" (page 172) for information on the update strategies:

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.webobjects.eocontrol.EOGlobalID globalID, long timestamp)

public NSDictionary snapshotForGlobalID(com.webobjects.eocontrol.EOGlobalID globalID)

Returns the snapshot associated with globalID. Returns 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.

snapshotForSourceGlobalID

public NSArray snapshotForSourceGlobalID( com.webobjects.eocontrol.EOGlobalID globalId, String name, long timestamp)

public NSArray snapshotForSourceGlobalID( com.webobjects.eocontrol.EOGlobalID globalId, String name)

Returns the to-many snapshot for globalId and name. A to-many snapshot is an array of globalIDs. These globalIDs identify the objects at the destination of the to-many relationship named name, which is a property of the object identified by globalID. Returns 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.

unlock

public void unlock()

Used internally to release the lock that protects access to the receiver in a multi-threaded environment.

See Also: lock

unregisterChannel

public void unregisterChannel(EODatabaseChannel channel)

Unregisters the EODatabaseChannel channel, which means that it removes it from the pool of available channels used for database communication (for example, to service fetch and fault requests).

updateStrategy

public int updateStrategy()

Returns the update strategy used by the receiver, one of:

UpdateWithOptimisticLocking
UpdateWithPessimisticLocking
UpdateWithNoLocking

The default strategy is UpdateWithOptimisticLocking.

See Also: setUpdateStrategy

valuesForKeys

public NSDictionary valuesForKeys( NSArray keys, com.webobjects.eocontrol.EOEnterpriseObject object)

Overrides the inherited implementation to return values for the specified keys from the snapshot of object. The returned values are used primarily by another EODatabaseContext to extract foreign key properties for objects owned by the receiver.

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.

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
`DatabaseChannelNeededNotification`	`String`	Description forthcoming.

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.

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.

Notification Object	The EODatabaseContext.
userInfo Dictionary	None.