Module io.smallrye.common.io

Package io.smallrye.common.io

Class Files2

java.lang.Object

io.smallrye.common.io.Files2

public final class Files2
extends Object

Extra utilities for dealing with the filesystem which are missing from Files.

Method Summary

Modifier and Type	Method	Description
static void	cleanRecursively(Path path)	Attempt to recursively clean the file or directory at the given path.
static void	cleanRecursively(SecureDirectoryStream<Path> sds)	Attempt to recursively clean all of the files returned by the given directory stream.
static void	cleanRecursively(SecureDirectoryStream<Path> sds, Path path)	Attempt to recursively clean the file or directory at the given directory and path.
static void	cleanRecursivelyEvenIfInsecure(DirectoryStream<Path> ds)	Attempt to recursively clean all of the files and directories from the given stream, even if secure directory streams are not supported.
static void	cleanRecursivelyEvenIfInsecure(Path path)	Attempt to recursively clean the file or directory at the given path, even if secure directory streams are not supported.
static long	copy(ReadableByteChannel in, WritableByteChannel out)	Copy from one channel to another in the most efficient manner supported by the JDK.
static void	copy(Path srcFile, Path destFile)	Equivalent to calling copy(Path, Path, CopyOption...) with no options.
static void	copy(Path srcFile, Path destFile, CopyOption option1)	Equivalent to calling copy(Path, Path, CopyOption...) with one option.
static void	copy(Path srcFile, Path destFile, CopyOption... options)	Copy a file as securely as possible from one path to another.
static void	copy(Path srcFile, Path destFile, CopyOption option1, CopyOption option2)	Equivalent to calling copy(Path, Path, CopyOption...) with two options.
static void	copy(SecureDirectoryStream<Path> sourceDir, Path srcFile, SecureDirectoryStream<Path> destDir, Path destFile)	Equivalent to calling copy(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...) with no options.
static void	copy(SecureDirectoryStream<Path> sourceDir, Path srcFile, SecureDirectoryStream<Path> destDir, Path destFile, CopyOption option1)	Equivalent to calling copy(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...) with one option.
static void	copy(SecureDirectoryStream<Path> sourceDir, Path srcFile, SecureDirectoryStream<Path> destDir, Path destFile, CopyOption... options)	Copy a file as securely as possible from one directory and path to another.
static void	copy(SecureDirectoryStream<Path> sourceDir, Path srcFile, SecureDirectoryStream<Path> destDir, Path destFile, CopyOption option1, CopyOption option2)	Equivalent to calling copy(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...) with two options.
static void	copyEvenIfInsecure(Path srcFile, Path destFile)	Copy a file, even if secure directory streams are not supported.
static void	copyRecursively(Path srcFile, Path destFile)	Equivalent to calling copyRecursively(Path, Path, CopyOption...) with no options.
static void	copyRecursively(Path srcFile, Path destFile, CopyOption option1)	Equivalent to calling copyRecursively(Path, Path, CopyOption...) with one option.
static void	copyRecursively(Path srcFile, Path destFile, CopyOption... options)	Recursively copy a file or directory as securely as possible from one path to another.
static void	copyRecursively(Path srcFile, Path destFile, CopyOption option1, CopyOption option2)	Equivalent to calling copyRecursively(Path, Path, CopyOption...) with two options.
static void	copyRecursively(SecureDirectoryStream<Path> sourceDir, Path srcFile, SecureDirectoryStream<Path> destDir, Path destFile)	Equivalent to calling copyRecursively(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...) with no options.
static void	copyRecursively(SecureDirectoryStream<Path> sourceDir, Path srcFile, SecureDirectoryStream<Path> destDir, Path destFile, CopyOption option1)	Equivalent to calling copyRecursively(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...) with one option.
static void	copyRecursively(SecureDirectoryStream<Path> sourceDir, Path srcFile, SecureDirectoryStream<Path> destDir, Path destFile, CopyOption... options)	Recursively copy a file or directory as securely as possible from one directory and path to another.
static void	copyRecursively(SecureDirectoryStream<Path> sourceDir, Path srcFile, SecureDirectoryStream<Path> destDir, Path destFile, CopyOption option1, CopyOption option2)	Equivalent to calling copyRecursively(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...) with two options.
static void	copyRecursivelyEvenIfInsecure(Path srcFile, Path destFile)	Recursively copy a file or directory, even if secure directory streams are not supported.
static Path	currentDirectory()	Returns the current working directory path at the time that this program was started (not null).
static UserPrincipal	currentUserPrincipal()	Returns the UserPrincipal corresponding to the current process user (not null).
static void	deleteRecursively(Path path)	Attempt to recursively delete the file or directory at the given path.
static void	deleteRecursively(SecureDirectoryStream<Path> sds)	Attempt to recursively delete all of the files returned by the given directory stream.
static void	deleteRecursively(SecureDirectoryStream<Path> sds, Path path)	Attempt to recursively delete the file or directory at the given directory and path.
static void	deleteRecursivelyEvenIfInsecure(DirectoryStream<Path> ds)	Attempt to recursively delete all of the files returned by the given directory stream, even if secure directory streams are not supported.
static void	deleteRecursivelyEvenIfInsecure(Path path)	Attempt to recursively delete the file or directory at the given path, even if secure directory streams are not supported.
static DeleteStats	deleteRecursivelyQuietly(Path path)	Attempt to recursively delete the file or directory at the given path.
static DeleteStats	deleteRecursivelyQuietly(SecureDirectoryStream<Path> sds)	Attempt to recursively delete all of the files returned by the given directory stream.
static DeleteStats	deleteRecursivelyQuietly(SecureDirectoryStream<Path> sds, Path path)	Attempt to recursively delete the file or directory at the given directory and path.
static DeleteStats	deleteRecursivelyQuietlyEvenIfInsecure(DirectoryStream<Path> ds)	Attempt to recursively delete all of the files returned by the given directory stream, even if secure directory streams are not supported.
static DeleteStats	deleteRecursivelyQuietlyEvenIfInsecure(Path path)	Attempt to recursively delete the file or directory at the given path, even if secure directory streams are not supported.
static Path	getParent(Path path)	Returns the parent of the given path, even if it is relative, or null if the path has no parent.
static boolean	hasSecureDirectories()	Returns true if this platform has secure directories, or false if it does not.
static void	move(Path srcFile, Path destFile)	Equivalent to calling move(Path, Path, CopyOption...) with no options.
static void	move(Path srcFile, Path destFile, CopyOption option1)	Equivalent to calling move(Path, Path, CopyOption...) with one option.
static void	move(Path srcFile, Path destFile, CopyOption... options)	Move a file as securely as possible from one path to another.
static void	move(Path srcFile, Path destFile, CopyOption option1, CopyOption option2)	Equivalent to calling move(Path, Path, CopyOption...) with two options.
static void	move(SecureDirectoryStream<Path> sourceDir, Path srcFile, SecureDirectoryStream<Path> destDir, Path destFile)	Equivalent to calling move(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...) with no options.
static void	move(SecureDirectoryStream<Path> sourceDir, Path srcFile, SecureDirectoryStream<Path> destDir, Path destFile, CopyOption option1)	Equivalent to calling move(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...) with one option.
static void	move(SecureDirectoryStream<Path> sourceDir, Path srcFile, SecureDirectoryStream<Path> destDir, Path destFile, CopyOption... options)	Move a file as securely as possible from one directory and path to another.
static void	move(SecureDirectoryStream<Path> sourceDir, Path srcFile, SecureDirectoryStream<Path> destDir, Path destFile, CopyOption option1, CopyOption option2)	Equivalent to calling move(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...) with two options.
static void	moveEvenIfInsecure(Path srcFile, Path destFile)	Move a file or directory, even if secure directory streams are not supported.
static SecureDirectoryStream<Path>	newSecureDirectoryStream(Path path, LinkOption... linkOptions)	Open a new secure directory stream at the given path.
static BufferedFile	openBuffered(Path path, OpenOption... options)	Open a buffered random-access file at the given path.
static BufferedFile	openBuffered(Path path, Collection<? extends OpenOption> options)	Open a buffered random-access file at the given path.
static BufferedFile	openBuffered(Path path, Collection<? extends OpenOption> options, Collection<? extends FileAttribute<?>> attrs)	Open a buffered random-access file at the given path, atomically setting the given file attributes if the file is created.
static FileAttribute<?>	privateDirectoryAttribute()	Returns the directory attribute that can be used to make a directory private to the current user (not null).
static FileAttribute<?>	privateFileAttribute()	Returns the file attribute that can be used to make a file private to the current user (not null).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

newSecureDirectoryStream

public static SecureDirectoryStream<Path> newSecureDirectoryStream(Path path,
 LinkOption... linkOptions)
                                                            throws IOException

Open a new secure directory stream at the given path. If the link option LinkOption.NOFOLLOW_LINKS is given, the open will fail with an exception if path is a symbolic link.

Parameters:

path - the path of the directory to open (must not be null)

linkOptions - the link options (must not be null)

Returns:

a secure directory stream for the given path (not null)

Throws:

NotDirectoryException - if the target path is not a directory

IOException - if another I/O error occurs

UnsupportedOperationException - if this platform does not support secure directory streams

See Also:

• SecureDirectoryStream.newDirectoryStream(Object, LinkOption...)

deleteRecursivelyEvenIfInsecure

public static void deleteRecursivelyEvenIfInsecure(Path path)
                                            throws IOException

Attempt to recursively delete the file or directory at the given path, even if secure directory streams are not supported. If the target path is a symbolic link, it will be removed. Warning: this method can potentially delete files outside the intended path if the target platform does not support secure directory iteration.

Parameters:

path - the path to delete (must not be null)

Throws:

IOException - if one or more files fails to be deleted or another I/O error occurs

See Also:

• deleteRecursively(Path)

deleteRecursivelyEvenIfInsecure

public static void deleteRecursivelyEvenIfInsecure(DirectoryStream<Path> ds)
                                            throws IOException

Attempt to recursively delete all of the files returned by the given directory stream, even if secure directory streams are not supported. If any of the target paths are symbolic links, they will be removed. Warning: this method can potentially delete files outside the intended path if the target platform does not support secure directory iteration.

The directory stream is not closed by this operation. The caller should ensure that the stream is closed at the appropriate time.

Parameters:

ds - the directory stream whose contents should be removed (must not be null)

Throws:

IOException - if one or more files fails to be deleted or another I/O error occurs

See Also:

• deleteRecursively(SecureDirectoryStream)

deleteRecursively

public static void deleteRecursively(Path path)
                              throws IOException

Attempt to recursively delete the file or directory at the given path. If the target path is a symbolic link, it will be removed.

Parameters:

path - the file or directory to be removed (must not be null)

Throws:

IOException - if one or more files fails to be deleted or another I/O error occurs

UnsupportedOperationException - if secure directory removal is unsupported

deleteRecursively

public static void deleteRecursively(SecureDirectoryStream<Path> sds)
                              throws IOException

Attempt to recursively delete all of the files returned by the given directory stream. If any of the target paths are symbolic links, they will be removed.

The directory stream is not closed by this operation, but its iterator is consumed. The caller should ensure that the stream is closed at the appropriate time.

Parameters:

sds - the directory stream whose contents should be removed (must not be null)

Throws:

IOException - if one or more files fails to be deleted or another I/O error occurs

deleteRecursively

public static void deleteRecursively(SecureDirectoryStream<Path> sds,
 Path path)
                              throws IOException

Attempt to recursively delete the file or directory at the given directory and path. If the target path or any nested path is a symbolic link, it will be removed and will not be treated as a directory. If the target path is absolute, then sds is ignored and the absolute path is removed. The caller should ensure that the given path is sanitized if needed (see Path.normalize() and Path.isAbsolute()).

The directory stream is not closed by this operation, and its iterator is not consumed. The caller should ensure that the stream is closed at the appropriate time.

Parameters:

sds - the directory stream containing the file (must not be null)

path - the relative path of the file or directory to be removed (must not be null)

Throws:

IOException - if one or more files fails to be deleted or another I/O error occurs

deleteRecursivelyQuietlyEvenIfInsecure

public static DeleteStats deleteRecursivelyQuietlyEvenIfInsecure(Path path)

Attempt to recursively delete the file or directory at the given path, even if secure directory streams are not supported. I/O errors will not be reported. If the target path is a symbolic link, it will be removed. Warning: this method can potentially delete files outside the intended path if the target platform does not support secure directory iteration.

Parameters:

path - the path to delete (must not be null)

Returns:

the deletion statistics (not null)

See Also:

• deleteRecursivelyQuietly(Path)

deleteRecursivelyQuietlyEvenIfInsecure

public static DeleteStats deleteRecursivelyQuietlyEvenIfInsecure(DirectoryStream<Path> ds)

Attempt to recursively delete all of the files returned by the given directory stream, even if secure directory streams are not supported. I/O errors will not be reported. If any of the target paths are symbolic links, they will be removed. Warning: this method can potentially delete files outside the intended path if the target platform does not support secure directory iteration.

The directory stream is not closed by this operation. The caller should ensure that the stream is closed at the appropriate time.

Parameters:

ds - the directory stream whose contents should be removed (must not be null)

Returns:

the deletion statistics (not null)

See Also:

• deleteRecursivelyQuietly(SecureDirectoryStream)

deleteRecursivelyQuietly

public static DeleteStats deleteRecursivelyQuietly(Path path)

Attempt to recursively delete the file or directory at the given path. If the target path is a symbolic link, it will be removed. I/O errors will not be reported.

Parameters:

path - the file or directory to be removed (must not be null)

Returns:

the deletion statistics (not null)

Throws:

UnsupportedOperationException - if secure directory removal is unsupported

deleteRecursivelyQuietly

public static DeleteStats deleteRecursivelyQuietly(SecureDirectoryStream<Path> sds)

Attempt to recursively delete all of the files returned by the given directory stream. If any of the target paths are symbolic links, they will be removed. I/O errors will not be reported.

The directory stream is not closed by this operation, but its iterator is consumed. The caller should ensure that the stream is closed at the appropriate time.

Parameters:

sds - the directory stream whose contents should be removed (must not be null)

Returns:

the deletion statistics (not null)

deleteRecursivelyQuietly

public static DeleteStats deleteRecursivelyQuietly(SecureDirectoryStream<Path> sds,
 Path path)

Attempt to recursively delete the file or directory at the given directory and path. If the target path or any nested path is a symbolic link, it will be removed and will not be treated as a directory. If the target path is absolute, then sds is ignored and the absolute path is removed. I/O errors will not be reported. The caller should ensure that the given path is sanitized if needed (see Path.normalize() and Path.isAbsolute()).

The directory stream is not closed by this operation, and its iterator is not consumed. The caller should ensure that the stream is closed at the appropriate time.

Parameters:

sds - the directory stream containing the file (must not be null)

path - the relative path of the file or directory to be removed (must not be null)

Returns:

the deletion statistics (not null)

cleanRecursivelyEvenIfInsecure

public static void cleanRecursivelyEvenIfInsecure(Path path)
                                           throws IOException

Attempt to recursively clean the file or directory at the given path, even if secure directory streams are not supported. If the target path or any nested path is not a directory, it will be removed. Directories will be preserved. Warning: this method can potentially delete files outside the intended path if the target platform does not support secure directory iteration.

Parameters:

path - the path to clean (must not be null)

Throws:

IOException - if one or more files fails to be cleaned or another I/O error occurs

See Also:

• cleanRecursively(Path)

cleanRecursivelyEvenIfInsecure

public static void cleanRecursivelyEvenIfInsecure(DirectoryStream<Path> ds)
                                           throws IOException

Attempt to recursively clean all of the files and directories from the given stream, even if secure directory streams are not supported. If any nested path is not a directory, it will be removed. Directories will be preserved. Warning: this method can potentially delete files outside the intended path if the target platform does not support secure directory iteration.

The directory stream is not closed by this operation. The caller should ensure that the stream is closed at the appropriate time.

Parameters:

ds - the directory stream whose contents should be cleaned (must not be null)

Throws:

IOException - if one or more files fails to be cleaned or another I/O error occurs

See Also:

• cleanRecursively(Path)

cleanRecursively

public static void cleanRecursively(Path path)
                             throws IOException

Attempt to recursively clean the file or directory at the given path. If the target path is not a directory, it will be removed.

Parameters:

path - the file or directory to be cleaned (must not be null)

Throws:

IOException - if one or more files fails to be deleted or another I/O error occurs

UnsupportedOperationException - if secure directory traversal is unsupported

cleanRecursively

public static void cleanRecursively(SecureDirectoryStream<Path> sds)
                             throws IOException

Attempt to recursively clean all of the files returned by the given directory stream. If any of the target paths are not directories, they will be removed.

The directory stream is not closed by this operation, but its iterator is consumed. The caller should ensure that the stream is closed at the appropriate time.

Parameters:

sds - the directory stream whose contents should be cleaned (must not be null)

Throws:

IOException - if one or more files fails to be deleted or another I/O error occurs

cleanRecursively

public static void cleanRecursively(SecureDirectoryStream<Path> sds,
 Path path)
                             throws IOException

Attempt to recursively clean the file or directory at the given directory and path. If the target path or any nested path is a symbolic link, it will be removed and will not be treated as a directory. If any of the target paths are not directories, they will be removed. If the target path is absolute, then sds is ignored and the absolute path is cleaned. The caller should ensure that the given path is sanitized if needed (see Path.normalize() and Path.isAbsolute()).

The directory stream is not closed by this operation, and its iterator is not consumed. The caller should ensure that the stream is closed at the appropriate time.

Parameters:

sds - the directory stream containing the file (must not be null)

path - the relative path of the file or directory to be cleaned (must not be null)

Throws:

IOException - if one or more files fails to be deleted or another I/O error occurs

getParent

public static Path getParent(Path path)

Returns the parent of the given path, even if it is relative, or null if the path has no parent. Relative paths are resolved relative to the current directory.

Parameters:

path - the path to examine (must not be null)

Returns:

the parent of the given path, even if it is relative, or null if the path has no parent

See Also:

• Path.getParent()
• currentDirectory()

copy

public static long copy(ReadableByteChannel in,
 WritableByteChannel out)
                 throws IOException

Copy from one channel to another in the most efficient manner supported by the JDK. Neither channel is closed.

Parameters:

in - the input channel (must not be null)

out - the output channel (must not be null)

Returns:

the number of bytes copied

Throws:

IOException - if copying failed for some reason

copy

public static void copy(SecureDirectoryStream<Path> sourceDir,
 Path srcFile,
 SecureDirectoryStream<Path> destDir,
 Path destFile)
                 throws IOException

Equivalent to calling copy(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...) with no options.

Parameters:

sourceDir - the directory stream of the source directory (must not be null)

srcFile - the source path name (must not be null)

destDir - the directory stream of the destination directory (must not be null)

destFile - the destination path name (must not be null)

Throws:

UnsupportedOperationException - if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during copy

See Also:

• copy(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...)

copy

public static void copy(SecureDirectoryStream<Path> sourceDir,
 Path srcFile,
 SecureDirectoryStream<Path> destDir,
 Path destFile,
 CopyOption option1)
                 throws IOException

Equivalent to calling copy(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...) with one option.

Parameters:

sourceDir - the directory stream of the source directory (must not be null)

srcFile - the source path name (must not be null)

destDir - the directory stream of the destination directory (must not be null)

destFile - the destination path name (must not be null)

option1 - the copy option to use for the operation (must not be null)

Throws:

UnsupportedOperationException - if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during copy

See Also:

• copy(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...)

copy

public static void copy(SecureDirectoryStream<Path> sourceDir,
 Path srcFile,
 SecureDirectoryStream<Path> destDir,
 Path destFile,
 CopyOption option1,
 CopyOption option2)
                 throws IOException

Equivalent to calling copy(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...) with two options.

Parameters:

sourceDir - the directory stream of the source directory (must not be null)

srcFile - the source path name (must not be null)

destDir - the directory stream of the destination directory (must not be null)

destFile - the destination path name (must not be null)

option1 - the first copy option to use for the operation (must not be null)

option2 - the second copy option to use for the operation (must not be null)

Throws:

UnsupportedOperationException - if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during copy

See Also:

• copy(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...)

copy

public static void copy(SecureDirectoryStream<Path> sourceDir,
 Path srcFile,
 SecureDirectoryStream<Path> destDir,
 Path destFile,
 CopyOption... options)
                 throws IOException

Copy a file as securely as possible from one directory and path to another. If both srcFile and destFile are absolute paths, then this method behaves exactly the same as Files.copy(Path, Path, CopyOption...). If srcFile and destFile are found to refer to the same file, then no action is taken and this method will return directly.

Otherwise, an attempt is made to:

• Copy symbolic links as symbolic links (when LinkOption.NOFOLLOW_LINKS is given)
• Copy directories as directories (non-recursively)
• Preserve file attributes (when StandardCopyOption.COPY_ATTRIBUTES is given)
• Copy regular files using the most efficient JDK mechanism available

The operation may fail with a IOException if some part of the operation fails; in this case, the file may be partially copied.

If some aspect of the operation is not supported, UnsupportedOperationException will be thrown. Currently, the currently unsupported operations include:

• Copying a symbolic link from or to a relative path (unsupported by the JDK as of JDK 25)
• Copying a directory into a relative path (unsupported by the JDK as of JDK 25)

The following copy options are allowed:

• LinkOption.NOFOLLOW_LINKS
• StandardCopyOption.COPY_ATTRIBUTES
• StandardCopyOption.REPLACE_EXISTING

Giving any other option will cause a IllegalArgumentException to be thrown.

Parameters:

sourceDir - the directory stream of the source directory (must not be null)

srcFile - the source path name (must not be null)

destDir - the directory stream of the destination directory (must not be null)

destFile - the destination path name (must not be null)

options - the copy options to use for the operation (must not be null)

Throws:

UnsupportedOperationException - if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during copy

See Also:

• SecureDirectoryStream.move(Object, SecureDirectoryStream, Object)

copyEvenIfInsecure

public static void copyEvenIfInsecure(Path srcFile,
 Path destFile)
                               throws IOException

Copy a file, even if secure directory streams are not supported. Warning: this method can potentially copy files outside the intended path if the target platform does not support secure directory iteration.

Parameters:

srcFile - the source path name (must not be null)

destFile - the destination path name (must not be null)

Throws:

IOException - if an I/O error occurs during copy

See Also:

• copy(Path, Path)

copy

public static void copy(Path srcFile,
 Path destFile)
                 throws IOException

Equivalent to calling copy(Path, Path, CopyOption...) with no options.

Parameters:

srcFile - the source path name (must not be null)

destFile - the destination path name (must not be null)

Throws:

UnsupportedOperationException - if secure directory traversal is unsupported or if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during copy

See Also:

• copy(Path, Path, CopyOption...)

copy

public static void copy(Path srcFile,
 Path destFile,
 CopyOption option1)
                 throws IOException

Equivalent to calling copy(Path, Path, CopyOption...) with one option.

Parameters:

srcFile - the source path name (must not be null)

destFile - the destination path name (must not be null)

option1 - the copy option to use for the operation (must not be null)

Throws:

UnsupportedOperationException - if secure directory traversal is unsupported or if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during copy

See Also:

• copy(Path, Path, CopyOption...)

copy

public static void copy(Path srcFile,
 Path destFile,
 CopyOption option1,
 CopyOption option2)
                 throws IOException

Equivalent to calling copy(Path, Path, CopyOption...) with two options.

Parameters:

srcFile - the source path name (must not be null)

destFile - the destination path name (must not be null)

option1 - the first copy option to use for the operation (must not be null)

option2 - the second copy option to use for the operation (must not be null)

Throws:

UnsupportedOperationException - if secure directory traversal is unsupported or if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during copy

See Also:

• copy(Path, Path, CopyOption...)

copy

public static void copy(Path srcFile,
 Path destFile,
 CopyOption... options)
                 throws IOException

Copy a file as securely as possible from one path to another. This method uses a secure directory stream acquired from the current working directory to perform the operation. If srcFile and destFile are found to refer to the same file, then no action is taken and this method will return directly.

Otherwise, an attempt is made to:

• Copy symbolic links as symbolic links (when LinkOption.NOFOLLOW_LINKS is given)
• Copy directories as directories (non-recursively)
• Preserve file attributes (when StandardCopyOption.COPY_ATTRIBUTES is given)
• Copy regular files using the most efficient JDK mechanism available

The operation may fail with a IOException if some part of the operation fails; in this case, the file may be partially copied.

If some aspect of the operation is not supported, UnsupportedOperationException will be thrown. Currently, the currently unsupported operations include:

• Copying a symbolic link from or to a relative path (unsupported by the JDK as of JDK 25)
• Copying a directory into a relative path (unsupported by the JDK as of JDK 25)

The following copy options are allowed:

• LinkOption.NOFOLLOW_LINKS
• StandardCopyOption.COPY_ATTRIBUTES
• StandardCopyOption.REPLACE_EXISTING

Giving any other option will cause a IllegalArgumentException to be thrown.

Parameters:

srcFile - the source path name (must not be null)

destFile - the destination path name (must not be null)

options - the copy options to use for the operation (must not be null)

Throws:

UnsupportedOperationException - if secure directory traversal is unsupported or if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during copy

See Also:

• copy(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...)

copyRecursively

public static void copyRecursively(SecureDirectoryStream<Path> sourceDir,
 Path srcFile,
 SecureDirectoryStream<Path> destDir,
 Path destFile)
                            throws IOException

Equivalent to calling copyRecursively(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...) with no options.

Parameters:

sourceDir - the directory stream of the source directory (must not be null)

srcFile - the source path name (must not be null)

destDir - the directory stream of the destination directory (must not be null)

destFile - the destination path name (must not be null)

Throws:

UnsupportedOperationException - if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during copy

See Also:

• copyRecursively(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...)

copyRecursively

public static void copyRecursively(SecureDirectoryStream<Path> sourceDir,
 Path srcFile,
 SecureDirectoryStream<Path> destDir,
 Path destFile,
 CopyOption option1)
                            throws IOException

Equivalent to calling copyRecursively(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...) with one option.

Parameters:

sourceDir - the directory stream of the source directory (must not be null)

srcFile - the source path name (must not be null)

destDir - the directory stream of the destination directory (must not be null)

destFile - the destination path name (must not be null)

option1 - the copy option to use for the operation (must not be null)

Throws:

UnsupportedOperationException - if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during copy

See Also:

• copyRecursively(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...)

copyRecursively

public static void copyRecursively(SecureDirectoryStream<Path> sourceDir,
 Path srcFile,
 SecureDirectoryStream<Path> destDir,
 Path destFile,
 CopyOption option1,
 CopyOption option2)
                            throws IOException

Equivalent to calling copyRecursively(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...) with two options.

Parameters:

sourceDir - the directory stream of the source directory (must not be null)

srcFile - the source path name (must not be null)

destDir - the directory stream of the destination directory (must not be null)

destFile - the destination path name (must not be null)

option1 - the first copy option to use for the operation (must not be null)

option2 - the second copy option to use for the operation (must not be null)

Throws:

UnsupportedOperationException - if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during copy

See Also:

• copyRecursively(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...)

copyRecursively

public static void copyRecursively(SecureDirectoryStream<Path> sourceDir,
 Path srcFile,
 SecureDirectoryStream<Path> destDir,
 Path destFile,
 CopyOption... options)
                            throws IOException

Recursively copy a file or directory as securely as possible from one directory and path to another. If srcFile and destFile are found to refer to the same file, then no action is taken and this method will return directly.

Otherwise, an attempt is made to:

• Copy symbolic links as symbolic links (when LinkOption.NOFOLLOW_LINKS is given)
• Copy directories as directories (recursively)
• Preserve file attributes (when StandardCopyOption.COPY_ATTRIBUTES is given)
• Copy regular files using the most efficient JDK mechanism available

The operation may fail with a IOException if some part of the operation fails; in this case, the file or directory may be partially copied.

If some aspect of the operation is not supported, UnsupportedOperationException will be thrown. Currently, the currently unsupported operations include:

• Copying a symbolic link from or to a relative path (unsupported by the JDK as of JDK 25)
• Copying a directory into a relative path (unsupported by the JDK as of JDK 25)

The following copy options are allowed:

• LinkOption.NOFOLLOW_LINKS
• StandardCopyOption.COPY_ATTRIBUTES
• StandardCopyOption.REPLACE_EXISTING

Giving any other option will cause a IllegalArgumentException to be thrown.

Parameters:

sourceDir - the directory stream of the source directory (must not be null)

srcFile - the source path name (must not be null)

destDir - the directory stream of the destination directory (must not be null)

destFile - the destination path name (must not be null)

options - the copy options to use for the operation (must not be null)

Throws:

UnsupportedOperationException - if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during copy

copyRecursivelyEvenIfInsecure

public static void copyRecursivelyEvenIfInsecure(Path srcFile,
 Path destFile)
                                          throws IOException

Recursively copy a file or directory, even if secure directory streams are not supported. Warning: this method can potentially copy files outside the intended path if the target platform does not support secure directory iteration.

Parameters:

srcFile - the source path name (must not be null)

destFile - the destination path name (must not be null)

Throws:

IOException - if an I/O error occurs during copy

See Also:

• copyRecursively(Path, Path)

copyRecursively

public static void copyRecursively(Path srcFile,
 Path destFile)
                            throws IOException

Equivalent to calling copyRecursively(Path, Path, CopyOption...) with no options.

Parameters:

srcFile - the source path name (must not be null)

destFile - the destination path name (must not be null)

Throws:

UnsupportedOperationException - if secure directory traversal is unsupported or if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during copy

See Also:

• copyRecursively(Path, Path, CopyOption...)

copyRecursively

public static void copyRecursively(Path srcFile,
 Path destFile,
 CopyOption option1)
                            throws IOException

Equivalent to calling copyRecursively(Path, Path, CopyOption...) with one option.

Parameters:

srcFile - the source path name (must not be null)

destFile - the destination path name (must not be null)

option1 - the copy option to use for the operation (must not be null)

Throws:

UnsupportedOperationException - if secure directory traversal is unsupported or if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during copy

See Also:

• copyRecursively(Path, Path, CopyOption...)

copyRecursively

public static void copyRecursively(Path srcFile,
 Path destFile,
 CopyOption option1,
 CopyOption option2)
                            throws IOException

Equivalent to calling copyRecursively(Path, Path, CopyOption...) with two options.

Parameters:

srcFile - the source path name (must not be null)

destFile - the destination path name (must not be null)

option1 - the first copy option to use for the operation (must not be null)

option2 - the second copy option to use for the operation (must not be null)

Throws:

UnsupportedOperationException - if secure directory traversal is unsupported or if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during copy

See Also:

• copyRecursively(Path, Path, CopyOption...)

copyRecursively

public static void copyRecursively(Path srcFile,
 Path destFile,
 CopyOption... options)
                            throws IOException

Recursively copy a file or directory as securely as possible from one path to another. This method uses a secure directory stream acquired from the current working directory to perform the operation. If srcFile and destFile are found to refer to the same file, then no action is taken and this method will return directly.

Otherwise, an attempt is made to:

• Copy symbolic links as symbolic links (when LinkOption.NOFOLLOW_LINKS is given)
• Copy directories as directories (recursively)
• Preserve file attributes (when StandardCopyOption.COPY_ATTRIBUTES is given)
• Copy regular files using the most efficient JDK mechanism available

The operation may fail with a IOException if some part of the operation fails; in this case, the file or directory may be partially copied.

If some aspect of the operation is not supported, UnsupportedOperationException will be thrown. Currently, the currently unsupported operations include:

• Copying a symbolic link from or to a relative path (unsupported by the JDK as of JDK 25)
• Copying a directory into a relative path (unsupported by the JDK as of JDK 25)

The following copy options are allowed:

• LinkOption.NOFOLLOW_LINKS
• StandardCopyOption.COPY_ATTRIBUTES
• StandardCopyOption.REPLACE_EXISTING

Giving any other option will cause a IllegalArgumentException to be thrown.

Parameters:

srcFile - the source path name (must not be null)

destFile - the destination path name (must not be null)

options - the copy options to use for the operation (must not be null)

Throws:

UnsupportedOperationException - if secure directory traversal is unsupported or if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during copy

See Also:

• copyRecursively(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...)

move

public static void move(SecureDirectoryStream<Path> sourceDir,
 Path srcFile,
 SecureDirectoryStream<Path> destDir,
 Path destFile)
                 throws IOException

Equivalent to calling move(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...) with no options.

Parameters:

sourceDir - the directory stream of the source directory (must not be null)

srcFile - the source path name (must not be null)

destDir - the directory stream of the destination directory (must not be null)

destFile - the destination path name (must not be null)

Throws:

UnsupportedOperationException - if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during move

See Also:

• move(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...)

move

public static void move(SecureDirectoryStream<Path> sourceDir,
 Path srcFile,
 SecureDirectoryStream<Path> destDir,
 Path destFile,
 CopyOption option1)
                 throws IOException

Equivalent to calling move(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...) with one option.

Parameters:

sourceDir - the directory stream of the source directory (must not be null)

srcFile - the source path name (must not be null)

destDir - the directory stream of the destination directory (must not be null)

destFile - the destination path name (must not be null)

option1 - the move option to use for the operation (must not be null)

Throws:

UnsupportedOperationException - if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during move

See Also:

• move(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...)

move

public static void move(SecureDirectoryStream<Path> sourceDir,
 Path srcFile,
 SecureDirectoryStream<Path> destDir,
 Path destFile,
 CopyOption option1,
 CopyOption option2)
                 throws IOException

Equivalent to calling move(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...) with two options.

Parameters:

sourceDir - the directory stream of the source directory (must not be null)

srcFile - the source path name (must not be null)

destDir - the directory stream of the destination directory (must not be null)

destFile - the destination path name (must not be null)

option1 - the first move option to use for the operation (must not be null)

option2 - the second move option to use for the operation (must not be null)

Throws:

UnsupportedOperationException - if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during move

See Also:

• move(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...)

move

public static void move(SecureDirectoryStream<Path> sourceDir,
 Path srcFile,
 SecureDirectoryStream<Path> destDir,
 Path destFile,
 CopyOption... options)
                 throws IOException

Move a file as securely as possible from one directory and path to another. If both srcFile and destFile are absolute paths, then this method behaves exactly the same as Files.move(Path, Path, CopyOption...). If srcFile and destFile are found to refer to the same file, then no action is taken and this method will return directly.

Otherwise, an attempt is made to:

• Move symbolic links as symbolic links (when LinkOption.NOFOLLOW_LINKS is given)
• Move directories as directories (including their contents)
• Preserve file attributes (when StandardCopyOption.COPY_ATTRIBUTES is given)
• Move regular files using the most efficient JDK mechanism available

The operation may fail with a IOException if some part of the operation fails; in this case, the file may be partially copied.

If some aspect of the operation is not supported, UnsupportedOperationException will be thrown. Currently, the currently unsupported operations include:

• Copying a symbolic link from or to a relative path (unsupported by the JDK as of JDK 25)
• Copying a directory into a relative path (unsupported by the JDK as of JDK 25)

The following move options are allowed:

• LinkOption.NOFOLLOW_LINKS
• StandardCopyOption.COPY_ATTRIBUTES
• StandardCopyOption.REPLACE_EXISTING
• StandardCopyOption.ATOMIC_MOVE

Giving any other option will cause a IllegalArgumentException to be thrown.

Parameters:

sourceDir - the directory stream of the source directory (must not be null)

srcFile - the source path name (must not be null)

destDir - the directory stream of the destination directory (must not be null)

destFile - the destination path name (must not be null)

options - the move options to use for the operation (must not be null)

Throws:

UnsupportedOperationException - if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during move

See Also:

• SecureDirectoryStream.move(Object, SecureDirectoryStream, Object)

moveEvenIfInsecure

public static void moveEvenIfInsecure(Path srcFile,
 Path destFile)
                               throws IOException

Move a file or directory, even if secure directory streams are not supported. Warning: this method can potentially move files outside the intended path if the target platform does not support secure directory iteration.

Parameters:

srcFile - the source path name (must not be null)

destFile - the destination path name (must not be null)

Throws:

IOException - if an I/O error occurs during move

See Also:

• move(Path, Path)

move

public static void move(Path srcFile,
 Path destFile)
                 throws IOException

Equivalent to calling move(Path, Path, CopyOption...) with no options.

Parameters:

srcFile - the source path name (must not be null)

destFile - the destination path name (must not be null)

Throws:

UnsupportedOperationException - if secure directory traversal is unsupported or if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during move

See Also:

• move(Path, Path, CopyOption...)

move

public static void move(Path srcFile,
 Path destFile,
 CopyOption option1)
                 throws IOException

Equivalent to calling move(Path, Path, CopyOption...) with one option.

Parameters:

srcFile - the source path name (must not be null)

destFile - the destination path name (must not be null)

option1 - the move option to use for the operation (must not be null)

Throws:

UnsupportedOperationException - if secure directory traversal is unsupported or if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during move

See Also:

• move(Path, Path, CopyOption...)

move

public static void move(Path srcFile,
 Path destFile,
 CopyOption option1,
 CopyOption option2)
                 throws IOException

Equivalent to calling move(Path, Path, CopyOption...) with two options.

Parameters:

srcFile - the source path name (must not be null)

destFile - the destination path name (must not be null)

option1 - the first move option to use for the operation (must not be null)

option2 - the second move option to use for the operation (must not be null)

Throws:

UnsupportedOperationException - if secure directory traversal is unsupported or if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during move

See Also:

• move(Path, Path, CopyOption...)

move

public static void move(Path srcFile,
 Path destFile,
 CopyOption... options)
                 throws IOException

Move a file as securely as possible from one path to another. This method uses a secure directory stream acquired from the current working directory to perform the operation. If srcFile and destFile are found to refer to the same file, then no action is taken and this method will return directly.

Otherwise, an attempt is made to:

• Move symbolic links as symbolic links (when LinkOption.NOFOLLOW_LINKS is given)
• Move directories as directories (including their contents)
• Preserve file attributes (when StandardCopyOption.COPY_ATTRIBUTES is given)
• Move regular files using the most efficient JDK mechanism available

The operation may fail with a IOException if some part of the operation fails; in this case, the file may be partially copied.

If some aspect of the operation is not supported, UnsupportedOperationException will be thrown. Currently, the currently unsupported operations include:

• Copying a symbolic link from or to a relative path (unsupported by the JDK as of JDK 25)
• Copying a directory into a relative path (unsupported by the JDK as of JDK 25)

The following move options are allowed:

• LinkOption.NOFOLLOW_LINKS
• StandardCopyOption.COPY_ATTRIBUTES
• StandardCopyOption.REPLACE_EXISTING
• StandardCopyOption.ATOMIC_MOVE

Giving any other option will cause a IllegalArgumentException to be thrown.

Parameters:

srcFile - the source path name (must not be null)

destFile - the destination path name (must not be null)

options - the move options to use for the operation (must not be null)

Throws:

UnsupportedOperationException - if secure directory traversal is unsupported or if the combination of options is unsupported by the source or destination filesystem or the JDK itself

IOException - if an I/O error occurs during move

See Also:

• move(SecureDirectoryStream, Path, SecureDirectoryStream, Path, CopyOption...)

currentDirectory

public static Path currentDirectory()

Returns the current working directory path at the time that this program was started (not null). This path comes from the user.dir system property.

Returns:

the current working directory path at the time that this program was started (not null)

hasSecureDirectories

public static boolean hasSecureDirectories()

Returns true if this platform has secure directories, or false if it does not. Some operating systems or JVM versions do not support secure directories.

Returns:

true if this platform has secure directories, or false if it does not

openBuffered

public static BufferedFile openBuffered(Path path,
 OpenOption... options)
                                 throws IOException

Open a buffered random-access file at the given path.

The options may include most StandardOpenOption values, as well as BufferSizeOption and ByteOrderOption to configure the buffer size and default byte order respectively. If no BufferSizeOption is given, a default of BufferSizeOption.DEFAULT_BUFFER_SIZE is used. If no ByteOrderOption is given, the native byte order is used. If neither READ nor WRITE is specified, the file is opened for reading only.

Note that APPEND mode is not supported for random-access buffered files.

Parameters:

path - the path to the file (must not be null)

options - the open options (must not be null, and must not contain null elements)

Returns:

a new BufferedFile instance

Throws:

IOException - if an I/O error occurs

FileAlreadyExistsException - if CREATE_NEW is specified and the file already exists

IllegalArgumentException - if conflicting options are specified (e.g., both ByteOrderOption.BIG_ENDIAN and ByteOrderOption.LITTLE_ENDIAN)

UnsupportedOperationException - if an unsupported option is specified

openBuffered

public static BufferedFile openBuffered(Path path,
 Collection<? extends OpenOption> options)
                                 throws IOException

Open a buffered random-access file at the given path.

The options may include most StandardOpenOption values, as well as BufferSizeOption and ByteOrderOption to configure the buffer size and default byte order respectively. If no BufferSizeOption is given, a default of BufferSizeOption.DEFAULT_BUFFER_SIZE is used. If no ByteOrderOption is given, the native byte order is used. If neither READ nor WRITE is specified, the file is opened for reading only.

Note that APPEND mode is not supported for random-access buffered files.

Parameters:

path - the path to the file (must not be null)

options - the open options (must not be null, and must not contain null elements)

Returns:

a new BufferedFile instance

Throws:

IOException - if an I/O error occurs

FileAlreadyExistsException - if CREATE_NEW is specified and the file already exists

IllegalArgumentException - if conflicting options are specified (e.g., both ByteOrderOption.BIG_ENDIAN and ByteOrderOption.LITTLE_ENDIAN)

UnsupportedOperationException - if an unsupported option is specified

openBuffered

public static BufferedFile openBuffered(Path path,
 Collection<? extends OpenOption> options,
 Collection<? extends FileAttribute<?>> attrs)
                                 throws IOException

Open a buffered random-access file at the given path, atomically setting the given file attributes if the file is created.

The options may include most StandardOpenOption values, as well as BufferSizeOption and ByteOrderOption to configure the buffer size and default byte order respectively. If no BufferSizeOption is given, a default of BufferSizeOption.DEFAULT_BUFFER_SIZE is used. If no ByteOrderOption is given, the native byte order is used. If neither READ nor WRITE is specified, the file is opened for reading only.

The attrs parameter specifies file attributes to set atomically when creating the file. If the file already exists and the CREATE option is given, the attributes are ignored. If the file already exists and the CREATE_NEW option is given, a FileAlreadyExistsException is thrown as usual.

Note that APPEND mode is not supported for random-access buffered files.

Parameters:

path - the path to the file (must not be null)

options - the open options (must not be null, and must not contain null elements)

attrs - the file attributes to set atomically when creating the file (must not be null)

Returns:

a new BufferedFile instance

Throws:

IOException - if an I/O error occurs

FileAlreadyExistsException - if CREATE_NEW is specified and the file already exists

IllegalArgumentException - if conflicting options are specified (e.g., both ByteOrderOption.BIG_ENDIAN and ByteOrderOption.LITTLE_ENDIAN)

UnsupportedOperationException - if an unsupported option is specified

currentUserPrincipal

public static UserPrincipal currentUserPrincipal()

Returns the UserPrincipal corresponding to the current process user (not null). The principal is looked up via the default filesystem's user principal lookup service.

Returns:

the UserPrincipal corresponding to the current process user (not null)

Throws:

IOError - if the user principal lookup fails

privateFileAttribute

public static FileAttribute<?> privateFileAttribute()

Returns the file attribute that can be used to make a file private to the current user (not null). The attribute value depends on the operating system.

Returns:

the file attribute that can be used to make a file private to the current user (not null)

Throws:

IOError - if the user principal lookup fails

privateDirectoryAttribute

public static FileAttribute<?> privateDirectoryAttribute()

Returns the directory attribute that can be used to make a directory private to the current user (not null). The attribute value depends on the operating system.

Returns:

the directory attribute that can be used to make a directory private to the current user (not null)

Throws:

IOError - if the user principal lookup fails