Merging Changes in Working Copy Clones

In a three-tier application, the client and server exchange objects using a serialization mechanism such as RMI or CORBA. When the client changes an object and returns it to the server, you cannot register this serialized object into a unit of work directly. On the server, you must merge the serialized object with the original object in the session cache.

Using the unit of work methods listed in Table 102-2, you can merge a deserialized object into your session cache. Each method takes the serialized object as an argument and returns the original object.

Before doing so, you must ensure that the source object is in your session cache. Attempting to merge a deserialized object into a session cache that does not yet contain the object will result in a descriptor exception (see "200: ATTEMPT_TO_REGISTER_DEAD_INDIRECTION"). To avoid this, Oracle recommends that you first read the object instance that the deserialized object represents. If you are using a coordinated cache or your application is running in a cluster, the session you merge into may not yet contain your original object. By performing a read operation first, you guarantee that the object will be in the cache before you merge.

Table 102-2 Unit of Work Merge Methods

Method	Purpose	Used When
mergeClone	Merges the serialized object and all its privately owned parts (excluding non-private references from it to independent objects) into the working copy clone.	The client edits the object but not its relationships, or marks its independent relationships as transient.
mergeCloneWithReferences	Merges the serialized object and all references into the working copy clone.	The client edits the object and the targets of its relationships and has not marked any attributes as transient.
shallowMergeClone	Merges only serialized object changes to attributes mapped with direct mappings into the working copy clone.	The client edits only the object's direct attributes or has marked all of the object's relationships as transient.
deepMergeClone	Merges the serialized object and everything connected to it (the entire object tree where the serialized object is the root) into the working copy clone.	The client traverses all relationships of the objects and makes changes. Note: Use deepMergeClone with caution. If two different copies of an object are in the same tree, TopLink will merge one set of changes over the other. You should not have any transient attributes in any of your related objects.

Note that if your three-tier client is sufficiently complex, consider using the TopLink remote session (see "Remote Sessions"). It automatically handles merging and lets you use a unit of work on the client.

You can merge clones with both existing and new objects. Because clones do not appear in the cache and may not have a primary key, you can merge new objects only once within a unit of work. If you need to merge a new object more than once, call the unit of work setShouldNewObjectsBeCached method, and ensure that the object has a valid primary key; you can then register the object.

Example 102-8 shows one way to update the original object with the changes contained in the corresponding serialized object (rmiClone) received from a client.

Example 102-8 Merging a Serialized Object

update(Object original, Object rmiClone)
{
  original = uow.registerObject(original);
  uow.mergeCloneWithRefereneces(rmiClone);
  uow.commit();
}

For more information, see "Indirection, Serialization, and Detachment".