EODistributedObjectStore

Inherits from:
com.webobjects.eocontrol.EOObjectStore

Package:
com.webobjects.eodistribution.client

Class Description

An EODistributedObjectStore functions as an object store on the Java client. 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; 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) and invokeRemoteMethodWithKeyPath 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.

Method Types

Initializing objects

initializeObject

Getting objects

objectsWithFetchSpecification
objectsForSourceGlobalID

Getting faults

faultForGlobalID
arrayFaultWithSourceGlobalID
refaultObject

Saving changes to objects

saveChangesInEditingContext

Invalidating objects

invalidateAllObjects
invalidateObjectsWithGlobalIDs

Invoking methods on the server

invokeRemoteMethod
invokeRemoteMethodWithKeyPath

Getting object data via global IDs

classDescriptionForGlobalID
snapshotForSourceGlobalID

Constructors

EODistributedObjectStore

public EODistributedObjectStore(EODistributionChannel aDistributionChannel)

Returns an EODistributedObjectStore instance initialized with a distribution channel.

Instance Methods

arrayFaultWithSourceGlobalID

public NSArray arrayFaultWithSourceGlobalID( com.webobjects.eocontrol.EOGlobalID globalID, String relationshipName, com.webobjects.eocontrol.EOEditingContext editingContext)

Creates a to-many fault in the editing context editingContext and returns the destination objects for the to-many relationship identified by relationshipName; globalID identifies the source object for the relationship (which doesn't necessarily exist in memory yet).

See Also: faultForGlobalID, refaultObject

classDescriptionForGlobalID

public com.webobjects.eocontrol.EOClassDescription classDescriptionForGlobalID(com.webobjects.eocontrol.EOGlobalID globalID)

Returns the class description for the enterprise object identified by globalID.

See Also: snapshotForSourceGlobalID

faultForGlobalID

public com.webobjects.eocontrol.EOEnterpriseObject faultForGlobalID( com.webobjects.eocontrol.EOGlobalID globalID, com.webobjects.eocontrol.EOEditingContext editingContext)

Creates a to-one fault from the enterprise object identified by globalID, registers it in editingContext, and returns the fault. This method could return an already existing object.

initializeObject

public void initializeObject( com.webobjects.eocontrol.EOEnterpriseObject anObject, com.webobjects.eocontrol.EOGlobalID globalID, com.webobjects.eocontrol.EOEditingContext editingContext)

Initializes the enterprise object anObject with its attributes and relationships using key-value coding; the properties of anObject are identified and accessed using the global ID globalID. For properties with EONullValues, a null is substituted.

See Also: classDescriptionForGlobalID

invalidateAllObjects

public void invalidateAllObjects()

Invoked to notify the receiver that all the properties 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 InvalidatedAllObjectsInStoreNotification after removing objects from the object store.

See Also: invalidateObjectsWithGlobalIDs

invalidateObjectsWithGlobalIDs

public void invalidateObjectsWithGlobalIDs(NSArray gidArray)

Invoked to notify the receiver that all of the objects identified by the global IDs in gidArray are no longer valid. Any child object stores are also notified that the specified objects are no longer valid. After invalidating the objects, this method posts ObjectsChangedInStoreNotification.

invokeRemoteMethod

public Object invokeRemoteMethod( com.webobjects.eocontrol.EOEditingContext editingContext, com.webobjects.eocontrol.EOGlobalID globalID, String methodName, Class[] anArray Object[] arguments)

public Object invokeRemoteMethod( com.webobjects.eocontrol.EOEditingContext editingContext, com.webobjects.eocontrol.EOGlobalID globalID, String methodName, Object[] arguments, Class[] anArray boolean shouldPush)

Invokes the method identified by methodName on the server-side enterprise object identified by the editing context editingContext and the EOGlobalID globalID. The result of the invocation is returned. The four-argument method (and the five-argument method, if shouldPush is true) pushes all changes pending on the client to the server before sending the invocation; this ensures that the states of the server and client are synchronized before the method is executed. If for performance or other reasons you do not want to push pending changes to the server, use the second method with shouldPush set to false. Note that the method without the shouldPush argument typically originates with one of the receiver's editing contexts.

The EODistributionContext on the server by default refuses the remote invocation unless methodName is prefixed with "clientSideRequest" or unless its delegate (usually the session object) implements the distributionContextShouldAllowInvocation method to return true. This mechanism exists to provide security on the server.

invokeRemoteMethodWithKeyPath

public Object invokeRemoteMethodWithKeyPath( com.webobjects.eocontrol.EOEditingContext editingContext, String keyPath, String methodName, Class[] anArray Object[] arguments, boolean shouldPush)

This method is similar to invokeRemoteMethod except for two things. The receiver of the invocation can be any object (not just an enterprise object) that can be specified with a key path (keyPath). The keyPath argument has special semantics:

If keyPath is a fully qualified key path (for example, "session.editingContext") the key path is followed starting from the WOComponent that is the invocation target of the EODistributionContext.
If keyPath is an empty string, the method is invoked on the WOComponent that is the invocation target of the EODistributionContext (typically a subclass of WOJavaClientApplet).
If keyPath is null, the method is invoked on 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 distributionContextShouldAllowInvocation and distributionContextShouldFetchObjectsWithFetchSpecification. For security reasons, the delegate must authorize the invocation and the key path in these methods.

objectsForSourceGlobalID

public NSArray objectsForSourceGlobalID( com.webobjects.eocontrol.EOGlobalID globalID, String relationshipName, com.webobjects.eocontrol.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 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 the server to send it those objects and updates the client-side cache with them.

objectsWithFetchSpecification

public NSArray objectsWithFetchSpecification( com.webobjects.eocontrol.EOFetchSpecification fetchSpecification, com.webobjects.eocontrol.EOEditingContext editingContext)

Fetches objects from the server according to the criteria specified by fetchSpecification and returns them in an array for inclusion in editingContext. Updates the client-side caches with the fetched enterprise objects. Throws an exception if an error occurs.

refaultObject

public void refaultObject( com.webobjects.eocontrol.EOEnterpriseObject anObject, com.webobjects.eocontrol.EOGlobalID globalID, com.webobjects.eocontrol.EOEditingContext editingContext)

Turns enterprise object anObject back into a fault (an empty enterprise object, identified by globalID in editingContext. Objects that have been inserted but not saved, or that have been deleted, shouldn't be refaulted.

saveChangesInEditingContext

public void saveChangesInEditingContext(com.webobjects.eocontrol.EOEditingContext editingContext)

Requests the server to commit changes to the enterprise objects in editingContext; this message is invoked by the editing context (editingContext). 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.

snapshotForSourceGlobalID

public NSArray snapshotForSourceGlobalID( com.webobjects.eocontrol.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 of 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.

See Also: classDescriptionForGlobalID

Notifications

EOGlobalID's GlobalIDChangedNotification is posted when the global ID of an object in the store changes. See the EOGlobalID documentation for more information.

InvalidatedAllObjectsInStoreNotification

This notification is posted when all objects in the object store are invalidated; see invalidateAllObjects.

Notification Object this

userInfo Dictionary None.

GlobalIDChangedNotification

This EOGlobalID notification is posted when the global ID of an object in the store changes.

Notification Object this

userInfo Dictionary Use the old global ID as the key to find the new global ID.

ObjectsChangedInStoreNotification

This notification is posted on when specific objects in the object store are inserted, deleted, updated, or invalidated. This can happen as a result of an update from the server.

Notification Object this

userInfo Dictionary The global IDs of inserted, deleted, updated, and invalidated objects, accessible with EOObjectStore's (respectively) InsertedKey, DeletedKey, UpdatedKey, and InvalidatedKey.

Notification Object	`this`
userInfo Dictionary	Use the old global ID as the key to find the new global ID.