kotlin-stdlib / kotlin.io.path / java.nio.file.Path / copyToRecursively

copyToRecursively

JVM
JRE7
1.8
@ExperimentalPathApi fun Path.copyToRecursively(
    target: Path,
    onError: (source: Path, target: Path, exception: Exception) -> OnErrorResult = { _, _, exception -> throw exception },
    followLinks: Boolean,
    overwrite: Boolean
): Path
(source)

Recursively copies this directory and its content to the specified destination target path. Note that if this function throws, partial copying may have taken place.

Unlike File.copyRecursively, if some directories on the way to the target are missing, then they won't be created automatically. You can use the createParentDirectories function to ensure that required intermediate directories are created:

sourcePath.copyToRecursively(
    destinationPath.createParentDirectories(),
    followLinks = false
)

If the entry located by this path is a directory, this function recursively copies the directory itself and its content. Otherwise, this function copies only the entry.

If an exception occurs attempting to read, open or copy any entry under the source subtree, further actions will depend on the result of the onError invoked with the source and destination paths, that caused the error, and the exception itself as arguments. If onError throws, this function ends immediately with the exception. By default onError rethrows the exception. See OnErrorResult for available options.

This function performs "directory merge" operation. If an entry in the source subtree is a directory and the corresponding entry in the target subtree already exists and is also a directory, it does nothing. Otherwise, overwrite determines whether to overwrite existing destination entries. Attributes of a source entry, such as creation/modification date, are not copied.

followLinks impacts only symbolic links in the source subtree and determines whether to copy a symbolic link itself or the entry it points to. Symbolic links in the target subtree are not followed, i.e., no entry is copied to the location a symbolic link points to. If a copy destination is a symbolic link, it is overwritten or an exception is thrown depending on overwrite. Note that symbolic links on the way to the roots of the source and target subtrees are always followed.

To provide a custom logic for copying use the overload that takes a copyAction lambda.

Parameters

target - the destination path to copy recursively this entry to.

onError - the function that determines further actions if an error occurs. By default, rethrows the exception.

followLinks - false to copy a symbolic link itself, not its target. true to recursively copy the target of a symbolic link.

overwrite - false to throw if a destination entry already exists. true to overwrite existing destination entries.

Exceptions

NoSuchFileException - if the entry located by this path does not exist.

FileSystemException - if target is an entry inside the source subtree.

FileAlreadyExistsException - if a destination entry already exists and overwrite is false. This exception is passed to onError for handling.

IOException - if any errors occur while copying. This exception is passed to onError for handling.

SecurityException - if a security manager is installed and access is not permitted to an entry in the source or target subtree. This exception is passed to onError for handling.

JVM
JRE7
1.8
@ExperimentalPathApi fun Path.copyToRecursively(
    target: Path,
    onError: (source: Path, target: Path, exception: Exception) -> OnErrorResult = { _, _, exception -> throw exception },
    followLinks: Boolean,
    copyAction: CopyActionContext.(source: Path, target: Path) -> CopyActionResult = { src, dst -> src.copyToIgnoringExistingDirectory(dst, followLinks) }
): Path
(source)

Recursively copies this directory and its content to the specified destination target path. Note that if this function throws, partial copying may have taken place.

Unlike File.copyRecursively, if some directories on the way to the target are missing, then they won't be created automatically. You can use the createParentDirectories function to ensure that required intermediate directories are created:

sourcePath.copyToRecursively(
    destinationPath.createParentDirectories(),
    followLinks = false
)

If the entry located by this path is a directory, this function recursively copies the directory itself and its content. Otherwise, this function copies only the entry.

If an exception occurs attempting to read, open or copy any entry under the source subtree, further actions will depend on the result of the onError invoked with the source and destination paths, that caused the error, and the exception itself as arguments. If onError throws, this function ends immediately with the exception. By default onError rethrows the exception. See OnErrorResult for available options.

Copy operation is performed using copyAction. By default copyAction performs "directory merge" operation. If an entry in the source subtree is a directory and the corresponding entry in the target subtree already exists and is also a directory, it does nothing. Otherwise, the entry is copied using sourcePath.copyTo(destinationPath, *followLinksOption), which doesn't copy attributes of the source entry and throws if the destination entry already exists.

followLinks impacts only symbolic links in the source subtree and determines whether to copy a symbolic link itself or the entry it points to. Symbolic links in the target subtree are not followed, i.e., no entry is copied to the location a symbolic link points to. If a copy destination is a symbolic link, an exception is thrown. Note that symbolic links on the way to the roots of the source and target subtrees are always followed.

If a custom implementation of copyAction is provided, consider making it consistent with followLinks value. See CopyActionResult for available options.

If copyAction throws an exception, it is passed to onError for handling.

Parameters

target - the destination path to copy recursively this entry to.

onError - the function that determines further actions if an error occurs. By default, rethrows the exception.

followLinks - false to copy a symbolic link itself, not its target. true to recursively copy the target of a symbolic link.

copyAction - the function to call for copying source entries to their destination path rooted in target. By default, performs "directory merge" operation.

Exceptions

NoSuchFileException - if the entry located by this path does not exist.

FileSystemException - if target is an entry inside the source subtree.

IOException - if any errors occur while copying. This exception is passed to onError for handling.

SecurityException - if a security manager is installed and access is not permitted to an entry in the source or target subtree. This exception is passed to onError for handling.