APITransfer

Transfer

		new Transfer(hash, sourceStore, destinationStore, keyPair, done);

		class Done implements Transfer.Done {
			public void onTransferDone() {
				// The transfer completed successfully.
			}

			public void onTransferNotFound(@NonNull Hash hash) {
				// At least one object was not found on the source store.
				// The transfer was cancelled.
			}

			public void onTransferFailed(@NonNull Store store, @NonNull String error) {
				// A store error occurred.
				// The transfer was cancelled.
			}
		}
	
		var transfer = keyPair.transfer(hash, sourceStore, destinationStore);

		transfer.onDone = function() {
			// The transfer completed successfully.
		};

		transfer.onNotFound = function(hash) {
			// At least one object was not found on the source store.
			// The transfer was cancelled.
		};

		transfer.onStoreError = function(store, error) {
			// A store error occurred.
			// The transfer was cancelled.
		};
	
		my ($missing, $store, $error) = $keyPair->transfer($hash, $sourceStore, $destinationStore);

		if (defined $error) {
			# A store error occurred on $store.
			# The transfer was cancelled.
		} elsif (defined $missing) {
			# At least one object was not found on the source store.
			# The transfer was cancelled.
		} else {
			# The transfer completed successfully.
		}
	

Transfers an object tree from one store to the other using the following algorithm:

  1. Book the object on the destination store. If the object exists, the transfer is complete.
  2. Get the object from the source store, and keep it in memory.
  3. Recursively transfer all children and their subtree, one by one.
  4. Put the object onto the destination store.

To reduce the memory footprint, objects are copied serially, and only one store operation is taking place at at time. The tree is traversed in depth-first order.

If a store error occurs, the transfer stops immediately.

If an object is not found on the source store (and could not be booked on the destination store), the transfer stops immediately.

Transfers assume that the destination store uses complete subtrees. If an object is found on the destination store, it is assumed that all its children are available as well. New objects are put in child-first order.

When the same subtree is transferred multiple times in parallel, the corresponding store operations are pooled and only executed once.