Documentation Archive Developer
Search
PATH  Documentation > WebObjects 4.5 > EOControl Reference

Table of Contents

EOObjectStoreCoordinator


Inherits from:
EOObjectStore : NSObject
Conforms to:
NSObject
(NSObject)
Declared in:
EOControl/EOObjectStoreCoordinator.h




Class Description


EOObjectStoreCoordinator is a part of the control layer's object storage abstraction. An EOObjectStoreCoordinator object acts as a single object store by directing one or more EOCooperatingObjectStores in managing objects from distinct data repositories.

For more general information on the object storage abstraction, see "Object Storage Abstraction" in the introduction to the EOControl Framework.


EOObjectStore Methods

EOObjectStoreCoordinator overrides the following EOObjectStore methods:

With the exception of saveChangesInEditingContext:, EOObjectStoreCoordinator's implementation of these methods simply forwards the message to an EOCooperatingObjectStore or stores. The message invalidateAllObjects is forwarded to all of a coordinator's cooperating stores. The rest of the messages are forwarded to the appropriate store based on which store responds YES to the messages ownsGlobalID:, ownsObject:, and handlesFetchSpecification: (which message is used depends on the context). The EOObjectStore methods listed above aren't documented in this class specification (except for saveChangesInEditingContext:)-for descriptions of them, see the EOObjectStore and EODatabaseContext (EOAccess) class specifications

For the method saveChangesInEditingContext:, the coordinator guides its cooperating stores through a multi-pass save protocol in which each cooperating store saves its own changes and forwards remaining changes to the other of the coordinator's stores. For example, if in its recordChangesInEditingContext method one cooperating store notices the removal of an object from an "owning" relationship but that object belongs to another cooperating store, it informs the other store by sending the coordinator a forwardUpdateForObject:changes: message. For a more details, see the method description for saveChangesInEditingContext:.

Although it manages objects from multiple repositories, EOObjectStoreCoordinator doesn't absolutely guarantee consistent updates when saving changes across object stores. If your application requires guaranteed distributed transactions, you can either provide your own solution by creating a subclass of EOObjectStoreCoordinator that integrates with a TP monitor, use a database server with built-in distributed transaction support, or design your application to write to only one object store per save operation (though it may read from multiple object stores). For more discussion of this subject, see the method description for saveChangesInEditingContext:.




Constants


In EOObjectStoreCoordinator.h, EOControl defines NSString constants for the notifications it posts. For more information, see the section "Notifications" .



Method Types


Initializing instances
- init
Setting the default coordinator
+ setDefaultCoordinator:
+ defaultCoordinator
Managing EOCooperatingObjectStores
- addCooperatingObjectStore:
- removeCooperatingObjectStore:
- cooperatingObjectStores
Saving changes
- saveChangesInEditingContext:
Communication between EOCooperatingObjectStores
- forwardUpdateForObject:changes:
- valuesForKeys:object:
Returning EOCooperatingObjectStores
- objectStoreForGlobalID:
- objectStoreForFetchSpecification:
- objectStoreForObject:
Getting the userInfo dictionary
- userInfo
- setUserInfo:


Class Methods



defaultCoordinator

+ (id)defaultCoordinator

Returns a shared instance of EOObjectStoreCoordinator.

setDefaultCoordinator:

+ (void)setDefaultCoordinator:(EOObjectStoreCoordinator *)coordinator

Sets a shared instance EOObjectStoreCoordinator.


Instance Methods



addCooperatingObjectStore:

- (void)addCooperatingObjectStore:(EOCooperatingObjectStore *)store

Adds store to the list of EOCooperatingObjectStores that need to be queried and notified about changes to enterprise objects. The receiver reuses its stores: they don't go away until the EOObjectStoreCoordinator is destroyed or until the stores are explicitly removed. Posts the notification EOCooperatingObjectStoreWasAdded.

See Also: - removeCooperatingObjectStore:, - cooperatingObjectStores



cooperatingObjectStores

- (NSArray *)cooperatingObjectStores

Returns the receiver's EOCooperatingObjectStores.

See Also: - addCooperatingObjectStore:, - removeCooperatingObjectStore:



forwardUpdateForObject:changes:

- (void)forwardUpdateForObject:(id)object changes:(NSDictionary *)changes

Tells the receiver to forward a message from an EOCooperatingObjectStore to another store, informing it that changes need to be made to object. For example, inserting an object in a relationship property of one EOCooperatingObjectStore might require changing a foreign key property in an object owned by another EOCooperatingObjectStore.

This method first locates the EOCooperatingObjectStore that's responsible for applying changes, and then it sends the store the message recordUpdateForObject:changes:.



init

- init

Initializes a newly allocated EOObjectStoreCoordinator and returns self. This is the designated initializer for the EOObjectStoreCoordinator class.

objectStoreForFetchSpecification:

- (EOCooperatingObjectStore *)objectStoreForFetchSpecification:(EOFetchSpecification *)fetchSpecification

Returns the EOCooperatingObjectStore responsible for fetching objects with fetchSpecification. Returns nil if no EOCooperatingObjectStore can be found that responds YES to handlesFetchSpecification:.

See Also: - objectStoreForGlobalID:, - objectStoreForObject:



objectStoreForGlobalID:

- (EOCooperatingObjectStore *)objectStoreForGlobalID:(EOGlobalID *)globalID

Returns the EOCooperatingObjectStore for the object identified by globalID. Returns nil if no EOCooperatingObjectStore can be found that responds YES to ownsGlobalID:.

See Also: - objectStoreForFetchSpecification:, - objectStoreForObject:



objectStoreForObject:

- (EOCooperatingObjectStore *)objectStoreForObject:(id)object

Returns the EOCooperatingObjectStore that owns object. Returns nil if no EOCooperatingObjectStore can be found that responds YES to ownsObject:.

See Also: - objectStoreForFetchSpecification:, - objectStoreForGlobalID:



removeCooperatingObjectStore:

- (void)removeCooperatingObjectStore:(EOCooperatingObjectStore *)store

Removes store from the list of EOCooperatingObjectStores that need to be queried and notified about changes to enterprise objects. Posts the notification EOCooperatingObjectStoreWasRemoved.

See Also: - addCooperatingObjectStore:, - cooperatingObjectStores



saveChangesInEditingContext:

- (void)saveChangesInEditingContext:(EOEditingContext *)anEditingContext

Overrides the EOObjectStore implementation to save the changes made in anEditingContext. This message is sent by an EOEditingContext to an EOObjectStoreCoordinator to commit changes. When an EOObjectStoreCoordinator receives this message, it guides its EOCooperatingObjectStores through a multi-pass save protocol in which each EOCooperatingObjectStore saves its own changes and forwards remaining changes to other EOCooperatingObjectStores. When this method is invoked, the following sequence of events occurs:
  1. The receiver sends each of its EOCooperatingObjectStores the message prepareForSaveWithCoordinator:editingContext:, which informs them that a multi-pass save operation is beginning. When the EOCooperatingObjectStore is an EODatabaseContext (EOAccess), it takes this opportunity to generate primary keys for any new objects in the EOEditingContext.
  2. The receiver sends each of its EOCooperatingObjectStores the message recordChangesInEditingContext, which prompts them to examine the changed objects in the editing context, record operations that need to be performed, and notify the receiver of any changes that need to be forwarded to other stores. For example, if in its recordChangesInEditingContext method one EOCooperatingObjectStore notices the removal of an object from an "owning" relationship but that object belongs to another EOCooperatingObjectStore, it informs the other store by sending the coordinator a forwardUpdateForObject:changes: message.
  3. The receiver sends each of its EOCooperatingObjectStores the message ownsGlobalID:. This tells the stores to transmit their changes to their underlying databases. When the EOCooperatingObjectStore is an EODatabaseContext, it responds to this message by taking the EODatabaseOperations (EOAccess) that were constructed in the previous step, constructing EOAdaptorOperations (EOAccess) from them, and giving the EOAdaptorOperations to an available EOAdaptorChannel (EOAccess) for execution.
  4. If ownsGlobalID: fails for any of the EOCooperatingObjectStores, all stores are sent the message rollbackChanges.
  5. If ownsGlobalID: succeeds for all EOCooperatingObjectStores, the receiver sends them the message commitChanges, which has the effect of telling the adaptor to commit the changes.
  6. If commitChanges fails for a particular EOCooperatingObjectStore, that store and all subsequent ones are sent the message rollbackChanges. However, the stores that have already committed their changes do not roll back. In other words, the coordinator doesn't perform the two-phase commit protocol necessary to guarantee consistent distributed update.

This method raises an exception if an error occurs.



setUserInfo:

- (void)setUserInfo:(NSDictionary *)dictionary

Sets the dictionary of auxiliary data, which your application can use for whatever it needs.

See Also: - userInfo



userInfo

- (NSDictionary *)userInfo

Returns a dictionary of user data. Your application can use this to store any auxiliary information it needs.

See Also: - setUserInfo:



valuesForKeys:object:

- (NSDictionary *)valuesForKeys:(NSArray *)keys object:(id)object

Communicates with the appropriate EOCooperatingObjectStore to get the values identified by keys for object, so that it can then forward them on to another EOCooperatingObjectStore. EOCooperatingObjectStores can hold values for an object that augment the properties in the object. For instance, an EODatabaseContext (EOAccess) stores foreign key information for the objects it owns. These foreign keys may well not be defined as properties of the object. Other EODatabaseContexts can find out the object's foreign keys by sending the EODatabaseContext that owns the object a valuesForKeys:object: message (through the coordinator).


Notifications


The following notifications are declared and posted by EOObjectStoreCoordinator.

EOCooperatingObjectStoreWasAdded

EOCONTROL_EXTERN NSString *EOCooperatingObjectStoreWasAdded

When an EOObjectStoreCoordinator receives an addCooperatingObjectStore: message and adds an EOCooperatingObjectStore to its list, it posts EOCooperatingObjectStoreWasAdded to notify observers.


Notification Object The EOObjectStoreCoordinator
userInfo Dictionary None

EOCooperatingObjectStoreWasRemoved

EOCONTROL_EXTERN NSString *EOCooperatingObjectStoreWasRemoved

When an EOObjectStoreCoordinator receives a removeCooperatingObjectStore: message and removes an EOCooperatingObjectStore from its list, it posts EOCooperatingObjectStoreWasRemoved to notify observers.
Notification Object The EOObjectStoreCoordinator
userInfo Dictionary None

EOCooperatingObjectStoreNeeded

EOCONTROL_EXTERN NSString *EOCooperatingObjectStoreNeeded

Posted when an EOObjectStoreCoordinator receives a request that it can't service with any of its currently registered EOCooperatingObjectStores. The observer can call back to the coordinator to register an appropriate EOCooperatingObjectStore based on the information in the userInfo dictionary.
Notification Object
The EOObjectStoreCoordinator
userInfo Dictionary
Contains the following keys and values:
Key Value
globalID globalID for the operation
fetchSpecification fetch specification for the operation
object object for the operation



Table of Contents