The Details of Merge Behavior

You can predict how the property values and collections in a successor version will change. MergeVersion modifies one object version, the successor, by combining its property values and collections with those of another version, the predecessor. MergeVersion compares the property values and collections of the predecessor version and the successor version to a third version, called the basis version.

You invoke MergeVersion on the successor version of the merge; you pass a reference to the predecessor as an input parameter. You also pass an indication of which version is to be considered the primary version. The primary version is the version whose member values are given priority when there are merge conflicts between the two versions. For each property, MergeVersion uses this rule to resolve merge conflicts:

• If the primary version differs from the basis version, Repository uses the property value from the primary version.
  
  
• If only the secondary version differs from the basis version, Repository uses the property value from the secondary version.
  
  
• If neither version differs from the basis version, Repository leaves the property value in the current version unchanged.

How MergeVersion Handles Origin Collections with COLLECTION_MERGEWHOLE Flag Set

For each origin collection type whose COLLECTION_MERGEWHOLE flag is set, MergeVersion uses this rule:

• If the primary version's collection differs (see "Comparing Collections") from the basis version's collection, Repository uses the collection from the primary version.
  
  
• If only the secondary version's collection differs from the basis version's, Repository uses the collection from the secondary version.
  
  
• If neither version differs from the basis version, Repository leaves the collection in the current version unchanged.

How MergeVersion Handles Origin Collections with COLLECTION_MERGEWHOLE Flag Not Set

For each origin collection type whose COLLECTION_MERGEWHOLE flag is not set, MergeVersion combines the items in the two collections as follows:

1. MergeVersion includes in the resulting collection each item in the basis version not changed in or deleted from either the primary version or secondary version. (See Comparing Versioned Relationships.)
   
   
2. MergeVersion includes in the resulting collection each item in the primary version's collection that differs from the basis version.
   
   
3. MergeVersion includes in the resulting collection each item in the secondary version's collection that differs from the basis version, provided the corresponding items in the primary version and basis version do not differ from each other.

Note   The resulting collection can exclude some items found in the basis object version's collection. For example, if the primary version's collection excludes the item, the resulting collection will exclude the item. Similarly, if the primary version's collection includes an item that is identical to an item in the basis version's collection, but the secondary object version excludes the item, the resulting collection will exclude the item.

For some examples of Merge behavior, see Examples of Merging Versions.

Calculating the Basis Version

When you invoke the MergeVersion method of the IRepositoryObjectVersion interface, Repository uses the version graph. The MergeVersion method compares each object version to be merged to a basis version of the same object. The basis version of the two to-be-merged object versions is the most recently created object version that is on the creation path of both the primary object version and the secondary object version of the merge. The creation path of an object version is a path through the version graph leading from the object version directly to Version 1 of the object. Each step of the path leads from an object version to its predecessor creation version.

You can easily follow an object version's creation path backward from it to Version 1 by following the solid arrows in reverse. For example, the version graph in the following figure shows that the creation path of Version 11 goes through these other versions: 9, 5, 4, 2, and 1.

Comparing Collections

As it works, the MergeVersion method must compare collections to each other. (It compares each collection in the basis version to its corresponding collection in the primary version and in the secondary version.) MergeVersion considers two collections to be different if either of the following is true:

• One collection contains different objects from the other collection.
  
  
• A corresponding pair of items from the two collections differ from each other. (See "Comparing Versioned Relationships.")

Comparing Versioned Relationships

The MergeVersion method compares each collection of the basis version of an object to the corresponding collections of the primary version and of the secondary version. As part of these comparisons, the method must compare corresponding items – versioned relationships – of these collections. An item from the basis object version's collection corresponds to an item in the primary or secondary object version's collection if the two items use the same target object. Even if two items correspond, however, they can still differ in important ways. Repository considers two versioned relationships to differ if any of the following is true:

• The collection type is a sequenced collection and the two items have different sequence numbers.
  
  
• The collection type is a naming collection and the two items have different names.
  
  
• The two items refer to different versions of the target object.
  
  
• The two items use a different version of the target object as pinned version.
  
  
• One item has a pinned target object version and the other does not.

For example, the following figure shows two items that differ in one respect only — the top item refers to Versions 1 and 3. The corresponding item of the second collection refers to Versions 3 and 5.