WebObjects 5.2

com.webobjects.eodistribution.client
Class EODistributedObjectStore

java.lang.Object
  |
  +--com.webobjects.eocontrol.EOObjectStore
        |
        +--com.webobjects.eodistribution.client.EODistributedObjectStore
All Implemented Interfaces:
NSDisposable, NSLocking

public class EODistributedObjectStore
extends EOObjectStore

An EODistributedObjectStore functions as the parent object store on the client side of Java Client applications. It handles interaction with the distribution layer's channel (an EODistributionChannel object), incorporating knowledge of that channel so it can forward messages it receives from the server to its editing contexts and forward messages from its editing contexts to the server. With the channel, it represents a single connection to the server, fetching and saving objects on behalf of one or more client-side editing contexts. In this regard, an EODistributedObjectStore acts like an EODatabaseContext on the server side. It differs from EODatabaseContext in that its editing contexts interact directly with it without the intervention of an object store coordinator.

EODistributedObjectStore provides several methods in addition to those defined by EOObjectStore. The invocation methods invokeRemoteMethod (two overloaded versions), invokeRemoteMethodWithKeyPath, and invokeStatelessRemoteMethodWithKeyPath allow you to send messages to any object on the server and receive responses from them. The methods classDescriptionForGlobalID and snapshotForSourceGlobalID return information related to enterprise objects in the distributed object store given an object's global ID.


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
EODistributedObjectStore(EODistributionChannel channel)
          Creates an EODistributedObjectStore instance initialized with a distribution channel.
 
Method Summary
 NSArray arrayFaultWithSourceGlobalID(EOGlobalID globalID, String relationshipName, EOEditingContext editingContext)
          Creates a to-many fault in the editing context editingContext and returns an array of the destination objects for the to-many relationship identified by relationshipName.
 EOClassDescription classDescriptionForGlobalID(EOGlobalID globalID)
          Returns the class description for the enterprise object identified by globalID.
 EODistributionChannel distributionChannel()
          Returns the distribution channel used by the distributed object store.
 void editingContextDidForgetObjectWithGlobalID(EOEditingContext editingContext, EOGlobalID globalID)
          Invoked if a child editing context forgot an object to clear out the snapshots.
 EOEnterpriseObject faultForGlobalID(EOGlobalID globalID, EOEditingContext editingContext)
          Creates a to-one fault for the enterprise object identified by the global ID globalID, registers it in the editing context editingContext, and returns the fault.
 EOEnterpriseObject faultForRawRow(NSDictionary row, String entityName, EOEditingContext editingContext)
          Creates a to-one fault for an enterprise object identified by the raw row row and the entity name entityName, registers it in the editing context editingContext, and returns the fault.
 void initializeObject(EOEnterpriseObject object, EOGlobalID globalID, EOEditingContext editingContext)
          Initializes the enterprise object object with its attributes and relationships using key-value coding.
 void invalidateAllObjects()
          Invoked to notify the receiver that all the properties and objects it caches are no longer valid and that they should be refaulted.
 void invalidateObjectsWithGlobalIDs(NSArray globalIDs)
          Invoked to notify the receiver that the objects in the object store with the global IDs globalIDs should no longer be considered valid and that they should be refaulted.
 Object invokeRemoteMethod(EOEditingContext editingContext, EOGlobalID globalID, String methodName, Class[] argumentTypes, Object[] arguments)
          Pushes the changes of the object graph in editingContext to the server-side editing context (but does not save the changes to the database) and invokes the method named methodName with the arguments passed remotely on the enterprise object identified by the global ID globalID.
 Object invokeRemoteMethod(EOEditingContext editingContext, EOGlobalID globalID, String methodName, Class[] argumentTypes, Object[] arguments, boolean shouldPush)
          Invokes the method named methodName with the arguments passed remotely on the enterprise object identified by the global ID globalID.
 Object invokeRemoteMethodWithKeyPath(EOEditingContext editingContext, String keyPath, String methodName, Class[] argumentTypes, Object[] arguments, boolean shouldPush)
          This method invokes a remote method on an object on the server side that can be specified with a key path (not just an enterprise object) relative to the invocation target of the server side EODistributionContext (for example "session").
 Object invokeStatelessRemoteMethodWithKeyPath(String keyPath, String methodName, Class[] argumentTypes, Object[] arguments)
          This method invokes a remote method on an object on the server side that can be specified with a key path (no enterprise object) relative to the invocation target of the server side EODistributionContext (for example "session").
 boolean isObjectLockedWithGlobalID(EOGlobalID globalID, EOEditingContext editingContext)
          Returns whether an object has been locked by the underlying data store.
 void lock()
          This method is used to protect access to the receiver from concurrent operations by multiple threads.
 void lockObjectWithGlobalID(EOGlobalID globalID, EOEditingContext editingContext)
          Places a persistent lock on the object in it's underlying data store.
 NSArray objectsForSourceGlobalID(EOGlobalID globalID, String relationshipName, EOEditingContext editingContext)
          Returns the destination objects for the to-many relationship identified by relationshipName.
 NSArray objectsWithFetchSpecification(EOFetchSpecification fetchSpecification, EOEditingContext editingContext)
          Fetches objects from the server according to the criteria specified by the fetch specification fetchSpecification and returns them in an array for inclusion in the editing context editingContext.
 void refaultObject(EOEnterpriseObject object, EOGlobalID globalID, EOEditingContext editingContext)
          Turns the enterprise object object back into a fault (an empty enterprise object, identified by the global ID globalID) in the editing context editingContext.
 void saveChangesInEditingContext(EOEditingContext editingContext)
          Requests the server to commit changes to the enterprise objects in the editing context editingContext.
 NSArray snapshotForSourceGlobalID(EOGlobalID globalID, String relationshipName)
          Returns an array of global IDs identifying the destination objects for the to-many relationship relationshipName having the source global ID globalID.
 void unlock()
          This method is used to protect access to the receiver from concurrent operations by multiple threads.
 
Methods inherited from class com.webobjects.eocontrol.EOObjectStore
dispose
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

EODistributedObjectStore

public EODistributedObjectStore(EODistributionChannel channel)
Creates an EODistributedObjectStore instance initialized with a distribution channel.
Parameters:
channel - the distribution channel used to communicate with the server
Method Detail

arrayFaultWithSourceGlobalID

public NSArray arrayFaultWithSourceGlobalID(EOGlobalID globalID,
                                            String relationshipName,
                                            EOEditingContext editingContext)
Creates a to-many fault in the editing context editingContext and returns an array of the destination objects for the to-many relationship identified by relationshipName. The globalID parameter identifies the source object for the relationship (which doesn't necessarily exist in memory yet).
Overrides:
arrayFaultWithSourceGlobalID in class EOObjectStore
Parameters:
globalID - the source object global ID
relationshipName - the to-many relationship name
editingContext - the editing context
Returns:
an array of destination objects

classDescriptionForGlobalID

public EOClassDescription classDescriptionForGlobalID(EOGlobalID globalID)
Returns the class description for the enterprise object identified by globalID.
Parameters:
globalID - the global ID of the enterprise object
Returns:
the class description of the enterprise object

distributionChannel

public EODistributionChannel distributionChannel()
Returns the distribution channel used by the distributed object store.
Returns:
the distribution channel

editingContextDidForgetObjectWithGlobalID

public void editingContextDidForgetObjectWithGlobalID(EOEditingContext editingContext,
                                                      EOGlobalID globalID)
Invoked if a child editing context forgot an object to clear out the snapshots.
Overrides:
editingContextDidForgetObjectWithGlobalID in class EOObjectStore
Parameters:
editingContext - the editing context which forgot the object
globalID - the global ID of the object forgotten by the editing context

faultForGlobalID

public EOEnterpriseObject faultForGlobalID(EOGlobalID globalID,
                                           EOEditingContext editingContext)
Creates a to-one fault for the enterprise object identified by the global ID globalID, registers it in the editing context editingContext, and returns the fault. This method could return an already existing object.
Overrides:
faultForGlobalID in class EOObjectStore
Parameters:
globalID - the global ID
editingContext - the editing context
Returns:
the fault object

faultForRawRow

public EOEnterpriseObject faultForRawRow(NSDictionary row,
                                         String entityName,
                                         EOEditingContext editingContext)
Creates a to-one fault for an enterprise object identified by the raw row row and the entity name entityName, registers it in the editing context editingContext, and returns the fault. This method may return an already existing object.
Overrides:
faultForRawRow in class EOObjectStore
Parameters:
row - the raw row
entityName - the entity name
editingContext - the editing context
Returns:
the fault object

initializeObject

public void initializeObject(EOEnterpriseObject object,
                             EOGlobalID globalID,
                             EOEditingContext editingContext)
Initializes the enterprise object object with its attributes and relationships using key-value coding. The properties of object are identified and accessed using the global ID globalID. For properties with NSKeyValueCoding.NullValue, null is substituted.
Overrides:
initializeObject in class EOObjectStore
Parameters:
object - the enterprise object to initialize
globalID - the global ID of the enterprise object
editingContext - the editing context of the enterprise object

invalidateAllObjects

public void invalidateAllObjects()
Invoked to notify the receiver that all the properties and objects it caches are no longer valid and that they should be refaulted. Any child object stores are also notified that the objects are no longer valid. Posts an InvalidatedAllObjectsInStoreNotification after removing snapshots from the object store.
Overrides:
invalidateAllObjects in class EOObjectStore
Following copied from class: com.webobjects.eocontrol.EOObjectStore
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 void invalidateObjectsWithGlobalIDs(NSArray globalIDs)
Invoked to notify the receiver that the objects in the object store with the global IDs globalIDs should no longer be considered valid and that they should be refaulted. This message is propagated to any underlying object store resulting in a refetch the next time the objects are accessed. Any child object stores are notified that the objects are no longer valid.
Overrides:
invalidateObjectsWithGlobalIDs in class EOObjectStore
Parameters:
globalIDs - the array of global IDs to invalidate

invokeRemoteMethod

public Object invokeRemoteMethod(EOEditingContext editingContext,
                                 EOGlobalID globalID,
                                 String methodName,
                                 Class[] argumentTypes,
                                 Object[] arguments)
Pushes the changes of the object graph in editingContext to the server-side editing context (but does not save the changes to the database) and invokes the method named methodName with the arguments passed remotely on the enterprise object identified by the global ID globalID. Note that if editingContext is a nested editing context, the changes have to be pushed through the parent editing context.
Overrides:
invokeRemoteMethod in class EOObjectStore
Parameters:
editingContext - the client editing editing of the enterprise object
globalID - the global ID of the enterprise object to invoke the remote method on
methodName - the name of the method to be invoked
argumentTypes - the types of the arguments of the method to be invoked
arguments - the arguments of the method to be invoked
Returns:
the return value of the remote method invocation
See Also:
invokeRemoteMethod(EOEditingContext, EOGlobalID, String, Class[], Object[], boolean), EODistributionContext, EODistributionContext.Delegate

invokeRemoteMethod

public Object invokeRemoteMethod(EOEditingContext editingContext,
                                 EOGlobalID globalID,
                                 String methodName,
                                 Class[] argumentTypes,
                                 Object[] arguments,
                                 boolean shouldPush)
Invokes the method named methodName with the arguments passed remotely on the enterprise object identified by the global ID globalID. If shouldPush is true, the changes of the object graph in editingContext are pushed to the server side editing context (but not saved to the database). Note that if editingContext is a nested editing context, the changes have to be pushed through to the parent editing context.
Parameters:
editingContext - the client editing context of the enterprise object
globalID - the global ID of the enterprise object to invoke the remote method on
methodName - the name of the method to be invoked
argumentTypes - the types of the arguments of the method to be invoked
arguments - the arguments of the method to be invoked
shouldPush - true if the changes in the editing context should be pushed to the server; false otherwise
Returns:
the return value of the remote method invocation
See Also:
invokeRemoteMethod(EOEditingContext, EOGlobalID, String, Class[], Object[]), EODistributionContext, EODistributionContext.Delegate

invokeRemoteMethodWithKeyPath

public Object invokeRemoteMethodWithKeyPath(EOEditingContext editingContext,
                                            String keyPath,
                                            String methodName,
                                            Class[] argumentTypes,
                                            Object[] arguments,
                                            boolean shouldPush)

This method invokes a remote method on an object on the server side that can be specified with a key path (not just an enterprise object) relative to the invocation target of the server side EODistributionContext (for example "session").

The keyPath argument has special semantics:

If an actual key path is specified, the EODistributionContext on the server blocks all invocations sent with this method unless methodName is prefixed with "clientSideRequest" or unless the EODistributionContext's delegate (on the server) implements the right delegate methods to explicitly allow the invocation. "clientSideRequest" methods can be invoked without special delegate methods on the server-side distribution context, on a remote method receiver registered with the distribution context or on the session of the distribution context's invocation target.

If enterprise objects are involved in the remote method invocation (either as argument or as return value), you need to specify an editing context. In that case you also have the choice to push the changes of the editing context's enterprise object graph to the server-side editing context.

Parameters:
editingContext - the editing context for enterprise objects involved in the remote method invocation
keyPath - the key path identifying the receiver of the method invocation
methodName - the name of the method to be invoked
argumentTypes - the types of the arguments of the method to be invoked
arguments - the arguments of the method to be invoked
shouldPush - true if the changes in the editing context should be pushed to the server; false otherwise
Returns:
the return value of the remote method invocation
See Also:
invokeStatelessRemoteMethodWithKeyPath(String, String, Class[], Object[]), EODistributionContext, EODistributionContext.Delegate

invokeStatelessRemoteMethodWithKeyPath

public Object invokeStatelessRemoteMethodWithKeyPath(String keyPath,
                                                     String methodName,
                                                     Class[] argumentTypes,
                                                     Object[] arguments)

This method invokes a remote method on an object on the server side that can be specified with a key path (no enterprise object) relative to the invocation target of the server side EODistributionContext (for example "session"). The arguments and return values of remote methods invoked through this method cannot be enterprise objects (but global IDs are okay). You can use this method, for example, to load resources from the server or to perform checks in background threads (as long as no enterprise objects are involved).

The keyPath argument has special semantics:

If an actual key path is specified, the EODistributionContext on the server blocks all invocations sent with this method unless methodName is prefixed with "clientSideRequest" or unless the EODistributionContext's delegate (on the server) implements the right delegate methods to explicitly allow the invocation. "clientSideRequest" methods can be invoked without special delegate methods on the server-side distribution context, on a remote method receiver registered with the distribution context or on the session of the distribution context's invocation target.

Parameters:
keyPath - the key path identifying the receiver of the method invocation
methodName - the name of the method to be invoked
argumentTypes - the types of the arguments of the method to be invoked
arguments - the arguments of the method to be invoked
Returns:
the return value of the remote method invocation
See Also:
invokeRemoteMethodWithKeyPath(EOEditingContext, String, String, Class[], Object[], boolean), EODistributionContext, EODistributionContext.Delegate

isObjectLockedWithGlobalID

public boolean isObjectLockedWithGlobalID(EOGlobalID globalID,
                                          EOEditingContext editingContext)
Returns whether an object has been locked by the underlying data store. Since EODistributedObjectStore does not support locking on the server, this method always returns false.
Overrides:
isObjectLockedWithGlobalID in class EOObjectStore
Parameters:
globalID - the global ID of the object to test
editingContext - the editing context of the object
Returns:
false since EODistributedObjectStore does not support locking

lock

public void lock()
Description copied from class: EOObjectStore
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.
Overrides:
lock in class EOObjectStore
Following copied from class: com.webobjects.eocontrol.EOObjectStore
See Also:
EOObjectStore.unlock()

lockObjectWithGlobalID

public void lockObjectWithGlobalID(EOGlobalID globalID,
                                   EOEditingContext editingContext)
Places a persistent lock on the object in it's underlying data store. Since EODistributedObjectStore does not support locking objects on the server, this method always raises an IllegalStateException.
Overrides:
lockObjectWithGlobalID in class EOObjectStore
Parameters:
globalID - the global ID of the object to lock
editingContext - the editing context of the object

objectsForSourceGlobalID

public NSArray objectsForSourceGlobalID(EOGlobalID globalID,
                                        String relationshipName,
                                        EOEditingContext editingContext)
Returns the destination objects for the to-many relationship identified by relationshipName. The source object for the relationship is identified by its global ID globalID. The source object and all destination objects for the relationship belong to the editing context editingContext. This method first looks to find the destination objects for the relationship in a client-side cache. If that cache is empty, it requests those objects from the server and updates the client-side cache with them.
Overrides:
objectsForSourceGlobalID in class EOObjectStore
Parameters:
globalID - the source global ID
relationshipName - the to-many relationship name
editingContext - the editing context of the enterprise object
Returns:
an array of destination objects

objectsWithFetchSpecification

public NSArray objectsWithFetchSpecification(EOFetchSpecification fetchSpecification,
                                             EOEditingContext editingContext)
Fetches objects from the server according to the criteria specified by the fetch specification fetchSpecification and returns them in an array for inclusion in the editing context editingContext. Updates the client-side caches with the fetched enterprise objects. Throws an exception if an error occurs.
Overrides:
objectsWithFetchSpecification in class EOObjectStore
Parameters:
fetchSpecification - the fetch specification describing the object to be fetched
editingContext - the editing context to fetch the objects into
Returns:
an array of the fetched enterprise objects

refaultObject

public void refaultObject(EOEnterpriseObject object,
                          EOGlobalID globalID,
                          EOEditingContext editingContext)
Turns the enterprise object object back into a fault (an empty enterprise object, identified by the global ID globalID) in the editing context editingContext. Objects that have been inserted but not saved, or that have been deleted, shouldn't be refaulted.
Overrides:
refaultObject in class EOObjectStore
Parameters:
object - the enterprise object to refault
globalID - the global ID of the enterprise object
editingContext - the editing context of the enterprise object

saveChangesInEditingContext

public void saveChangesInEditingContext(EOEditingContext editingContext)
Requests the server to commit changes to the enterprise objects in the editing context editingContext. This message is invoked by the editing context. The receiver calls back to the editing context to get the updated, deleted, and inserted objects to save and commits these changes in a single transaction. Raises an exception if any error occurs.
Overrides:
saveChangesInEditingContext in class EOObjectStore
Parameters:
editingContext - the editing context to save.

snapshotForSourceGlobalID

public NSArray snapshotForSourceGlobalID(EOGlobalID globalID,
                                         String relationshipName)
Returns an array of global IDs identifying the destination objects for the to-many relationship relationshipName having the source global ID globalID. Returns null if the object identified by the source global ID does not currently exist in the object store or if there is no relationship with the given name.
Parameters:
globalID - the source global ID
relationshipName - the to-many relationship name
Returns:
an array of global IDs representing the to-many relationship values

unlock

public void unlock()
Description copied from class: EOObjectStore
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.
Overrides:
unlock in class EOObjectStore
Following copied from class: com.webobjects.eocontrol.EOObjectStore
See Also:
EOObjectStore.lock()

Last updated Fri Feb 21 13:15:00 PST 2003.

Copyright © 2003 Apple Computer, Inc.