Copy this instance and all objects reachable from it via the specified cascade into the specified destination transaction.
This is a more general method; see
#cascadeCopyIn and
#cascadeCopyOutfor more common and specific use cases.
This method finds and copies all objects reachable from this object based on
io.permazen.annotation.JField#cascades and
io.permazen.annotation.JField#inverseCascades annotation properties on
reference fields: a reference field is traversed in the forward or inverse direction if
cascadeName is
specified in the corresponding annotation property. See
io.permazen.annotation.JField for details.
The
recursionLimit parameter can be used to limit the maximum distance of any copied object,
measured in the number of reference field "hops" from this object.
This instance will first be
#upgradeed if necessary. If any copied object already exists in
dest,
it will have its schema version updated first, if necessary, then be overwritten.
Any
io.permazen.annotation.OnCreate,
io.permazen.annotation.OnCreate,
and
io.permazen.annotation.OnCreate methods will be notified accordingly as usual (in
dest);
however, for
io.permazen.annotation.OnCreate and
io.permazen.annotation.OnCreate, the annotation must have
snapshotTransactions = trueif
dest is a
SnapshotJTransaction.
The two transactions must be compatible in that for any schema versions encountered, those schema versions
must be identical in both transactions.
Circular references are handled properly: if an object is encountered more than once, it is not copied again.
The
copyState tracks which objects have already been copied and traversed.
For a "fresh" copy operation, pass a newly created
CopyState; for a copy operation that is a continuation
of a previous copy, reuse the previous
copyState. The
CopyState may also be configured to remap object ID's.
Warning: if two threads attempt to copy objects between the same two transactions at the same time
but in opposite directions, deadlock could result.