com.webobjects.eocontrol
Class EOObjectStore

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

All Implemented Interfaces:

NSDisposable, NSLocking

Direct Known Subclasses:

EOCooperatingObjectStore, EODistributedObjectStore, EOEditingContext, EOObjectStoreCoordinator

public abstract class EOObjectStore

extends Object

implements NSDisposable, NSLocking

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" 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.

See Also:

EOCooperatingObjectStore, EOObjectStoreCoordinator, EODatabaseContext

Field Summary

static String	DeletedKey
static String	InsertedKey
static String	InvalidatedAllObjectsInStoreNotification
static String	InvalidatedKey
static String	ObjectsChangedInStoreNotification
static String	UpdatedKey

Fields inherited from interface com.webobjects.foundation.NSLocking

OneCentury, OneDay, OneHour, OneMinute, OneSecond, OneWeek, OneYear

Constructor Summary

EOObjectStore()

Method Summary

abstract NSArray	arrayFaultWithSourceGlobalID(EOGlobalID globalID, String relationshipName, EOEditingContext context) Implemented by subclasses to return the destination objects for a to-many relationship, whether as real instances or as faults (empty enterprise objects).
void	dispose() Invoked when the receiver should prepare itself for destruction.
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.
abstract EOEnterpriseObject	faultForGlobalID(EOGlobalID globalID, EOEditingContext context) If the receiver is context and the object associated with globalID is already registered in context, this method returns that object.
abstract EOEnterpriseObject	faultForRawRow(NSDictionary row, String entityName, EOEditingContext context) 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.
abstract void	initializeObject(EOEnterpriseObject object, EOGlobalID globalID, EOEditingContext context) Implemented by subclasses to set object's properties, as obtained for globalID.
abstract void	invalidateAllObjects() Discards the values of all objects held by the receiver and turns them into faults (empty enterprise objects).
abstract void	invalidateObjectsWithGlobalIDs(NSArray globalIDs) Signals that the objects identified by globalIDs should no longer be considered valid and that they should be turned into faults (empty enterprise objects).
Object	invokeRemoteMethod(EOEditingContext context, EOGlobalID gid, String methodName, Class[] argumentTypes, Object[] arguments) Invokes methodName on the enterprise object identified by gid in context, using arguments.
abstract boolean	isObjectLockedWithGlobalID(EOGlobalID globalID, EOEditingContext context) Returns true if the object identified by globalID is locked, false if it isn't.
abstract void	lock() This method is used to protect access to the receiver from concurrent operations by multiple threads.
abstract void	lockObjectWithGlobalID(EOGlobalID globalID, EOEditingContext context) Locks the object identified by globalID.
abstract NSArray	objectsForSourceGlobalID(EOGlobalID globalID, String relationshipName, EOEditingContext context) Returns the destination objects for a to-many relationship.
abstract NSArray	objectsWithFetchSpecification(EOFetchSpecification fetchSpecification, EOEditingContext context) Fetches objects from an external store according to the criteria specified by fetchSpecification and returns them in an array for inclusion in context.
abstract void	refaultObject(EOEnterpriseObject object, EOGlobalID globalID, EOEditingContext context) Turns object into a fault (an empty enterprise object), identified by globalID in context.
abstract void	saveChangesInEditingContext(EOEditingContext context) Saves any changes in context to the receiver's repository.
abstract void	unlock() This method is used to protect access to the receiver from concurrent operations by multiple threads.

Methods inherited from class java.lang.Object

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

Field Detail

DeletedKey

public static final String DeletedKey

InsertedKey

public static final String InsertedKey

InvalidatedAllObjectsInStoreNotification

public static final String InvalidatedAllObjectsInStoreNotification

InvalidatedKey

public static final String InvalidatedKey

ObjectsChangedInStoreNotification

public static final String ObjectsChangedInStoreNotification

UpdatedKey

public static final String UpdatedKey

Constructor Detail

EOObjectStore

public EOObjectStore()

Method Detail

arrayFaultWithSourceGlobalID

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

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 context. 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.

Parameters:

globalID - EOGlobalID of a source object with a to-many relationship

relationshipName - name of the to-many relationship from which to generate the array of destination objects

context - the EOEditingContext that will contain the source and destination objects

Returns:

the destination objects for the to-many relationship named relationshipName from the source object identified by globalID

See Also:

faultForGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), EOEditingContext.arrayFaultWithSourceGlobalID(com.webobjects.eocontrol.EOGlobalID, java.lang.String, com.webobjects.eocontrol.EOEditingContext), EODatabaseContext.arrayFaultWithSourceGlobalID(com.webobjects.eocontrol.EOGlobalID, java.lang.String, com.webobjects.eocontrol.EOEditingContext)

dispose

public void dispose()

Description copied from interface: NSDisposable

Invoked when the receiver should prepare itself for destruction. Implementations of this method should break connections that other objects have to the receiver, including unregistering for notifications, resigning as other objects' delegates, release locks and system resources, close files, and any other clean up operations.

Specified by:

dispose in interface NSDisposable

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.

Parameters:

context - the EOEditingContext that has stopped storing data about the object identified by gid

gid - the EOGlobalID of the object that was forgotten by context

See Also:

EOEditingContext.editingContextDidForgetObjectWithGlobalID(com.webobjects.eocontrol.EOEditingContext, com.webobjects.eocontrol.EOGlobalID), EODatabaseContext.editingContextDidForgetObjectWithGlobalID(com.webobjects.eocontrol.EOEditingContext, com.webobjects.eocontrol.EOGlobalID)

faultForGlobalID

public abstract EOEnterpriseObject faultForGlobalID(EOGlobalID globalID,
                                                    EOEditingContext context)

If the receiver is context and the object associated with globalID is already registered in context, this method returns that object. Otherwise it creates a to-one fault, registers it in context, and returns the fault. This method is always directed first at context, 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 method. 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.

Parameters:

globalID - the EOGlobalID of the object to return

context - the EOEditingContext that holds the object identified by globalID

Returns:

the object identified by globalID, held in context

See Also:

EOEditingContext.faultForGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), EODatabaseContext.faultForGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), arrayFaultWithSourceGlobalID(com.webobjects.eocontrol.EOGlobalID, java.lang.String, com.webobjects.eocontrol.EOEditingContext), EOEditingContext.recordObject(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.eocontrol.EOGlobalID), EOFaultHandler

faultForRawRow

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

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.

Parameters:

row - dictionary containing at least the the primary key of the corresponding row

entityName - the name of the entity to create an enterprise object from

context - the EOEditingContext that either contains the object from row, or will contain the object's fault

Returns:

the EOEnterpriseObject described by row

See Also:

EOEditingContext.faultForRawRow(com.webobjects.foundation.NSDictionary, java.lang.String, com.webobjects.eocontrol.EOEditingContext), EODatabaseContext.faultForRawRow(com.webobjects.foundation.NSDictionary, java.lang.String, com.webobjects.eocontrol.EOEditingContext)

initializeObject

public abstract void initializeObject(EOEnterpriseObject object,
                                      EOGlobalID globalID,
                                      EOEditingContext context)

Implemented by subclasses to set object's properties, as obtained for globalID. This method is typically invoked after object 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.

Parameters:

object - the EOEnterpriseObject to set the properties of

globalID - the EOGlobalID that identifies the set of properties to set in object

context - the EOEditingContext that contains the object

See Also:

EOEnterpriseObject.awakeFromInsertion(com.webobjects.eocontrol.EOEditingContext), EOEnterpriseObject.awakeFromFetch(com.webobjects.eocontrol.EOEditingContext), EOEditingContext.initializeObject(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext)

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.

See Also:

invalidateObjectsWithGlobalIDs(com.webobjects.foundation.NSArray), refaultObject(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), EOEditingContext.invalidateAllObjects(), EODatabaseContext.invalidateAllObjects()

invalidateObjectsWithGlobalIDs

public abstract void invalidateObjectsWithGlobalIDs(NSArray globalIDs)

Signals that the objects identified by 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.

Parameters:

globalIDs - array of EOGlobalIDs that identify objects to invalidate

See Also:

invalidateAllObjects(), refaultObject(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), EOEditingContext.invalidateObjectsWithGlobalIDs(com.webobjects.foundation.NSArray), EODatabaseContext.invalidateObjectsWithGlobalIDs(com.webobjects.foundation.NSArray)

invokeRemoteMethod

public Object invokeRemoteMethod(EOEditingContext context,
                                 EOGlobalID gid,
                                 String methodName,
                                 Class[] argumentTypes,
                                 Object[] arguments)

Invokes methodName on the enterprise object identified by gid in context, 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.

Parameters:

context - the container of the enterprise object to invoke the method on

gid - the EOGlobalID of the enterprise object to invoke the method on

methodName - the name of the method to invoke

argumentTypes - language array of Class objects defining the types of arguments to methodName

arguments - language array of objects to pass to methodName as arguments

Returns:

the result of the remote method invocation

isObjectLockedWithGlobalID

public abstract boolean isObjectLockedWithGlobalID(EOGlobalID globalID,
                                                   EOEditingContext context)

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.

Parameters:

globalID - the EOGlobalID of the object to test

editingContext - EOEditingContext to locate the object with globalID in

Returns:

true if the object identified by globalID in context is locked, false otherwise

See Also:

EOEditingContext.isObjectLockedWithGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), EODatabaseContext.isObjectLockedWithGlobalID(com.webobjects.eocontrol.EOGlobalID)

lock

public abstract void lock()

This method is used to protect access to the receiver from concurrent operations by multiple threads. Most EOObjectStores can only service one thread at a time (i.e. they are not reentreant) so properly locking them ensures correct concurrent behavior (i.e. threads take turns) Applications which make direct use of an EOObjectStore should lock and unlock it as appropriate. EOObjectStores are expected to lock and unlock any additional resources they need as appropriate. Specifically, so long as an object store is properly locked and unlocked by its clients, any indirect locks or resoruces the EOObjectStore requires to fulfill its client's requests are expected to be managed by the EOObjectStore, not its client. Do not confuse this with any methods which work with the database locking mechanism.

Specified by:

lock in interface NSLocking

See Also:

unlock()

lockObjectWithGlobalID

public abstract void lockObjectWithGlobalID(EOGlobalID globalID,
                                            EOEditingContext context)

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

Parameters:

globalID - the EOGlobalID of the object to lock

context - the EOEditingContext that holds the object to lock

See Also:

EOEditingContext.lockObjectWithGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext), EODatabaseContext.lockObjectWithGlobalID(com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext)

objectsForSourceGlobalID

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

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 context. See the EOEditingContext and EODatabaseContext (EOAccess) class specifications for more information on how this method works in concrete subclasses.

Parameters:

globalID - the EOGlobalID of the source object

relationshipName - the name of the to-many relationship

context - the EOEditingContext that contains the source and destination objects

Returns:

the destination objects for the to-many relationship

See Also:

EOEditingContext.objectsForSourceGlobalID(com.webobjects.eocontrol.EOGlobalID, java.lang.String, com.webobjects.eocontrol.EOEditingContext), EODatabaseContext.objectsForSourceGlobalID(com.webobjects.eocontrol.EOGlobalID, java.lang.String, com.webobjects.eocontrol.EOEditingContext)

objectsWithFetchSpecification

public abstract NSArray objectsWithFetchSpecification(EOFetchSpecification fetchSpecification,
                                                      EOEditingContext context)

Fetches objects from an external store according to the criteria specified by fetchSpecification and returns them in an array for inclusion in context. 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.

Parameters:

fetchSpecification - the EOFetchSpecification that speicifies which objects to fetch

context - container of objects fetched using fetchSpecification

Returns:

array of EOEnterpriseObjects fetched

See Also:

EOEditingContext.objectsWithFetchSpecification(com.webobjects.eocontrol.EOFetchSpecification, com.webobjects.eocontrol.EOEditingContext), EODatabaseContext.objectsWithFetchSpecification(com.webobjects.eocontrol.EOFetchSpecification, com.webobjects.eocontrol.EOEditingContext)

refaultObject

public abstract void refaultObject(EOEnterpriseObject object,
                                   EOGlobalID globalID,
                                   EOEditingContext context)

Turns object into a fault (an empty enterprise object), identified by globalID in context. 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.

Parameters:

object - the object to turn into a fault

globalID - the EOGlobalID identifier for the resulting fault object

context - contains object and the resulting fault for object

See Also:

EOEditingContext.refaultObject(com.webobjects.eocontrol.EOEnterpriseObject), EODatabaseContext.refaultObject(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.eocontrol.EOGlobalID, com.webobjects.eocontrol.EOEditingContext)

saveChangesInEditingContext

public abstract void saveChangesInEditingContext(EOEditingContext context)

Saves any changes in context to the receiver's repository. Sends insertedObjects, deletedObjects, and updatedObjects messages to context 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.

Parameters:

context - EOEditingContext that will have its object graph changes saved

See Also:

EOEditingContext.saveChangesInEditingContext(com.webobjects.eocontrol.EOEditingContext), EODatabaseContext.saveChangesInEditingContext(com.webobjects.eocontrol.EOEditingContext), EOAdaptor

unlock

public abstract void unlock()

This method is used to protect access to the receiver from concurrent operations by multiple threads. Most EOObjectStores can only service one thread at a time (i.e. they are not reentreant) so properly unlocking them ensures another thread can utilize the object store (i.e. prevent deadlock) Applications which make direct use of an EOObjectStore should lock and unlock it as appropriate. EOObjectStores are expected to lock and unlock any additional resources they need as appropriate. Specifically, so long as an object store is properly locked and unlocked by its clients, any indirect locks or resoruces the EOObjectStore requires to fulfill its client's requests are expected to be managed by the EOObjectStore, not its client. Do not confuse this with any methods which work with the database locking mechanism.

Specified by:

unlock in interface NSLocking

See Also:

lock()