PATH
Documentation > WebObjects 4.5 >
EOControl Reference
- 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
+ (id)defaultCoordinator
Returns a shared instance of EOObjectStoreCoordinator.
+ (void)setDefaultCoordinator:(EOObjectStoreCoordinator
*)coordinator
Sets a shared instance EOObjectStoreCoordinator.
Instance Methods
- (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
- (NSArray *)cooperatingObjectStores
Returns the receiver's EOCooperatingObjectStores. See
Also: - addCooperatingObjectStore:, - removeCooperatingObjectStore:
- (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
Initializes a newly allocated EOObjectStoreCoordinator
and returns self. This is the designated initializer
for the EOObjectStoreCoordinator class.
- (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:
- (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:
- (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:
- (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
- (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:
- 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.
- 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.
- 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.
- If ownsGlobalID: fails for any of
the EOCooperatingObjectStores, all stores are sent the message rollbackChanges.
- 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.
- 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.
- (void)setUserInfo:(NSDictionary
*)dictionary
Sets the dictionary of
auxiliary data, which your application can use for whatever it needs.See
Also: - userInfo
- (NSDictionary *)userInfo
Returns a dictionary of user data. Your application
can use this to store any auxiliary information it needs.See
Also: - setUserInfo:
- (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 |