WebObjects 5.4.2

com.webobjects.eocontrol
Class EOObjectStore

java.lang.Object
  extended by 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:

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 editingContext)
          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.
 void setUserInfo(Map aDictionary)
          Sets a dictionary in the WOMessage object that can contain, as a convenience, any kind of information related to the current response.
 void setUserInfoForKey(Object value, String key)
          Setes the value for key in the infor user dictionary
abstract  void unlock()
          This method is used to protect access to the receiver from concurrent operations by multiple threads.
 NSDictionary userInfo()
          Return the userInfo dictionary.
 Object userInfoForKey(String key)
          Return the value of the key in the userInfo dictionary
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ObjectsChangedInStoreNotification

public static final String ObjectsChangedInStoreNotification
See Also:
Constant Field Values

InvalidatedAllObjectsInStoreNotification

public static final String InvalidatedAllObjectsInStoreNotification
See Also:
Constant Field Values

InsertedKey

public static final String InsertedKey
See Also:
Constant Field Values

UpdatedKey

public static final String UpdatedKey
See Also:
Constant Field Values

DeletedKey

public static final String DeletedKey
See Also:
Constant Field Values

InvalidatedKey

public static final String InvalidatedKey
See Also:
Constant Field Values
Constructor Detail

EOObjectStore

public EOObjectStore()
Method Detail

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), EOObjectStore.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)

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:
EOObjectStore.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)

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)

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)

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)

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

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)

isObjectLockedWithGlobalID

public abstract boolean isObjectLockedWithGlobalID(EOGlobalID globalID,
                                                   EOEditingContext editingContext)
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)

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)

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:
EOObjectStore.invalidateObjectsWithGlobalIDs(com.webobjects.foundation.NSArray), EOObjectStore.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:
EOObjectStore.invalidateAllObjects(), EOObjectStore.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

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:
EOObjectStore.unlock()

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:
EOObjectStore.lock()

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

setUserInfo

public void setUserInfo(Map aDictionary)
Sets a dictionary in the WOMessage object that can contain, as a convenience, any kind of information related to the current response. Objects further down the appendToResponse method chain can retrieve this information by invoking userInfo.

This method unconditionally makes an immutable copy of aDictionary. This can be a problem if changes made elsewhere to the dictionary's contents need to be reflected in the userInfo dictionary.

If you need to pass in a mutable dictionary that can be changed by other objects down the chain, wrap the mutable dictionary in a read-only (immutable) dictionary and pass the immutable dictionary as the argument to this method. Be extremely careful doing this if your application is multi-threaded and the userInfo data may be accessed by multiple threads.

Parameters:
aDictionary - a dictionary that can contain any kind of information related to the current object store
Since:
5.4
See Also:
EOObjectStore.userInfo(), EOObjectStore.userInfoForKey(String key), EOObjectStore.setUserInfoForKey(Object value, String key)

userInfo

public NSDictionary userInfo()
Return the userInfo dictionary. An object further upstream in the appendToResponse method chain can set this dictionary in the WOMessage object as a way to pass information to other objects.

Returns:
a dictionary that can contain any kind of information related to the current object store
Since:
5.4
See Also:
#setUserInfo(Map aDictionary), EOObjectStore.userInfoForKey(String key), EOObjectStore.setUserInfoForKey(Object value, String key)

userInfoForKey

public Object userInfoForKey(String key)
Return the value of the key in the userInfo dictionary

Parameters:
key - to search for
Returns:
value for key
Since:
5.4
See Also:
EOObjectStore.userInfo(), #setUserInfo(Map aDictionary), EOObjectStore.setUserInfoForKey(Object value, String key)

setUserInfoForKey

public void setUserInfoForKey(Object value,
                              String key)
Setes the value for key in the infor user dictionary

Parameters:
value - to set
key - to set
Since:
5.4
See Also:
EOObjectStore.userInfo(), #setUserInfo(Map aDictionary), EOObjectStore.userInfoForKey(String key)

Last updated June 2008

Copyright © 2000-2008 Apple Inc.