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	cleanupSnapshots() Force the weak references hold by this context to be freed.
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, setUserInfo, setUserInfoForKey, userInfo, userInfoForKey

Methods inherited from class java.lang.Object

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

Field Detail

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

UpdateWithNoLocking

public static final int UpdateWithNoLocking

Integer constant that identifies the locking strategy as no locking.

See Also:

Constant Field Values

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.

See Also:

Constant Field Values

CustomQueryExpressionHintKey

public static final String CustomQueryExpressionHintKey

See Also:

Constant Field Values

StoredProcedureNameHintKey

public static final String StoredProcedureNameHintKey

See Also:

Constant Field Values

DatabaseContextKey

public static final String DatabaseContextKey

A key in an GenericAdaptorException's userInfo dictionary.

See Also:

Constant Field Values

DatabaseOperationsKey

public static final String DatabaseOperationsKey

A key in an GenericAdaptorException's userInfo dictionary.

See Also:

Constant Field Values

FailedDatabaseOperationKey

public static final String FailedDatabaseOperationKey

A key in an GenericAdaptorException's userInfo dictionary.

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

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.

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)

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

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

dispose

public void dispose()

Conformance to NSDisposable.

Specified by:

dispose in interface NSDisposable

Overrides:

dispose in class EOObjectStore

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)

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

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.

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

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, EOObjectStoreCoordinator#removeCooperatingObjectStore

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)

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)

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

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)

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.

database

public EODatabase database()

Returns the receiver's EODatabase.

Returns:

The receiver's EODatabase.

See Also:

EODatabaseContext(EODatabase aDatabase)

adaptorContext

public EOAdaptorContext adaptorContext()

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

Returns:

The EOAdaptorContext used by the receiver.

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)

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

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)

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)

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, provid