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 keyPath is a fully qualified key path (for example, "session"), the key path is followed starting from the invocation target of the EODistributionContext.
• If keyPath is an empty string, the method is invoked on the invocation target of the EODistributionContext directly (typically a subclass of WOJavaClientComponent).
• If keyPath is null, the method is invoked on one of the remote method receivers of the server side EODistributionContext.

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 keyPath is a fully qualified key path (for example, "session"), the key path is followed starting from the invocation target of the EODistributionContext.
• If keyPath is an empty string, the method is invoked on the invocation target of the EODistributionContext directly (typically a subclass of WOJavaClientComponent).
• If keyPath is null, the method is invoked on one of the remote method receivers of the server side EODistributionContext.

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()