As mentioned, when a merge test on a node N fails, this indicates that the two base versions V and V' are on separate branches of the version graph. Consequently, determining the result of the merge is not simply a matter of determining which version is the successor of the other in terms of version history. Instead, the content (that is, the subtree) of N' must be merged into the content of N according to some domain specific criteria which must be performed at the application level, for example, through a merge tool provided to the user.
The jcr:mergeFailed property is used to tag nodes that fail the merge test so that an application can find them and deal appropriately with them. The jcr:mergeFailed property is multi-valued so that information about merge failures is not lost if more than one successive merge is attempted before being dealt with by the application.
In the above example, after the content of N' is merged into N, the application will want to also merge the two branches of the version graph. This is done by calling N.doneMerge(V') where V' is retrieved by following the reference stored in the jcr:mergeFailed property of N. This has the effect of moving the reference-to-V' from the jcr:mergeFailed property of N to its jcr:predecessors property.
If, on the other hand, the application chooses not to join the two branches, then cancelMerge(V') is performed. This has the effect of removing the reference to V' from the jcr:mergeFailed property of N without adding it to jcr:predecessors.
Once the last reference in jcr:mergeFailed has been either moved to jcr:predecessors (with doneMerge) or just removed from jcr:mergeFailed (with cancelMerge) the jcr:mergeFailed property is automatically removed, thus enabling this node to be checked-in, creating a new version (note that before the jcr:mergeFailed is removed, its OnParentVersion setting of ABORT prevents check in). This new version will have a predecessor connection to each version for which doneMerge was called, thus joining those branches of the version graph.
See 8.2.14 Versioning API.