com.webobjects.eoaccess
Class EODatabaseContext

java.lang.Object
  |
  +--com.webobjects.eocontrol.EOObjectStore
        |
        +--com.webobjects.eocontrol.EOCooperatingObjectStore
              |
              +--com.webobjects.eoaccess.EODatabaseContext

All Implemented Interfaces:

NSDisposable, NSLocking

public class EODatabaseContext

extends EOCooperatingObjectStore

implements NSLocking

EODatabaseContext is the basic EOObjectStore for the EOAccess Framework. It acts as one of possibly several EOCooperatingObjectStores for an EOObjectStoreCoordinator. It acts as a store for any entities in the model list of its EODatabase. When saving editing context changes, the EODatabaseContext searches the object graph using the editing context's list of inserted, deleted, and updated objects and determines exactly which changes need to be made in the database. It then creates an array of adaptorOperations which it hands to an adaptor channel for execution.

The EODatabaseContext knows how to interact with other EOCooperatingObjectStores to save changes made to an object graph in more than one database server.

When the EODatabaseContext is asked to fetch or write information to the database, it tries to use one of its EODatabaseChannels. If all of its channels are busy, it broadcasts a DatabaseChannelNeededNotification in the hopes that some observer can provide a new channel for the context or that an existing channel can be freed up.

An EODatabaseContext represents a single transaction scope on the database server, and determines the updating and locking stragegy used by the database layer. It is managed by an EODatabase object, which represents the main connection to the server. If the server supports multiple concurrent transaction sessions, the EODatabase may have several EODatabaseContexts. If the adaptor allows multiple channels per context, then an EODatabaseContext may in turn have several EODatabaseChannels, which handle actual access to the data on the server. Not all adaptors support multiple contexts per database object. See EODatabase and EODatabaseChannel documentation for more information.

EODatabaseContext's Interaction with Other Classes

As a subclass of EOCooperatingObjectStore, EODatabaseContext acts as one of possibly several EOCooperatingObjectStores for an EOObjectStoreCoordinator, which mediates between EOEditingContexts and EOCooperatingObjectStores. (EOObjectStore, EOCooperatingObjectStore, and EOObjectStoreCoordinator are provided by the control layer.)

An EODatabaseContext creates an EOAdaptorContext when initialized, and uses this object to communicate with the database server.

Creating and Using an EODatabaseContext

Though you can create an EODatabaseContext explicitly by using the static method registeredDatabaseContextForModel, you should rarely need to do so. If you are using the "higher-level" objects EOEditingContexts (EOControl) and EODatabaseDataSources, the database contexts those objects need are created automatically, on demand. When you create database data source (typically for use with the interface layer's EODisplayGroup or WebObject's WODisplayGroup), it registers a database context that is capable of fetching objects for the data source's entities. If objects fetched into an editing context (described more in the following section) have references to objects from EOModels that are based on another database, an EODatabaseContext is created and registered for each of the additional databases.

EODatabaseContexts are created on demand when an EOObjectStoreCoordinator (EOControl) posts a CooperatingObjectStoreNeeded notification. The EODatabaseContext class registers for the notification, and it provides the coordinator with a new EODatabaseContext instance that can handle the request.

For the most part, you don't need to programmatically interact with an EODatabaseContext. Some cases in which this might be necessary are:

• To implement your own locking strategy, either application-wide, or on a per-fetch basis. This is described in the section "Updating And Locking Strategies" below.
• To enable performance tuning, which is described in the section "Faulting" below.
• To intervene when objects are created and fetched in order to provide custom behavior. This is described in the section "Delegate Methods", and in the individual delegate method descriptions in the section "Instance Methods".

Fetching and Saving Objects

Conceptually, an EODatabaseContext fetches and saves objects on behalf of an EOEditingContext (EOControl). However, the two objects don't interact with each other directly. An EOObjectStoreCoordinator (EOControl) acts as a mediator between them. When an editing context fetches objects, the request is passed through the coordinator, which forwards it to the appropriate database context based on the fetch specification or global ID. EODatabaseContext knows how to interact with other EOCooperatingObjectStores to save changes made to an object graph in more than one database server.

When the database context receives a request to fetch or write information to the database, it tries to use one of its EODatabaseChannels. If all of its channels are busy, it broadcasts an DatabaseChannelNeededNotification in the hopes that an observer can provide a new channel or that an existing channel can be freed up. This observer could be a manager object that decides how many database cursors can be opened by a particular client.

Using a Custom Query

EODatabaseContext defines a hint for use with an EOFetchSpecification (EOControl) in the method objectsWithFetchSpecification. Named by the key CustomQueryExpressionHintKey, the hint's value is an SQL string for performing the fetch. The expression must query the same attributes in the same order that Enterprise Objects Framework would if it were generating the SELECT expression dynamically. If this key is supplied, other characteristics of the EOFetchSpecification such as isDeep, qualifier, and sortOrderings are ignored. In that sense, this key is more of a directive than a hint.

Faulting

When an EODatabaseContext fetches an object, it examines the relationships defined in the model and creates objects representing the destinations of the fetched object's relationships. For example, if you fetch an employee object, you can ask for its manager and immediately receive the object. You don't have to obtain the manager's employee ID from the employee object and then use it fetch the manager.

However, EODatabaseContext doesn't immediately fetch data for the destination objects of relationships since fetching is fairly expensive. To avoid this waste of time and resources, the destination objects aren't initially filled with fetched data. Instead, they exist without any of their values until those values are actually needed. When the "empty" destination object (called a fault) is accessed for the first time, it "fires the fault", that is, it triggers its EODatabaseContext to fetch its data.

There are two types of faults: single object faults for to-one relationships and array faults for to-many relationships. When an array fault is accessed, it fetches all of the destination objects and replaces itself with an array of those objects. You can fine-tune faulting behavior for additional performance gains by using two different mechanisms: batch faulting, and prefetching relationships.

Batch Faulting

Triggering one fault has no effect on other faults. The destination object or objects for that one fault are fetched from the database, incurring the overhead of a roundtrip to the database server. You can take advantage of this expensive round trip to the database server by batching faults together ith the method batchFetchRelationship. For example, given an array of Employee objects, this method can fetch all of their departments with a single round trip to the server, rather than asking the server for each of the employees' departments individually. The delegate methods databaseContextShouldFetchArrayFault and databaseContextShouldFetchObjectFault can be used to to fine-tune batch faulting behavior.

Batch faulting can also be set in an EOModel. In that approach, you specify the number of faults that should be triggered along with the first fault. In this case, you don't actually control which faults are batch fetched the ay you would by using batchFetchRelationship.

Delegate Methods

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), the fetch specification that is used to fetch objects (databaseContextShouldSelectObjects), how batch faulting is performed (databaseContextShouldFetchArrayFault and databaseContextShouldFetchObjectFault), and so on.

Snapshots

An EODatabase records snapshots for its EODatabaseContexts. These snapshots form the application's view of the current state of the database server. This global view is overridden locally by database contexts, which form their own snapshots as they make changes during a transaction. When a database context commits its top-level transaction, it reconciles all changed snapshots with the global view of the database object, so that other database contexts (except those with open transactions) immediately use the new snapshots as well.

Updating And Locking Strategies

EODatabaseContext supports three updating strategies defined in the EODatabaseContext class as integer values:

Constant	Description
UpdateWithOptimisticLocking	The default update strategy. Under optimistic locking, objects aren't locked immediately on being fetched from the server. Instead, whenever you attempt to save updates to an object in the database, the object's snapshot is used to ensure that the values in the corresponding database row haven't changed since the object was fetched. As long as the snapshot matches the values in the database, the update is allowed to proceed.
UpdateWithPessimisticLocking	Causes objects to be locked in the database when they are selected, ensuring that no one else can modify the objects until the transaction ends. However, this doesn't necessarily mean that either the select or the update operation will succeed. Other settings at the adaptor or physical database level can cause an update to fail. When pessimistic locking is enabled, a transaction is automatically started upon the first access to the database. By default, all selects against the database are performed with "select FOR UPDATE". The transaction is ended either when saveChangesInEditingContext is invoked and the transaction is committed or when revertAllObjects is invoked and the transaction is rolled back. By default, when the transaction is closed, all snapshots are invalidated and all objects based on those snapshots are invalidated (refaulted).
UpdateWithNoLocking	Objects are never locked. No comparisons are made between the snapshot and the row to ensure that the values in the corresponding database row haven't changed since the object was fetched.

EODatabaseContext also supports "on-demand" locking, in which specific optimistic locks can be promoted to database locks during the course of program execution. You can either use lockObjectWithGlobalID to lock a database row for a particular object, or objectsWithFetchSpecification to fetch objects with a fetch specification that includes locking.

See Also:

registeredDatabaseContextForModel(EOModel aModel, EOEditingContext anEditingContext), lockObjectWithGlobalID(EOGlobalID gid, EOEditingContext ec), objectsWithFetchSpecification( EOFetchSpecification fetchSpecification, EOEditingContext anEditingContext), EODatabaseContext.Delegate.databaseContextDidFetchObjects( EODatabaseContext dbCtxt, NSArray array , EOFetchSpecification fetchSpec, EOEditingContext ec), EODatabaseContext.Delegate.databaseContextShouldSelectObjects( EODatabaseContext dbCtxt , EOFetchSpecification fetchSpec, EODatabaseChannel dbChannel), EODatabaseContext.Delegate.databaseContextShouldUpdateCurrentSnapshot( EODatabaseContext dbCtxt , NSDictionary dic, NSDictionary dic2, EOGlobalID gid , EODatabaseChannel dbChannel), EODatabaseContext.Delegate.databaseContextShouldUsePessimisticLock( EODatabaseContext dbCtxt , EOFetchSpecification fetchSpec, EODatabaseChannel dbChannel), EODatabaseContext.Delegate.databaseContextNewPrimaryKey( EODatabaseContext dbCtxt , Object object, EOEntity entity), EODatabaseContext.Delegate.databaseContextShouldLockObjectWithGlobalID( EODatabaseContext dbCtxt , EOGlobalID gid, NSDictionary dic), EODatabaseContext.Delegate.databaseContextShouldFetchArrayFault( EODatabaseContext dbCtxt , Object object), EODatabaseContext.Delegate.databaseContextShouldFetchObjectFault( EODatabaseContext dbCtxt , Object object), batchFetchRelationship( EORelationship relationship, NSArray objects, EOEditingContext anEditingContext), EODatabaseContext.Delegate

Nested Class Summary

static class	EODatabaseContext.DatabaseContextEvent DatabaseContextEvent is a subclass of EOEvent, the parent class for objects that gather information, such as duration or order of execution, about various operations in WebObjects.
static interface	EODatabaseContext.Delegate This interface defines a delegate to EODatabaseContext to to handle specific requests that are ordinarily handled by EODatabaseContext.

Field Summary

static String	CustomQueryExpressionHintKey
static String	DatabaseChannelNeededNotification This nofification is broadcast whenever an EODatabaseContext is asked to perform an object store operation, and it does not have an available databaseChannel.
static String	DatabaseContextKey A key in an GenericAdaptorException's userInfo dictionary.
static String	DatabaseOperationsKey A key in an GenericAdaptorException's userInfo dictionary.
static String	FailedDatabaseOperationKey A key in an GenericAdaptorException's userInfo dictionary.
static String	StoredProcedureNameHintKey
static int	UpdateWithNoLocking Integer constant that identifies the locking strategy as no locking.
static int	UpdateWithOptimisticLocking Integer constant that identifies the locking strategy as optimistic.
static int	UpdateWithPessimisticLocking Integer constant that identifies the locking strategy as pessimistic.

Fields inherited from class com.webobjects.eocontrol.EOObjectStore

DeletedKey, InsertedKey, InvalidatedAllObjectsInStoreNotification, InvalidatedKey, ObjectsChangedInStoreNotification, UpdatedKey

Fields inherited from interface com.webobjects.foundation.NSLocking

OneCentury, OneDay, OneHour, OneMinute, OneSecond, OneWeek, OneYear

Constructor Summary

EODatabaseContext(EODatabase database)
Creates and returns a new EODatabaseContext with database assigned as the EODatabase object that the new context works.

Method Summary

EOAdaptorContext	adaptorContext() Returns the EOAdaptorContext used by the EODatabaseContext for communication with the database server.
NSArray	arrayFaultWithSourceGlobalID(EOGlobalID globalID, String name, EOEditingContext context) Creates and returns a to-many fault for the relationship name whose source entity must be the entity identified by globalID in the editing context context.
EODatabaseChannel	availableChannel() Returns the first database channel that isn't busy from the the list of EODatabaseChannels registered with the receiver.
void	batchFetchRelationship(EORelationship relationship, NSArray objects, EOEditingContext editingContext) Clears all the faults for relationship pointed by the source objects in objects and performs a single, efficient fetch or, at most, two fetches if the relationship is many-to-many.
void	commitChanges() Instructs the adaptor to commit the transaction.
static Class	contextClassToRegister() Returns the class that is created when a CooperatingObjectStoreNeeded notification is posted by an EOObjectStoreCoordinator.
EODatabase	database() Returns the receiver's EODatabase.
static Object	defaultDelegate() Returns the default delegate that will be used when initializing new EODatabaseContext instances.
Object	delegate() Returns the receiver's delegate.
void	dispose() Conformance to NSDisposable.
void	editingContextDidForgetObjectWithGlobalID(EOEditingContext context, EOGlobalID gid) Invoked when the editing context context is no longer using the object corresponding to gid.
EOEnterpriseObject	faultForGlobalID(EOGlobalID globalID, EOEditingContext context) Creates a to-one fault for the object identified by globalID and registers it in the editing context context.
EOEnterpriseObject	faultForRawRow(NSDictionary row, String entityName, EOEditingContext editingContext) Returns a fault for a raw row.
static EODatabaseContext	forceConnectionWithModel(EOModel model, NSDictionary overrides, EOEditingContext editingContext) Forces the stack of objects in the EOAccess layer to be instantiated, if necessary, and then makes a connection to the database.
void	forgetAllLocks() Clears all of the locks made for Enterprise Objects by the receiver.
void	forgetLocksForObjectsWithGlobalIDs(NSArray gids) Clears the locks made for the Enterprise Objects identified by each of the EOGlobalIDs in gids.
void	forgetSnapshotForGlobalID(EOGlobalID gid) Deletes the snapshot recorded for the Enterprise Object identified by gid.
void	forgetSnapshotsForGlobalIDs(NSArray gids) Deletes the snapshots recorded for the Enterprise Objects identified by gids, both in the receiver and in the EODatabase.
void	handleDroppedConnection() Cleans up after a database connection is dropped by unregistering the receiver's adaptor context and database channels, and then creating a new adaptor context.
boolean	handlesFetchSpecification(EOFetchSpecification fetchSpecification) Returns true if the entity identified by the entity name in fetchSpecification can be found in one of the models owned by the EODatabase of the receiver, false
boolean	hasBusyChannels() Returns true if the receiver's EOAdaptorContext has channels that have outstanding operations (that is, have a fetch in progress), false otherwise.
void	initializeObject(EOEnterpriseObject object, EOGlobalID gid, EOEditingContext context) Initializes the enteprise object object in the editing context context based on the snapshot for gid.
void	invalidateAllObjects() Discards all snapshots in the receiver's EODatabase, forgets all object locks, and posts an InvalidatedAllObjectsInStoreNotification, as well as an ObjectsChangedInStoreNotification with the globalIDs for the invalidated objects in the userInfo dictionary.
void	invalidateObjectsWithGlobalIDs(NSArray gids) Discards the snapshots for the objects identified by the EOGlobalIDs in gids and broadcasts an ObjectsChangedInStoreNotification, which causes any EOEditingContext containing objects fetched from the receiver to refault those objects.
boolean	isObjectLockedWithGlobalID(EOGlobalID gid) Returns true if the Enterprise Object identified by gid is locked, false otherwise.
boolean	isObjectLockedWithGlobalID(EOGlobalID gid, EOEditingContext ec) Returns true if the row corresponding to the globalID gid has been locked in an open transaction held by this database context.
static boolean	isSharedObjectLoadingEnabled() Returns true if the database contexts automatically load enterprise objects into the default shared editing context when they load a model which contains shared object fetch specifications, false if automatic loading is disabled.
NSDictionary	localSnapshotForGlobalID(EOGlobalID gid) Returns the snapshot for the object identified by gid, if there is one, otherwise returns null.
NSArray	localSnapshotForSourceGlobalID(EOGlobalID gid, String name) Returns the to-many snapshot for the relationship named name belonging to the Enterprise Object identified by the globalID gid, or null if there is no to-many snapshot.
void	lock() This method is used to protect access to the receiver from concurrent operations by multiple threads.
void	lockObjectWithGlobalID(EOGlobalID gid, EOEditingContext ec) Attempts to lock the database row corresponding to gid in the underlying database server on behalf of the editing context ec.
NSArray	missingObjectGlobalIDs() Returns an array of the globalIDs of any missing Enterprise Objects, or an empty array if no missing objects are known to the receiver.
NSArray	objectsForSourceGlobalID(EOGlobalID gid, String name, EOEditingContext context) Services a to-many fault.
NSArray	objectsWithFetchSpecification(EOFetchSpecification fetchSpec, EOEditingContext context) Fetches objects from an external store into context.
boolean	ownsGlobalID(EOGlobalID globalID) Returns true if the receiver is responsible for fetching and saving the object identified by globalID, false otherwise.
boolean	ownsObject(EOEnterpriseObject object) Returns true if the receiver is responsible for fetching and saving object, false otherwise.
void	performChanges() Constructs EOAdaptorOperations for all the EODatabaseOperations produced during recordChangesInEditingContext and recordUpdateForObject.
void	prepareForSaveWithCoordinator(EOObjectStoreCoordinator coordinator, EOEditingContext editingContext) Prepares to save changes.
void	recordChangesInEditingContext() Constructs a list of EODatabaseOperations for all changes to objects in the EOEditingContext that are owned by the receiver.
void	recordSnapshotForGlobalID(NSDictionary snapshot, EOGlobalID gid) Records snapshot under the globalID gid.
void	recordSnapshotForSourceGlobalID(NSArray gids, EOGlobalID gid, String name) For the object identified by gidgids, which is the array of globalIDs identifying the destination objects for the to-many relationship named name.
void	recordSnapshots(NSDictionary snapshots) Records the snapshots in snapshots, which is a dictionary whose keys are globalIDs and whose values are the snapshots for the enterprise objects identified by those globalIDs.
void	recordToManySnapshots(NSDictionary snapshots) Records a collection of to-many snapshots from a dictionary keyed by globalID.
void	recordUpdateForObject(EOEnterpriseObject object, NSDictionary changes) Applies changes supplied from another EOCooperatingObjectStore (through the EOObjectStoreCoordinator) to the database operation for object in the receiver.
void	refaultObject(EOEnterpriseObject object, EOGlobalID globalID, EOEditingContext context) Refault the Enterprise Object identified by globalID in the editing context context.
void	registerChannel(EODatabaseChannel channel) Registers the EODatabaseChannel channel with the receiver, adding it from the pool of available channels used to service fetch and fault requests.
NSArray	registeredChannels() Returns an array containing all of the EODatabaseChannels that have been registered for use with the receiver.
static EODatabaseContext	registeredDatabaseContextForModel(EOModel model, EOEditingContext editingContext) Finds the EOObjectStoreCoordinator for editingContext and checks whether it already contains an EODatabaseContext cooperating store for model.
static EODatabaseContext	registeredDatabaseContextForModel(EOModel model, EOObjectStoreCoordinator coordinator) Returns the cooperating object store that is registered with the EOObjectStoreCoordinator coordinator for the EOModel model.
void	registerLockedObjectWithGlobalID(EOGlobalID gid) Registers as a locked object the Enterprise Object identified by gid.
void	rollbackChanges() Instructs the adaptor to roll back the transaction.
void	saveChangesInEditingContext(EOEditingContext context) Sent by an EOEditingContext context to its EOObjectStore to commit changes.
static void	setContextClassToRegister(Class contextClass) Sets the class that is created and registered when a CooperatingObjectStoreNeeded notification is posted by an EOObjectStoreCoordinator to contextclass.
void	setCoordinator(EOObjectStoreCoordinator coord)
static void	setDefaultDelegate(Object defaultDelegate) Sets the default delegate for new instances of EODatabaseContext to defaultDelegate.
void	setDelegate(Object delegate) Sets delegate as the delegate for the receiver and all the receiver's EODatabaseChannels.
static void	setSharedObjectLoadingEnabled(boolean bool) Based on the value of the Boolean parameter bool, enables or disables automatic loading of Enterprise Objects into the default shared editing context when a database context loads a model which contains shared object fetch specifications.
void	setUpdateStrategy(int strategy) Sets the update strategy used by the receiver to strategy, which must be one of the following constants: 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.
NSDictionary	snapshotForGlobalID(EOGlobalID gid) Returns the snapshot associated with gid or null if there isn't one.
NSDictionary	snapshotForGlobalID(EOGlobalID gid, long timestamp) Returns the snapshot for the Enterprise Object identified by the globalID gid, provided the snapshot's timestamp is greater than or equal to timestamp.
NSArray	snapshotForSourceGlobalID(EOGlobalID gid, String name) Returns the to-many snapshot for the relationship named name belonging to the Enterprise Object identified by the globalID gid, or null if there is no to-many snapshot.
NSArray	snapshotForSourceGlobalID(EOGlobalID gid, String name, long timestamp) Returns the to-many snapshot for the globalID gid and relationship name, provided that the timestamp of the snapshot is greater than or equal to timestamp.
void	unlock() This method is used to protect access to the receiver from concurrent operations by multiple threads.
void	unregisterChannel(EODatabaseChannel channel) Unregisters the EODatabaseChannel channel with the receiver, removing it from the pool of available channels used to service fetch and fault requests.
int	updateStrategy() Returns the update strategy used by the receiver, one of the following constants: UpdateWithOptimisticLocking UpdateWithPessimisticLocking UpdateWithNoLocking The default strategy is UpdateWithOptimisticLocking.
NSDictionary	valuesForKeys(NSArray keys, EOEnterpriseObject object) Returns values for the specified keys from the snapshot of object.

Methods inherited from class com.webobjects.eocontrol.EOCooperatingObjectStore

coordinator

Methods inherited from class com.webobjects.eocontrol.EOObjectStore

invokeRemoteMethod

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CustomQueryExpressionHintKey

public static final String CustomQueryExpressionHintKey

DatabaseChannelNeededNotification

public static final String DatabaseChannelNeededNotification

This nofification is broadcast whenever an EODatabaseContext is asked to perform an object store operation, and it does not have an available databaseChannel. Subscribers can create a new channel and add it to the databaseContext at this time.

DatabaseContextKey

public static final String DatabaseContextKey

A key in an GenericAdaptorException's userInfo dictionary.

DatabaseOperationsKey

public static final String DatabaseOperationsKey

A key in an GenericAdaptorException's userInfo dictionary.

FailedDatabaseOperationKey

public static final String FailedDatabaseOperationKey

A key in an GenericAdaptorException's userInfo dictionary.

StoredProcedureNameHintKey

public static final String StoredProcedureNameHintKey

UpdateWithNoLocking

public static final int UpdateWithNoLocking

Integer constant that identifies the locking strategy as no locking.

See Also:

Constant Field Values

UpdateWithOptimisticLocking

public static final int UpdateWithOptimisticLocking

Integer constant that identifies the locking strategy as optimistic.

See Also:

Constant Field Values

UpdateWithPessimisticLocking

public static final int UpdateWithPessimisticLocking

Integer constant that identifies the locking strategy as pessimistic.

See Also:

Constant Field Values

Constructor Detail

EODatabaseContext

public EODatabaseContext(EODatabase database)

Creates and returns a new EODatabaseContext with database assigned as the EODatabase object that the new context works. Throws an exception if unable to obtain a new EOAdaptorContext from the underlying adaptor.

Parameters:

database - The EODatabase object that the new EODatabaseContext uses.

Throws:

IllegalStateException - if the underlying adaptor context can't create a corresponding adaptor channel.

See Also:

database(), EODatabaseContext

Method Detail

adaptorContext

public EOAdaptorContext adaptorContext()

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

Returns:

The EOAdaptorContext used by the receiver.

arrayFaultWithSourceGlobalID

public NSArray arrayFaultWithSourceGlobalID(EOGlobalID globalID,
                                            String name,
                                            EOEditingContext context)

Creates and returns a to-many fault for the relationship name whose source entity must be the entity identified by globalID in the editing context context. Throws an exception if globalID is not an instance of EOKeyGlobalID.

Specified by:

arrayFaultWithSourceGlobalID in class EOObjectStore

Parameters:

globalID - The unique identifier for the source entity for name.

name - The EORelationship for which to create the fault.

context - The EOEditingContext.

Returns:

The to-many fault for globalID and name.

Throws:

IllegalArgumentException - if globalID is not an instance of EOKeyGlobalID.

See Also:

faultForGlobalID(EOGlobalID globalID, EOEditingContext anEditingContext)

availableChannel

public EODatabaseChannel availableChannel()

Returns the first database channel that isn't busy from the the list of EODatabaseChannels registered with the receiver. If all registered channels are busy, posts a DatabaseChannelNeededNotification, then checks the list of available channels again to see if one has been added. If there are still no available channels, the receiver creates and opens a new EODatabaseChannel if possible, otherwise the method returns null.

Returns:

An open database channel that is registered with the receiver, or null.

See Also:

DatabaseChannelNeededNotification, registerChannel(EODatabaseChannel channel), registeredChannels(), unregisterChannel(EODatabaseChannel channel)

batchFetchRelationship

public void batchFetchRelationship(EORelationship relationship,
                                   NSArray objects,
                                   EOEditingContext editingContext)

Clears all the faults for relationship pointed by the source objects in objects and performs a single, efficient fetch or, at most, two fetches if the relationship is many-to-many. Throws an exception if any of the objects in objects doesn't originate from the same entity as relationship.

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 employees' departments individually.

Parameters:

relationship - An EORelationship.

objects - An array of source objects for relationship.

editingContext - The EOEditingContext.

Throws:

IllegalStateException - if anything in objects doesn't originate from the same entity as relationship.

commitChanges

public void commitChanges()

Instructs 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 ObjectsChangedInStoreNotification is posted describing the committed changes. Throws 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.

Specified by:

commitChanges in class EOCooperatingObjectStore

See Also:

ownsGlobalID(EOGlobalID globalID), rollbackChanges()

contextClassToRegister

public static Class contextClassToRegister()

Returns the class that is created when a CooperatingObjectStoreNeeded notification is posted by an EOObjectStoreCoordinator. The default is EODatabaseContext. Use setContextClassToRegister to specify a subclass of EODatabaseContext instead.

When an EOObjectStoreCoordinator sends a CooperatingObjectStoreNeeded notification for an entity in the default model group, an instance of the context class is created, the EOModel for the entity is registered, and the context class is registered with the requesting EOObjectStoreCoordinator.

Returns:

The class that is created in response to a CooperatingObjectStoreNeeded notification.

See Also:

setContextClassToRegister(Class contextClass)

database

public EODatabase database()

Returns the receiver's EODatabase.

Returns:

The receiver's EODatabase.

See Also:

EODatabaseContext(EODatabase aDatabase)

defaultDelegate

public static Object defaultDelegate()

Returns the default delegate that will be used when initializing new EODatabaseContext instances. Returns null unless the default delegate has been set with setDefaultDelegate.

Returns:

The default delegate, or null.

See Also:

setDefaultDelegate(Object defaultDelegate)

delegate

public Object delegate()

Returns the receiver's delegate.

Returns:

The receiver's delegate.

See Also:

setDelegate(Object delegate)

dispose

public void dispose()

Conformance to NSDisposable.

Specified by:

dispose in interface NSDisposable

Overrides:

dispose in class EOObjectStore

editingContextDidForgetObjectWithGlobalID

public void editingContextDidForgetObjectWithGlobalID(EOEditingContext context,
                                                      EOGlobalID gid)

Invoked when the editing context context is no longer using the object corresponding to gid. The receiver destroys related data, such as snapshots, for gid if no other objects are using them.

Do not invoke this method yourself; it is invoked automatically by the Framework.

Specified by:

editingContextDidForgetObjectWithGlobalID in class EOObjectStore

Parameters:

context - The EOEditingContext.

gid - The globalID identifying an object no longer in use by context.

See Also:

EODatabase.decrementSnapshotCountForGlobalID(EOGlobalID globalId), EODatabase.incrementSnapshotCountForGlobalID(EOGlobalID globalID)

faultForGlobalID

public EOEnterpriseObject faultForGlobalID(EOGlobalID globalID,
                                           EOEditingContext context)

Creates a to-one fault for the object identified by globalID and registers it in the editing context context. Throws an exception if globalID is not an instance of EOKeyGlobalID.

Specified by:

faultForGlobalID in class EOObjectStore

Parameters:

globalID - Identifer for the Enterprise Object for which to create a fault.

context - The EOEditingContext.

Returns:

The fault created for the object identifed by globalID.

Throws:

IllegalArgumentException - if globalID is not an instance of EOKeyGlobalID.

See Also:

arrayFaultWithSourceGlobalID(EOGlobalID globalID, String name, EOEditingContext context)

faultForRawRow

public EOEnterpriseObject faultForRawRow(NSDictionary row,
                                         String entityName,
                                         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 Enterprise Object you want to create as a fault. editingContext is the EOEditingContext in which to create the fault. Throws an exception if row does not contain primary key information for entityName.

Specified by:

faultForRawRow in class EOObjectStore

Parameters:

row - The raw data for the row, in the form of an NSDictionary.

entityName - The name of the appropriate entity for the Enterprise Object fault to be created.

editingContext - The EOEditingContext in which to create the fault.

Returns:

A fault for the specfied raw row.

Throws:

IllegalArgumentException - if row does not contain primary key information.

See Also:

EOEditingContext.faultForRawRow(com.webobjects.foundation.NSDictionary, java.lang.String, com.webobjects.eocontrol.EOEditingContext), faultForRawRow(com.webobjects.foundation.NSDictionary, java.lang.String, com.webobjects.eocontrol.EOEditingContext)

forceConnectionWithModel

public static EODatabaseContext forceConnectionWithModel(EOModel model,
                                                         NSDictionary overrides,
                                                         EOEditingContext editingContext)

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 model, it is first closed and then reconnected with a new connection dictionary made up of the original connection dictionary overlaid with the alternate values for keys specified in overrides. All compatible models in the model group also are associated with the new connection so that they share the same adaptor. Returns the EODatabaseContext associated with the model for the given editingContext.

Parameters:

model - The EOModel.

overrides - Alternate values for specified keys in the connection dictionary.

editingContext - The EOEditingContext.

Returns:

The EODatabaseContext associated with the model for editingContext

forgetAllLocks

public void forgetAllLocks()

Clears all of the locks made for Enterprise Objects by the receiver. Does not unlock the corresponding rows in the database server. This method is useful when something has happened to cause the database server to forget the locks, and the receiver needs to be synchronized with it.

This method is invoked whenever a transaction is committed or rolled back.

See Also:

registerLockedObjectWithGlobalID(EOGlobalID gid), isObjectLockedWithGlobalID(EOGlobalID gid), isObjectLockedWithGlobalID(EOGlobalID gid, EOEditingContext ec), forgetLocksForObjectsWithGlobalIDs(NSArray gids), lockObjectWithGlobalID(EOGlobalID gid, EOEditingContext ec), EOEditingContext.lockObject(EOEnterpriseObject object)

forgetLocksForObjectsWithGlobalIDs

public void forgetLocksForObjectsWithGlobalIDs(NSArray gids)

Clears the locks made for the Enterprise Objects identified by each of the EOGlobalIDs in gids. Does not unlock the corresponding rows in the database server.

Parameters:

gids - An array of globalIDs identifying objects which correspond to locked rows in the database.

See Also:

forgetAllLocks(), registerLockedObjectWithGlobalID(EOGlobalID gid), isObjectLockedWithGlobalID(EOGlobalID gid), isObjectLockedWithGlobalID(EOGlobalID gid, EOEditingContext ec), lockObjectWithGlobalID(EOGlobalID gid, EOEditingContext ec), EOEditingContext.lockObject(EOEnterpriseObject object)

forgetSnapshotForGlobalID

public void forgetSnapshotForGlobalID(EOGlobalID gid)

Deletes the snapshot recorded for the Enterprise Object identified by gid. Throws an exception if invoked when no transaction is in progress, or if gid is null.

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

Parameters:

gid - The globalID for an Enterprise Object.

Throws:

IllegalArgumentException - if gid is null.

IllegalStateException - if there is no transaction in progress.

See Also:

EODatabase, recordSnapshotForGlobalID(NSDictionary aSnapshot,EOGlobalID aGlobalID), localSnapshotForGlobalID(EOGlobalID globalID), recordSnapshots(NSDictionary snapshots), snapshotForGlobalID(EOGlobalID globalID, long timestamp), forgetSnapshotsForGlobalIDs(NSArray globalIDs)

forgetSnapshotsForGlobalIDs

public void forgetSnapshotsForGlobalIDs(NSArray gids)

Deletes the snapshots recorded for the Enterprise Objects identified by gids, both in the receiver and in the EODatabase.

Parameters:

gids - An array of globalIDs for Enterprise Objects whose snapshots should be deleted.

See Also:

recordSnapshotForGlobalID(NSDictionary aSnapshot,EOGlobalID aGlobalID), localSnapshotForGlobalID(EOGlobalID globalID), recordSnapshots(NSDictionary snapshots), snapshotForGlobalID(EOGlobalID globalID, long timestamp)

handleDroppedConnection

public void handleDroppedConnection()

Cleans up after a database connection is dropped by unregistering the receiver's adaptor context and database channels, and then creating a new adaptor context. Throws an exception if unable to obtain a new EOAdaptorContext from the underlying adaptor.

Do not invoke this method yourself. It is invoked automatically by the Framework.

Throws:

IllegalStateException - if unable to obtain a new EOAdaptorContext from the underlying adaptor.

handlesFetchSpecification

public boolean handlesFetchSpecification(EOFetchSpecification fetchSpecification)

Returns true if the entity identified by the entity name in fetchSpecification can be found in one of the models owned by the EODatabase of the receiver, falsetrue, the receiver is responsible for fetching the objects specified in fetchSpecification.

Specified by:

handlesFetchSpecification in class EOCooperatingObjectStore

Parameters:

fetchSpecification - The criteria to select and order a group of database records.

Returns:

true if the receiver is responsible for fetching the objects described fetchSpecification.

See Also:

ownsObject(EOEnterpriseObject object), ownsGlobalID(EOGlobalID globalID)

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.

Returns:

true if the receiver's EOAdaptorContext has channels with outstanding operations.

initializeObject

public void initializeObject(EOEnterpriseObject object,
                             EOGlobalID gid,
                             EOEditingContext context)

Initializes the enteprise object object in the editing context context based on the snapshot for gid. Throws an exception if gid does not identify a valid object in the specified editing context.

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.

Specified by:

initializeObject in class EOObjectStore

Parameters:

object - The Enterprise Object to initialize.

gid - The globalID for the snapshot from which to initialize object.

context - The EOEditingContext.

Throws:

IllegalStateException - if gid does not identify a valid object in context.

See Also:

EOEnterpriseObject.awakeFromInsertion(com.webobjects.eocontrol.EOEditingContext), EOEnterpriseObject.awakeFromFetch(com.webobjects.eocontrol.EOEditingContext), EOEditingContext.initializeObject(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext)

invalidateAllObjects

public void invalidateAllObjects()

Discards all snapshots in the receiver's EODatabase, forgets all object locks, and posts an InvalidatedAllObjectsInStoreNotification, as well as an ObjectsChangedInStoreNotification with the globalIDs for the invalidated objects in the userInfo dictionary. Both of these notifications are defined in EOObjectStore. This method works by invoking invalidateObjectsWithGlobalIDs for all of the snapshots in the receiver's EODatabase.

Specified by:

invalidateAllObjects in class EOObjectStore

See Also:

invalidateObjectsWithGlobalIDs(NSArray gids), EOObjectStore

invalidateObjectsWithGlobalIDs

public void invalidateObjectsWithGlobalIDs(NSArray gids)

Discards the snapshots for the objects identified by the EOGlobalIDs in gids and broadcasts an ObjectsChangedInStoreNotification, which causes any 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.

Specified by:

invalidateObjectsWithGlobalIDs in class EOObjectStore

Parameters:

gids - An array of globalIDs identifying objects whose snapshots to discard.

See Also:

EOObjectStore.invalidateAllObjects(), EOObjectStore.refaultObject(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), EOEditingContext.invalidateObjectsWithGlobalIDs(com.webobjects.foundation.NSArray), invalidateObjectsWithGlobalIDs(com.webobjects.foundation.NSArray)

isObjectLockedWithGlobalID

public boolean isObjectLockedWithGlobalID(EOGlobalID gid)

Returns true if the Enterprise Object identified by gid is locked, false otherwise.

Parameters:

gid - A globalID identifying an Enterprise Object.

Returns:

true if the Enterprise Object identified by code>gid is locked.

See Also:

forgetLocksForObjectsWithGlobalIDs(NSArray gids), forgetAllLocks(), registerLockedObjectWithGlobalID(EOGlobalID gid), isObjectLockedWithGlobalID(EOGlobalID gid), isObjectLockedWithGlobalID(EOGlobalID gid, EOEditingContext ec), lockObjectWithGlobalID(EOGlobalID gid, EOEditingContext ec), EOEditingContext.lockObject(EOEnterpriseObject object)

isObjectLockedWithGlobalID

public boolean isObjectLockedWithGlobalID(EOGlobalID gid,
                                          EOEditingContext ec)

Returns true if the row corresponding to the globalID gid has been locked in an open transaction held by this database context.

Specified by:

isObjectLockedWithGlobalID in class EOObjectStore

Parameters:

gid - The globalID identifying an Enterprise Object.

ec - The EOEditingContext.

Returns:

true if the database row corresponding to gid has been locked in an open transaction held by the receiver.

See Also:

forgetLocksForObjectsWithGlobalIDs(NSArray gids), forgetAllLocks(), registerLockedObjectWithGlobalID(EOGlobalID gid), isObjectLockedWithGlobalID(EOGlobalID gid), isObjectLockedWithGlobalID(EOGlobalID gid, EOEditingContext ec), lockObjectWithGlobalID(EOGlobalID gid, EOEditingContext ec), EOEditingContext.lockObject(EOEnterpriseObject object)

isSharedObjectLoadingEnabled

public static boolean isSharedObjectLoadingEnabled()

Returns true if the database contexts automatically load enterprise objects into the default shared editing context when they load a model which contains shared object fetch specifications, false if automatic loading is disabled.

Returns:

true if database contexts automatically load enterprise objects into the default shared editing context.

See Also:

EOEntity.sharedObjectFetchSpecificationNames()

localSnapshotForGlobalID

public NSDictionary localSnapshotForGlobalID(EOGlobalID gid)

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

Parameters:

gid - The globalID identifying the Enterprise Object whose local snapshot to return.

Returns:

The local snapshot for the object identified by gid, or null.

See Also:

recordSnapshotForGlobalID(NSDictionary aSnapshot,EOGlobalID aGlobalID), recordSnapshots(NSDictionary snapshots), snapshotForGlobalID(EOGlobalID globalID, long timestamp), forgetSnapshotsForGlobalIDs(NSArray globalIDs)

localSnapshotForSourceGlobalID

public NSArray localSnapshotForSourceGlobalID(EOGlobalID gid,
                                              String name)

Returns the to-many snapshot for the relationship named name belonging to the Enterprise Object identified by the globalID gid, or null if there is no to-many snapshot. A to-many snapshot is an array of globalIDs which identify the objects at the destination of a to-many relationship. Only searches locally (in the transaction scope), not in the EODatabase.

Parameters:

gid - The globalID for the Enterprise Object that owns the relationship name.

name - The name of the to-many relationship whose snapshot to return.

Returns:

The to-many snapshot for gid and name, or null.

See Also:

recordSnapshotForGlobalID(NSDictionary aSnapshot, EOGlobalID aGlobalID), snapshotForSourceGlobalID(EOGlobalID gid, String name, long timestamp)

lock

public void lock()

This method is used to protect access to the receiver from concurrent operations by multiple threads. Typically, this method is invoked by the Frameworks as most EODatabaseContexts are acting as cooperating EOObjectStores managed by an EOObjectStoreCoordinator. The coordinator locks its object stores when necessary. However, applications which make direct use of an EODatabaseContext should lock and unlock it as appropriate. Do not confuse this with any methods which work with the database locking mechanism.

Specified by:

lock in interface NSLocking

Specified by:

lock in class EOCooperatingObjectStore

See Also:

unlock(), EOObjectStoreCoordinator

lockObjectWithGlobalID

public void lockObjectWithGlobalID(EOGlobalID gid,
                                   EOEditingContext ec)

Attempts to lock the database row corresponding to gid in the underlying database server on behalf of the editing context ec. 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.

Specified by:

lockObjectWithGlobalID in class EOObjectStore

Parameters:

gid - The globalID identifying an Enterprise Object whose corresponding database row should be locked.

ec - The EOEditingContext.

Throws:

IllegalStateException - if unable to obtain the lock.

See Also:

forgetLocksForObjectsWithGlobalIDs(NSArray gids), forgetAllLocks(), registerLockedObjectWithGlobalID(EOGlobalID gid), isObjectLockedWithGlobalID(EOGlobalID gid), isObjectLockedWithGlobalID(EOGlobalID gid, EOEditingContext ec), lockObjectWithGlobalID(EOGlobalID gid, EOEditingContext ec), EOEditingContext.lockObject(EOEnterpriseObject object)

missingObjectGlobalIDs

public NSArray missingObjectGlobalIDs()

Returns an array of 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.

If an application tries to save a missing object, an exception is thrown. To be notified when a missing object is discovered, implement the delegate method databaseContextFailedToFetchObject.

Returns:

An array of the globalIDs of any missing Enterprise Objects.

objectsForSourceGlobalID

public NSArray objectsForSourceGlobalID(EOGlobalID gid,
                                        String name,
                                        EOEditingContext context)

Services a to-many fault. The snapshot for the source object identified by gid 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 the editing context context using the method objectsWithFetchSpecification.

Throws an exception in the following conditions:

• gid does not specify a valid source object in context.
• name is not a valid relationship in the model.
• There is no database snapshot available for gid.

Specified by:

objectsForSourceGlobalID in class EOObjectStore

Parameters:

gid - The globalID to identify the source object.

name - The name of the EORelationship.

context - The EOEditingContext into which to fetch the requested object.

Returns:

Array of requested objects.

Throws:

IllegalStateException - if context does not contain an object with the globalID gid, or ifname is not a valid relationship in the model, or if there is no snapshot for gid.

See Also:

objectsWithFetchSpecification(EOFetchSpecification fetchSpec, EOEditingContext context)

objectsWithFetchSpecification

public NSArray objectsWithFetchSpecification(EOFetchSpecification fetchSpec,
                                             EOEditingContext context)

Fetches objects from an external store into context. The receiver obtains an available EODatabaseChannel and performs a fetch with fetchSpec. Returns an array containing the fetched objects. If one of the fetched objects is already present in memory, by default this method doesn't overwrite its values with the new values from the database.

You can fine-tune the fetching behavior by adding hints to fetchSpec's hints dictionary. The class description for EOFetchSpecification contains additional information on using hints. You can also use this method to implement on-demand locking by using a fetch specification that includes locking.

Throws an exception if an error occurs; the error message indicates the nature of the problem.

Specified by:

objectsWithFetchSpecification in class EOObjectStore

Parameters:

fetchSpec - The criteria to select and order a group of database records.

context - The EOEditingContext into which objects are to be fetched.

Returns:

The array of fetched objects.

See Also:

(EOFetchSpecification fetchSpec, EOEditingContext context)

ownsGlobalID

public boolean ownsGlobalID(EOGlobalID globalID)

Returns true if the receiver is responsible for fetching and saving the object identified by globalID, false otherwise. The receiver is responsible if globalID is a subclass of EOKeyGlobalID and if globalID has an entity from a model belonging to one of the receiver's EODatabases.

Specified by:

ownsGlobalID in class EOCooperatingObjectStore

Parameters:

globalID - The unique identifier for an enteprise object.

Returns:

true if the receiver is responsible for fetching and saving the object identified by globalID.

See Also:

handlesFetchSpecification(EOFetchSpecification fetchSpec), ownsObject(EOEnterpriseObject object)

ownsObject

public boolean ownsObject(EOEnterpriseObject object)

Returns true if the receiver is responsible for fetching and saving object, false otherwise. The receiver is responsible if the entity corresponding to object can be found in a model belonging to one of the receiver's EODatabases.

Specified by:

ownsObject in class EOCooperatingObjectStore

Parameters:

object - An Enterprise Object.

Returns:

true if the receiver is responsible for fetching and saving object.

See Also:

handlesFetchSpecification(EOFetchSpecification fetchSpec), ownsGlobalID(EOGlobalID globalID)

performChanges

public void performChanges()

Constructs EOAdaptorOperations for all the EODatabaseOperations produced during recordChangesInEditingContext and recordUpdateForObject. Invokes the delegate method databaseContextWillOrderAdaptorOperations to give the delegate an opportunity to construct alternative adaptor operations from the database operations. Then invokes the delegate method databaseContextWillPerformAdaptorOperations to let the delegate substitute its own array of EOAdaptorOperations. Performs the EOAdaptorOperations on an available EOAdaptorChannel.

If the save succeeds, updates the snapshots in the receiver to reflect the new state of the server. Throws 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 thrown.
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.

You should never need to invoke this method directly.

Specified by:

performChanges in class EOCooperatingObjectStore

See Also:

EOAdaptorChannel, commitChanges(), rollbackChanges(), recordChangesInEditingContext(), recordUpdateForObject(EOEnterpriseObject object, NSDictionary changes)

prepareForSaveWithCoordinator

public void prepareForSaveWithCoordinator(EOObjectStoreCoordinator coordinator,
                                          EOEditingContext editingContext)

Prepares to save changes. If needed, generates primary keys for any new objects in editingContext that are owned by the receiver. This method is invoked before the object graph is analyzed and foreign key assignments are performed. Throws an exception in the following conditions:

• The receiver is currently saving for a different editing context.
• The underlying adaptor failed to get new primary keys for one of the entities associated with the objects in editingContext.
• The row corresponding to one of editingContext's objects could not be found in the database.

You should never need to invoke this method directly; it is invoked by the Framework.

Specified by:

prepareForSaveWithCoordinator in class EOCooperatingObjectStore

Parameters:

coordinator - The EOObjectStoreCoordinator.

editingContext - The current EOEditingContext.

Throws:

IllegalStateException - if the receiver is currently performing a save for another editing context, or if it could not obtain primary keys for an associated entity.

EOObjectNotAvailableException - if the database row for one of editingcontext's objects is missing.

recordChangesInEditingContext

public void recordChangesInEditingContext()

Constructs 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 is invoked after prepareForSaveWithCoordinator and before ownsGlobalID.

You should never need to invoke this method directly.

Specified by:

recordChangesInEditingContext in class EOCooperatingObjectStore

See Also:

prepareForSaveWithCoordinator( EOObjectStoreCoordinator coordinator , EOEditingContext editingContext), ownsGlobalID(EOGlobalID globalID)

recordSnapshotForGlobalID

public void recordSnapshotForGlobalID(NSDictionary snapshot,
                                      EOGlobalID gid)

Records snapshot under the globalID gid. Throws an exception in the following conditions:

• There is no transaction in progress.
• gid is null.
• snapshot is null

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

Parameters:

snapshot - The dictionary representation of an Enterprise Object with the last known values from the database.

gid - The EOGlobalID identifying snapshot's Enterprise Object.

Throws:

IllegalArgumentException - if either parameter is null.

IllegalStateException - if there is no transaction in progress.

See Also:

EODatabase, recordSnapshotForGlobalID(NSDictionary aSnapshot,EOGlobalID aGlobalID), localSnapshotForGlobalID(EOGlobalID globalID), recordSnapshots(NSDictionary snapshots), snapshotForGlobalID(EOGlobalID globalID, long timestamp), forgetSnapshotForGlobalID(EOGlobalID gid)

recordSnapshotForSourceGlobalID

public void recordSnapshotForSourceGlobalID(NSArray gids,
                                            EOGlobalID gid,
                                            String name)

For the object identified by gidgids, which is the array of globalIDs identifying the destination objects for the to-many relationship named name. Throws an exception in the following conditions:

• There is no transaction in progress.
• gid is null.
• gids is null

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

Parameters:

gids - Array of globalIDs identifying the objects at the destination of the relationship.

gid - Identifies the Enterprise Object whose to-many relationship is being snapshotted.

name - The name of the to-many relationship being snapshotted.

Throws:

IllegalArgumentException - if gid or gids is null.

IllegalStateException - if there is no transaction in progress.

See Also:

EODatabase, snapshotForSourceGlobalID(EOGlobalID gid, String name , long timestamp), localSnapshotForSourceGlobalID(EOGlobalID globalID, String name), recordToManySnapshots(NSDictionary snapshots)

recordSnapshots

public void recordSnapshots(NSDictionary snapshots)

Records the snapshots in snapshots, which is a dictionary whose keys are globalIDs and whose values are the snapshots for the enterprise objects identified by those globalIDs. Throws an exception if invoked when no transaction is in progress.

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

Parameters:

snapshots - A dictionary of snapshots to record, keyed by globalID.

Throws:

IllegalStateException - if no transaction is in progress.

See Also:

EODatabase, recordSnapshotForGlobalID(NSDictionary aSnapshot, EOGlobalID aGlobalID), localSnapshotForGlobalID(EOGlobalID globalID), forgetSnapshotForGlobalID(EOGlobalID gid), snapshotForSourceGlobalID(EOGlobalID gid, String name, long timestamp)

recordToManySnapshots

public void recordToManySnapshots(NSDictionary snapshots)

Records a collection of to-many snapshots from a dictionary keyed by globalID. The snapshots parameter should be a dictionary of NSDictionaries. The top-level dictionary has as its key the globalID of the Enterprise Object for which to-many relationship snapshots are being recorded. That key's value is a dictionary whose keys are the names of the Enterprise Object's to-many relationships, and whose values are arrays of globalIDs that identify the objects at the destination of each relationship. Throws an exception if invoked when no transaction is in progress

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

Parameters:

snapshots - A dictionary of dictionaries, keyed by globalIDs, representing the snapshots for the to-many relationships of the Enterprise Object identifed by the top-level key.

Throws:

IllegalStateException - if no transaction is in progress.

See Also:

EODatabase, recordSnapshotForSourceGlobalID(NSArray globalIDs, EOGlobalID globalID, String name), snapshotForSourceGlobalID(EOGlobalID globalId, String name, long timestamp), localSnapshotForSourceGlobalID(EOGlobalID gid, String name)

recordUpdateForObject

public void recordUpdateForObject(EOEnterpriseObject object,
                                  NSDictionary changes)

Applies changes supplied from another EOCooperatingObjectStore (through the EOObjectStoreCoordinator) to the database operation for 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 object store. This method can be invoked any time after prepareForSaveWithCoordinator and before ownsGlobalID.

Specified by:

recordUpdateForObject in class EOCooperatingObjectStore

Parameters:

object - The object for whose database operation changes will be applied.

changes - Array of changes to apply for object, supplied from another database context.

See Also:

prepareForSaveWithCoordinator(EOObjectStoreCoordinator coordinator, EOEditingContext editingContext), ownsGlobalID(EOGlobalID globalID)

refaultObject

public void refaultObject(EOEnterpriseObject object,
                          EOGlobalID globalID,
                          EOEditingContext context)

Refault the Enterprise Object identified by globalID in the editing context context. Throws an exception if globalID is not an instance of EOKeyGlobalID.

Newly-inserted objects should not be refaulted. Since they are not in the external store, they can not be refetched; attempting this will cause an exception to be thrown. 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's snapshot from the undo stack, with the result that object snapshot may no longer refer to the proper object.

Specified by:

refaultObject in class EOObjectStore

Parameters:

object - The EOEnterpriseObject to turn back into a fault.

globalID - The unique identifier for object.

context - The current EOEditingContext.

Throws:

IllegalArgumentException - if globalID is not an instance of EOKeyGlobalID.

See Also:

EOEditingContext.refaultObject(com.webobjects.eocontrol.EOEnterpriseObject), refaultObject(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext)

registerChannel

public void registerChannel(EODatabaseChannel channel)

Registers the EODatabaseChannel channel with the receiver, adding it from the pool of available channels used to service fetch and fault requests. Throws an exception if the receiver is not the parent object for channel or if channel is already registered with the receiver.

Use this method if you need to perform more than one fetch simultaneously.

Parameters:

channel - The EODatabaseChannel to be registered with the receiver.

Throws:

IllegalStateException - if the receiver is not the parent for channel, or if channel is already registered with the receiver.

See Also:

availableChannel(), registeredChannels(), unregisterChannel(EODatabaseChannel channel)

registerLockedObjectWithGlobalID

public void registerLockedObjectWithGlobalID(EOGlobalID gid)

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

Parameters:

gid - A globalID identifying an Enterprise Object that corresponds to a locked row in the database.

See Also:

forgetAllLocks(), isObjectLockedWithGlobalID(EOGlobalID gid, EOEditingContext ec), forgetLocksForObjectsWithGlobalIDs(NSArray gids), lockObjectWithGlobalID(EOGlobalID gid, EOEditingContext ec), EOEditingContext.lockObject(EOEnterpriseObject object)

registeredChannels

public NSArray registeredChannels()

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

Returns:

The array of all database channels registered for use with the receiver.

See Also:

availableChannel(), registeredChannels(), unregisterChannel(EODatabaseChannel channel)

registeredDatabaseContextForModel

public static EODatabaseContext registeredDatabaseContextForModel(EOModel model,
                                                                  EOObjectStoreCoordinator coordinator)

Returns the cooperating object store that is registered with the EOObjectStoreCoordinator coordinator for the EOModel model. If no cooperating object store is registered for model, this method instantiates a new EODatabaseContext, adds it to the coordinator, and returns it.

Parameters:

model - An EOModel.

coordinator - An EOObjectStoreCoordinator.

Returns:

The cooperating object store registered with coordinator for model.

registeredDatabaseContextForModel

public static EODatabaseContext registeredDatabaseContextForModel(EOModel model,
                                                                  EOEditingContext editingContext)

Finds the EOObjectStoreCoordinator for editingContext and checks whether it already contains an EODatabaseContext cooperating store for model. If it does, it returns that EODatabaseContext. Otherwise it instantiates a new EODatabaseContext, adds it to the coordinator, and returns it.

Parameters:

model - The current EOModel.

editingContext - The editing context.

Returns:

The cooperating object store for model.

rollbackChanges

public void rollbackChanges()

Instructs the adaptor to roll back the transaction. Rolls back any changed snapshots and releases all locks. Throws an exception if the adaptor is unable to roll back the transaction cleanly; the error message indicates the nature of the problem.

Specified by:

rollbackChanges in class EOCooperatingObjectStore

See Also:

ownsGlobalID(EOGlobalID globalID), commitChanges()

saveChangesInEditingContext

public void saveChangesInEditingContext(EOEditingContext context)

Sent by an EOEditingContext context to its EOObjectStore to commit changes. Normally, the EODatabaseContext is not called directly by this method but is instead called by an EOObjectStoreCoordinator. Throws an exception if an error occurs; the error message indicates the nature of the problem.

Specified by:

saveChangesInEditingContext in class EOObjectStore

Parameters:

context - The EOEditingContext in which the changes are to be saved.

See Also:

EOEditingContext.saveChangesInEditingContext(com.webobjects.eocontrol.EOEditingContext), saveChangesInEditingContext(com.webobjects.eocontrol.EOEditingContext), EOAdaptor

setContextClassToRegister

public static void setContextClassToRegister(Class contextClass)

Sets the class that is created and registered when a CooperatingObjectStoreNeeded notification is posted by an EOObjectStoreCoordinator to contextclass.

Parameters:

contextClass - The class to instantiate in response to a CooperatingObjectStoreNeeded notification.

See Also:

contextClassToRegister()

setCoordinator

public void setCoordinator(EOObjectStoreCoordinator coord)

Overrides:

setCoordinator in class EOCooperatingObjectStore

Parameters:

coord - the coordinator this cooperating store is has been registered with

See Also:

EOObjectStoreCoordinator.addCooperatingObjectStore(com.webobjects.eocontrol.EOCooperatingObjectStore), EOObjectStoreCoordinator.removeCooperatingObjectStore(com.webobjects.eocontrol.EOCooperatingObjectStore)

setDefaultDelegate

public static void setDefaultDelegate(Object defaultDelegate)

Sets the default delegate for new instances of EODatabaseContext to defaultDelegate.

Parameters:

defaultDelegate - The object to be assigned as delegate to new instances of EODatabaseContext.

setDelegate

public void setDelegate(Object delegate)

Sets delegate as the delegate for the receiver and all the receiver's EODatabaseChannels.

Parameters:

delegate - The object to set as the delegate for the receiver and its database channels.

See Also:

delegate()

setSharedObjectLoadingEnabled

public static void setSharedObjectLoadingEnabled(boolean bool)

Based on the value of the Boolean parameter bool, enables or disables automatic loading of Enterprise Objects into the default shared editing context when a database context loads a model which contains shared object fetch specifications. Automatic loading is enabled by default.

Parameters:

bool - Boolean flag that enables/disables automatic loading of objects into the default shared editing context.

See Also:

EOEntity.sharedObjectFetchSpecificationNames()

setUpdateStrategy

public void setUpdateStrategy(int strategy)

Sets the update strategy used by the receiver to strategy, which must be one of the following constants:

• 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.

Parameters:

strategy - The update strategy used by the receiver.

Throws:

IllegalArgumentException - if strategy is UpdateWithPessimisticLocking and the receiver's EODatabase contains snapshots.

See Also:

updateStrategy()

snapshotForGlobalID

public NSDictionary snapshotForGlobalID(EOGlobalID gid)

Returns the snapshot associated with gid or null if there isn't one. Searches first locally (in the transaction scope) and then in the EODatabase.

Parameters:

gid - The globalID of an Enterprise Object whose snapshot to return.

Returns:

The snapshot associated with gid, or null.

See Also:

recordSnapshotForGlobalID(NSDictionary aSnapshot, EOGlobalID aGlobalID), forgetSnapshotForGlobalID(EOGlobalID gid)

snapshotForGlobalID

public NSDictionary snapshotForGlobalID(EOGlobalID gid,
                                        long timestamp)

Returns the snapshot for the Enterprise Object identified by the globalID gid, provided the snapshot's timestamp is greater than or equal to timestamp. Returns null if there isn't a snapshot for gid or if the snapshot's timestamp is earlier (less) than the reference timestamp. Searches first locally (in the transaction scope) and then in the EODatabase.

Parameters:

gid - The globalID of an Enterprise Object whose snapshot to return.

timestamp - A reference timestamp to compare with the snapshot's timestamp.

Returns:

The snapshot for gid, or null.

See Also:

recordSnapshotForGlobalID(NSDictionary aSnapshot, EOGlobalID aGlobalID), forgetSnapshotForGlobalID(EOGlobalID gid)

snapshotForSourceGlobalID

public NSArray snapshotForSourceGlobalID(EOGlobalID gid,
                                         String name)

Returns the to-many snapshot for the relationship named name belonging to the Enterprise Object identified by the globalID gid, or null if there is no to-many snapshot. Searches first locally (in the transaction scope) and then in the EODatabase.

A to-many snapshot is an array of globalIDs which identify the objects at the destination of a to-many relationship.

Parameters:

gid - The globalID for the Enterprise Object that owns the relationship name.

name - The name of the to-many relationship whose snapshot to return.

Returns:

The to-many snapshot for gid and name, or null.

snapshotForSourceGlobalID

public NSArray snapshotForSourceGlobalID(EOGlobalID gid,
                                         String name,
                                         long timestamp)

Returns the to-many snapshot for the globalID gid and relationship name, provided that the timestamp of the snapshot is greater than or equal to timestamp. Returns null if there isn't a to-many snapshot for gid and name, or if the snapshot's timestamp is earlier (less) than the reference timestamp. Searches first locally (in the transaction scope) and then in the EODatabase.

Parameters:

gid - The globalID for the Enterprise Object that owns the relationship name.

name - The name of the to-many relationship whose snapshot to return.

timestamp - The reference timestamp to compare with the snapshot's timestamp.

Returns:

The to-many snapshot for gid and name, or null.

unlock

public void unlock()

This method is used to protect access to the receiver from concurrent operations by multiple threads. Typically, this method is invoked by the Frameworks as most EODatabaseContexts are acting as cooperating EOObjectStores managed by an EOObjectStoreCoordinator. The coordinator unlocks its stores when necessary. However, applications which make direct use of an EODatabaseContext should lock and unlock it as appropriate. Do not confuse this with any methods which work with the database locking mechanism.

Specified by:

unlock in interface NSLocking

Specified by:

unlock in class EOCooperatingObjectStore

See Also:

lock(), EOObjectStoreCoordinator

unregisterChannel

public void unregisterChannel(EODatabaseChannel channel)

Unregisters the EODatabaseChannel channel with the receiver, removing it from the pool of available channels used to service fetch and fault requests. Throws an exception if channel is not registered with the receiver.

Parameters:

channel - The EODatabaseChannel to unregister with the receiver.

Throws:

IllegalStateException - if channel is not registered with the receiver.

See Also:

registerChannel(EODatabaseChannel channel), registeredChannels(), availableChannel()

updateStrategy

public int updateStrategy()

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

• UpdateWithOptimisticLocking
• UpdateWithPessimisticLocking
• UpdateWithNoLocking

The default strategy is UpdateWithOptimisticLocking.

Returns:

The update strategy used by the receiver.

See Also:

setUpdateStrategy(int strategy)

valuesForKeys

public NSDictionary valuesForKeys(NSArray keys,
                                  EOEnterpriseObject object)

Returns 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.

Specified by:

valuesForKeys in class EOCooperatingObjectStore

Parameters:

keys - Array of keys whose values to return from the snapshot for object.

object - An Enterprise Object.

Returns:

The values for the specified keys from the snapshot for object.