In certain circumstances a “chicken and egg” problem may arise due to a cycle of REFERENCE properties when attempting to restore a node that has been removed.
For example, let us say that there is a node /A with child nodes /A/B and /A/C. Furthermore let there be REFERENCE properties /A/B/X /A/C/Y such that X refers to /A/C and Y refers to /A/B. Now assume that A, B and C are first checked-in (thus creating versions of all three nodes) and then B and C are deleted from the workspace.
In order to restore B or C the other must be restored first, since the reference properties X and Y both require the existence of the node to which they refer. This is the “chicken and egg” problem.
To deal with such situations the method
Workspace.restore(Version[] versions,
boolean removeExisting)
is provided. This method allows the client to simultaneously restore two or more versions. In this case the client must first find the Version objects (call them Va, Vb and Vc) that correspond to the versions of A, B and C that are to be restored and calling
ws.restore(new Version[]{Va, Vb, Vc}, removeExisting)
Notice that in order to restore B and C, the previous version of A must also be restored because its state contains the child links to B and C.
The removeExisting flag governs what happens in cases of UUID collision.
See 8.2.14.2 Workspace Versioning Methods, for more information.