EOObjectStore

Inherits from: Object

Package: com.webobjects.eocontrol

Class Description

EOObjectStore is the abstract class that defines the API for an "intelligent" repository of objects, the control layer's object storage abstraction. An object store is responsible for constructing and registering objects, servicing object faults, and saving changes made to objects. For more information on the object storage abstraction, see "Object Storage Abstraction" (page 23) in the introduction to the EOControl Framework.

EOEditingContext is the principal EOObjectStore subclass and is used for managing objects in memory-in fact, the primary purpose of the EOObjectStore class is to define an API for servicing editing contexts, not to define a completely general API. Other subclasses of EOObjectStore are:

EOCooperatingObjectStore
EOObjectStoreCoordinator
EODatabaseContext (EOAccess)

A subclass of EOObjectStore must implement all of its methods. The default implementations simply throw exceptions.

Constants

EOObjectStore defines the following String constants to be used as keys in the notifications it posts:

DeletedKey
InsertedKey
InvalidatedKey
UpdatedKey

Additionally, EOObjectStore defines String constants for the names of the notifications it posts. See the section "Notifications" (page 281) for more information on the notifications.

Method Types

Initializing objectsinitializeObjectGetting objectsobjectsWithFetchSpecification objectsForSourceGlobalIDGetting faultsfaultForGlobalID arrayFaultWithSourceGlobalID refaultObject faultForRawRowLocking objectslockObjectWithGlobalID isObjectLockedWithGlobalIDSaving changes to objectssaveChangesInEditingContextInvalidating and forgetting objectsinvalidateAllObjects invalidateObjectsWithGlobalIDs:editingContextDidForgetObjectWithGlobalIDInteracting with the serverinvokeRemoteMethodw

Constructors

EOObjectStore

public EOObjectStore()

Description forthcoming.

Instance Methods

arrayFaultWithSourceGlobalID

public abstract NSArray arrayFaultWithSourceGlobalID( EOGlobalID globalID, String relationshipName, EOEditingContext anEditingContext)

Implemented by subclasses to return the destination objects for a to-many relationship, whether as real instances or as faults (empty enterprise objects). globalID identifies the source object for the relationship (which doesn't necessarily exist in memory yet), and relationshipName is the name of the relationship. The object identified by globalID and the destination objects for the relationship all belong to anEditingContext.

If you implement this method to return a fault, you must define an EOFaultHandler subclass that stores globalID and relationshipName, using them to fetch the objects in a later objectsForSourceGlobalID message and that turns the fault into an array containing those objects. See the EOFaultHandler class specification for more information on faults.

See the EOEditingContext and EODatabaseContext (EOAccess) class specifications for more information on how this method works in concrete subclasses.

See Also: faultForGlobalID

dispose

public void dispose()

Description forthcoming.

editingContextDidForgetObjectWithGlobalID

public abstract void editingContextDidForgetObjectWithGlobalID( EOEditingContext context, EOGlobalID gid)

Invoked to inform the object store that it can stop keeping data about an object it passed to a child. Don't invoke this method; it is invoked automatically by the Framework.

faultForGlobalID

public abstract EOEnterpriseObject faultForGlobalID( EOGlobalID globalID, EOEditingContext anEditingContext)

If the receiver is anEditingContext and the object associated with globalID is already registered in anEditingContext, this method returns that object. Otherwise it creates a to-one fault, registers it in anEditingContext, and returns the fault. This method is always directed first at anEditingContext, which forwards the message to its parent object store if needed to create a fault.

If you implement this method to return a fault (an empty enterprise object), you must define an EOFaultHandler subclass that stores globalID, uses it to fetch the object's data, and initializes the object with EOObjectStore's initializeObject. See the EOFaultHandler class specification for more information on faults.

See the EOEditingContext and EODatabaseContext (EOAccess) class specifications for more information on how this method works in concrete subclasses.

See Also: arrayFaultWithSourceGlobalID, recordObject (EOEditingContext)

faultForRawRow

public abstract EOEnterpriseObject faultForRawRow( NSDictionary row, String entityName, EOEditingContext anEOEditingContext)

Returns a fault for the enterprise object corresponding to row, which is a dictionary of values containing at least the primary key of the corresponding enterprise object. This is especially useful if you have fetched raw rows and now want a unique enterprise object.

initializeObject

public abstract void initializeObject( EOEnterpriseObject anObject, EOGlobalID globalID, EOEditingContext anEditingContext)

Implemented by subclasses to set anObject's properties, as obtained for globalID. This method is typically invoked after anObject has been created using EOClassDescription's createInstanceWithEditingContext or using EOGenericRecord's or EOCustomObject's constructors. This method is also invoked after a fault has been fired.

See Also: awakeFromInsertion (EOEnterpriseObject), awakeFromFetch (EOEnterpriseObject)

invalidateAllObjects

public abstract void invalidateAllObjects()

Discards the values of all objects held by the receiver and turns them into faults (empty enterprise objects). This causes all locks to be dropped and any transaction to be rolled back. The next time any object is accessed, its data is fetched anew. Any child object stores are also notified that the objects are no longer valid. See the EOEditingContext class specification for more information on how this method works in concrete subclasses.

This method should also post an InvalidatedAllObjectsInStoreNotification.

invalidateObjectsWithGlobalIDs:

public abstract void invalidateObjectsWithGlobalIDs(NSArray globalIDs)

Signals that the objects identified by the EOGlobalIDs in globalIDs should no longer be considered valid and that they should be turned into faults (empty enterprise objects). This causes data for each object to be refetched the next time it's accessed. Any child object stores are also notified that the objects are no longer valid.

See Also: invalidateAllObjects, refaultObject

invokeRemoteMethod

public Object invokeRemoteMethod( EOEditingContext anEditingContext, EOGlobalID receiverGID, String methodName, Class[] aClass Object[] arguments)

Invokes methodName on the enterprise object identified by receiverGID in anEditingContext, using arguments. To pass an enterprise object as an argument, use its global ID. This method has the side effect of saving all the changes from the editing context all the way down to the editing context in the server session.

isObjectLockedWithGlobalID

public abstract boolean isObjectLockedWithGlobalID( EOGlobalID globalID, EOEditingContext anEditingContext)

Returns true if the object identified by globalID is locked, false if it isn't. See the EODatabaseContext (EOAccess) class specification for more information on how this method works in concrete subclasses.

lockObjectWithGlobalID

public abstract void lockObjectWithGlobalID( EOGlobalID globalID, EOEditingContext anEditingContext)

Locks the object identified by globalID. See the EODatabaseContext (EOAccess) class specification for more information on how this method works in concrete subclasses.

objectsForSourceGlobalID

public abstract NSArray objectsForSourceGlobalID( EOGlobalID globalID, String relationshipName, EOEditingContext anEditingContext)

Returns the destination objects for a to-many relationship. This method is used by an array fault previously constructed using arrayFaultWithSourceGlobalID. globalID identifies the source object for the relationship (which doesn't necessarily exist in memory yet), and relationshipName is the name of the relationship. The object identified by globalID and the destination objects for the relationship all belong to anEditingContext.

See the EOEditingContext and EODatabaseContext (EOAccess) class specifications for more information on how this method works in concrete subclasses.

objectsWithFetchSpecification

public abstract NSArray objectsWithFetchSpecification( EOFetchSpecification aFetchSpecification, EOEditingContext anEditingContext)

Fetches objects from an external store according to the criteria specified by fetchSpecification and returns them in an array for inclusion in anEditingContext. If one of these objects is already present in memory, this method doesn't overwrite its values with the new values from the database. Throws an exception if an error occurs.

See the EOEditingContext and EODatabaseContext (EOAccess) class specifications for more information on how this method works in concrete subclasses.

refaultObject

public abstract void refaultObject( EOEnterpriseObject anObject, EOGlobalID globalID, EOEditingContext anEditingContext)

Turns anObject into a fault (an empty enterprise object), identified by globalID in anEditingContext. Objects that have been inserted but not saved, or that have been deleted, shouldn't be refaulted. When using com.webobjects.eocontrol, use this method with caution since refaulting an object doesn't remove the object snapshot from the undo stack.

saveChangesInEditingContext

public abstract void saveChangesInEditingContext(EOEditingContext anEditingContext)

Saves any changes in anEditingContext to the receiver's repository. Sends insertedObjects, deletedObjects, and updatedObjects messages to anEditingContext and applies the changes to the receiver's data repository as appropriate. For example, EODatabaseContext (EOAccess) implements this method to send operations to an EOAdaptor (EOAccess) for making the changes in a database.

Notifications

InvalidatedAllObjectsInStoreNotification

public static final String InvalidatedAllObjectsInStoreNotification

Posted whenever an EOObjectStore receives an invalidateAllObjects message. The notification contains:

Notification Object The EOObjectStore that received the invalidateAllObjects message.

Userinfo None

ObjectsChangedInStoreNotification

public static final String ObjectsChangedInStoreNotification

Posted whenever an EOObjectStore observes changes to its objects. The notification contains: Notification ObjectThe EOObjectStore that observed the changeuserInfoA dictionary containing the following keys and values:

Key Value

UpdatedKey An NSArray of EOGlobalIDs for objects whose properties have changed. A receiving EOEditingContext typically responds by refaulting its corresponding objects.

InsertedKey An NSArray of EOGlobalIDs for objects that have been inserted into the EOObjectStore.

DeletedKey An NSArray of EOGlobalIDs for objects that have been deleted from the EOObjectStore.

InvalidatedKey An NSArray of EOGlobalIDs for objects that have been turned into faults.

Notification Object	The EOObjectStore that received the invalidateAllObjects message.
Userinfo	None

Key	Value
UpdatedKey	An NSArray of EOGlobalIDs for objects whose properties have changed. A receiving EOEditingContext typically responds by refaulting its corresponding objects.
InsertedKey	An NSArray of EOGlobalIDs for objects that have been inserted into the EOObjectStore.
DeletedKey	An NSArray of EOGlobalIDs for objects that have been deleted from the EOObjectStore.
InvalidatedKey	An NSArray of EOGlobalIDs for objects that have been turned into faults.