com.webobjects.eocontrol
Class EOCooperatingObjectStore

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

All Implemented Interfaces:

NSDisposable, NSLocking

Direct Known Subclasses:

EODatabaseContext

public abstract class EOCooperatingObjectStore

extends EOObjectStore

implements NSLocking

EOCooperatingObjectStore is a part of the control layer's object storage abstraction. It is an abstract class that defines the basic API for object stores that work together to manage data from several distinct data repositories.

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

The interaction between EOCooperatingObjectStores is managed by another class, EOObjectStoreCoordinator. The EOObjectStoreCoordinator communicates changes to its EOCooperatingObjectStores by passing them an EOEditingContext. Each cooperating store examines the modified objects in the editing context and determines if it's responsible for handling the changes. When a cooperating store has changes that need to be handled by another store, it communicates the changes to the other store back through the coordinator.

For relational databases, Enterprise Objects Framework provides a concrete subclass of EOCooperatingObjectStore, EODatabaseContext (EOAccess). A database context represents a single connection to a database server, fetching and saving objects on behalf of one or more editing contexts. However, a database context and an editing context don't interact with each other directly-a coordinator acts as a mediator between them.

For more information on EOCooperatingObjectStore, refer to:

• "Object Storage Abstraction"

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

EOCooperatingObjectStore()

Method Summary

abstract void	commitChanges() Overridden by subclasses to commit the transaction.
EOObjectStoreCoordinator	coordinator()
abstract boolean	handlesFetchSpecification(EOFetchSpecification fetchSpecification) Overridden by subclasses to return true if the receiver is responsible for fetching the objects described by fetchSpecification.
abstract void	lock() Attempts to acquire a lock.
abstract boolean	ownsGlobalID(EOGlobalID globalID) Overridden by subclasses to return true if the receiver is responsible for fetching and saving the object identified by globalID.
abstract boolean	ownsObject(EOEnterpriseObject object) Overridden by subclasses to return true if the receiver is responsible for fetching and saving object.
abstract void	performChanges() Overridden by subclasses to transmit changes to the receiver's underlying database.
abstract void	prepareForSaveWithCoordinator(EOObjectStoreCoordinator coordinator, EOEditingContext context) Overridden by subclasses to notify the receiver that a multi-store save operation overseen by coordinator is beginning for the EOEditingContext, context.
abstract void	recordChangesInEditingContext() Overridden by subclasses to instruct the receiver to examine the changed objects in the receiver's EOEditingContext, record any operations that need to be performed, and notify the receiver's EOObjectStoreCoordinator of any changes that need to be forwarded to other EOCooperatingObjectStores.
abstract void	recordUpdateForObject(EOEnterpriseObject object, NSDictionary changes) Overridden by subclasses to communicate from one EOCooperatingObjectStore to another (through the EOObjectStoreCoordinator) that changes need to be made to the an EOEnterpriseObject.
abstract void	rollbackChanges() Overridden by subclasses to roll back changes to the underlying database.
void	setCoordinator(EOObjectStoreCoordinator newCoordinator)
abstract void	unlock() Relinquishes a previously acquired lock.
abstract NSDictionary	valuesForKeys(NSArray keys, EOEnterpriseObject object) Overridden by subclasses to return values (as identified by keys) held by the receiver that augment properties in object.

Methods inherited from class com.webobjects.eocontrol.EOObjectStore

arrayFaultWithSourceGlobalID, dispose, editingContextDidForgetObjectWithGlobalID, faultForGlobalID, faultForRawRow, initializeObject, invalidateAllObjects, invalidateObjectsWithGlobalIDs, invokeRemoteMethod, isObjectLockedWithGlobalID, lockObjectWithGlobalID, objectsForSourceGlobalID, objectsWithFetchSpecification, refaultObject, saveChangesInEditingContext

Methods inherited from class java.lang.Object

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

Constructor Detail

EOCooperatingObjectStore

public EOCooperatingObjectStore()

Method Detail

commitChanges

public abstract void commitChanges()

Overridden by subclasses to commit the transaction. Throws an exception if an error occurs; the error message indicates the nature of the problem.

See Also:

ownsGlobalID(com.webobjects.eocontrol.EOGlobalID), commitChanges(), EOObjectStoreCoordinator.saveChangesInEditingContext(com.webobjects.eocontrol.EOEditingContext)

coordinator

public EOObjectStoreCoordinator coordinator()

Returns:

the EOObjectStoreCoordinator this cooperating store is registered with, or null if it is not

See Also:

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

handlesFetchSpecification

public abstract boolean handlesFetchSpecification(EOFetchSpecification fetchSpecification)

Overridden by subclasses to return true if the receiver is responsible for fetching the objects described by fetchSpecification. For example, EODatabaseContext (EOAccess) determines whether it's responsible based on fetchSpecification's entity name.

Parameters:

fetchSpecification - an EOFetchSpecification.

Returns:

true if this EOCooperatingObjectStore is responsible for fetching and saving objects from fetchSpecification, false otherwise.

See Also:

ownsGlobalID(com.webobjects.eocontrol.EOGlobalID), ownsObject(com.webobjects.eocontrol.EOEnterpriseObject)

lock

public abstract void lock()

Description copied from interface: NSLocking

Attempts to acquire a lock. This method blocks a thread's execution until the lock can be acquired.

An application protects a critical section of code by requiring a thread to acquire a lock before executing the code. Once the critical section is past, the thread relinquishes the lock by invoking unlock.

Specified by:

lock in interface NSLocking

Overrides:

lock in class EOObjectStore

Following copied from class: com.webobjects.eocontrol.EOObjectStore

See Also:

EOObjectStore.unlock()

ownsGlobalID

public abstract boolean ownsGlobalID(EOGlobalID globalID)

Overridden by subclasses to return true if the receiver is responsible for fetching and saving the object identified by globalID. For example, EODatabaseContext (EOAccess) determines whether it's responsible based on the entity associated with globalID.

Parameters:

globalID - the EOGlobalID for an object

Returns:

true if this EOCooperatingObjectStore is responsible for fetching and saving the object identified by globalID, false otherwise

See Also:

handlesFetchSpecification(com.webobjects.eocontrol.EOFetchSpecification), ownsObject(com.webobjects.eocontrol.EOEnterpriseObject)

ownsObject

public abstract boolean ownsObject(EOEnterpriseObject object)

Overridden by subclasses to return true if the receiver is responsible for fetching and saving object. For example, EODatabaseContext (EOAccess) determines whether it's responsible based on the entity associated with object.

Parameters:

object - an EOEnterpriseObject

Returns:

true if this EOCooperatingObjectStore is responsible for fetching and saving object, false otherwise

See Also:

handlesFetchSpecification(com.webobjects.eocontrol.EOFetchSpecification), ownsGlobalID(com.webobjects.eocontrol.EOGlobalID)

performChanges

public abstract void performChanges()

Overridden by subclasses to transmit changes to the receiver's underlying database. Raises an exception if an error occurs; the error message indicates the nature of the problem.

See Also:

commitChanges(), rollbackChanges(), EOObjectStoreCoordinator.saveChangesInEditingContext(com.webobjects.eocontrol.EOEditingContext)

prepareForSaveWithCoordinator

public abstract void prepareForSaveWithCoordinator(EOObjectStoreCoordinator coordinator,
                                                   EOEditingContext context)

Overridden by subclasses to notify the receiver that a multi-store save operation overseen by coordinator is beginning for the EOEditingContext, context. For example, the receiver might prepare primary keys for newly inserted objects so that they can be handed out to other EOCooperatingObjectStores upon request. The receiver should be prepared to receive the messages recordChangesInEditingContext and recordUpdateForObject. After performing these methods, the receiver should be prepared to receive the possible messages ownsGlobalID and then commitChanges or rollbackChanges.

Parameters:

coordinator - the EOObjectStoreCoordinator that will oversee the save operation

context - the EOEditingContext for which the save operation is beginning

recordChangesInEditingContext

public abstract void recordChangesInEditingContext()

Overridden by subclasses to instruct the receiver to examine the changed objects in the receiver's EOEditingContext, record any operations that need to be performed, and notify the receiver's EOObjectStoreCoordinator of any changes that need to be forwarded to other EOCooperatingObjectStores.

See Also:

prepareForSaveWithCoordinator(com.webobjects.eocontrol.EOObjectStoreCoordinator, com.webobjects.eocontrol.EOEditingContext), recordUpdateForObject(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.foundation.NSDictionary)

recordUpdateForObject

public abstract void recordUpdateForObject(EOEnterpriseObject object,
                                           NSDictionary changes)

Overridden by subclasses to communicate from one EOCooperatingObjectStore to another (through the EOObjectStoreCoordinator) that changes need to be made to the an EOEnterpriseObject. For example, an insert of an object in a relationship property might require changing a foreign key property in an object owned by another EOCooperatingObjectStore. This method is primarily used to manipulate relationships.

Parameters:

object - the object that has updates to have recorded

changes - dictionary of attribute-value pairs to record for object

See Also:

prepareForSaveWithCoordinator(com.webobjects.eocontrol.EOObjectStoreCoordinator, com.webobjects.eocontrol.EOEditingContext), recordChangesInEditingContext()

rollbackChanges

public abstract void rollbackChanges()

Overridden by subclasses to roll back changes to the underlying database. Raises one of several possible exceptions if an error occurs; the error message should indicate the nature of the problem.

See Also:

ownsGlobalID(com.webobjects.eocontrol.EOGlobalID), commitChanges(), EOObjectStoreCoordinator.saveChangesInEditingContext(com.webobjects.eocontrol.EOEditingContext)

setCoordinator

public void setCoordinator(EOObjectStoreCoordinator newCoordinator)

Parameters:

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

See Also:

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

unlock

public abstract void unlock()

Description copied from interface: NSLocking

Relinquishes a previously acquired lock.

Specified by:

unlock in interface NSLocking

Overrides:

unlock in class EOObjectStore

Following copied from class: com.webobjects.eocontrol.EOObjectStore

See Also:

EOObjectStore.lock()

valuesForKeys

public abstract NSDictionary valuesForKeys(NSArray keys,
                                           EOEnterpriseObject object)

Overridden by subclasses to return values (as identified by keys) held by the receiver that augment properties in object. For instance, an EODatabaseContext (EOAccess) stores foreign keys for the objects it owns (and primary keys for new objects). These foreign and primary keys may not be defined as properties of the object. Other database contexts can find out these keys by sending the database context that owns the object a valuesForKeys message. Note that you use this for properties that are not stored in the object, so using key-value coding directly on the object won't always work.

Parameters:

keys - property names to return values for

object - object to return values for

Returns:

a dictionary of key-value pairs to use to augment object's properties.