public class

MoreFiles

extends Object
java.lang.Object
   ↳ com.atlassian.bitbucket.util.MoreFiles

Class Overview

Additional utility methods missing from Files.

Summary

Public Methods
static void cleanDirectory(Path directory)
Deletes any files or subdirectories in the specified directory and leaves the directory empty.
static void deleteOnExit(Path path)
Registers the provided path to be deleted when the JVM exits.
static boolean deleteQuietly(Path path)
Recursively deletes the specified path, suppressing any IOExceptions that are thrown.
static void deleteRecursively(Path path)
Recursively deletes the specified path.
static long getLastModified(Path path)
Gets the last modified time for the specified Path, in milliseconds.
static boolean isAclSupported(Path path)
Gets the file store for the specified Path, and returns whether the file store supports ACLs.
static boolean isPosixSupported(Path path)
Gets the file store for the specified Path, and returns whether the file store supports POSIX.
static boolean isWithin(Path path, Path expectedParent)
Returns true if the specified path is contained within the expectedParent.
@Nonnull static Path mkdir(Path parent, String child)
Creates the specified child directory beneath the parent, if it does not already exist.
@Nonnull static Path mkdir(Path directory)
Creates the specified directory, if it does not already exist.
static void requireWithin(Path path, Path expectedParent)
Validates that the specified path is contained within the expectedParent.
@Nonnull static Path resolve(Path path, String first, String... more)
Simplifies resolving several subpaths in a single call.
static void setPermissions(SetFilePermissionRequest request)
Sets the file permissions according to the specifications provided in the request.
static long size(Path path)
Gets the size of the specified Path.
@Nonnull static String toString(Path path, Charset charset)
Reads the entire contents of the specified path using the provided character set.
@Nonnull static String toString(Path path)
Reads the entire contents of the specified path using the UTF-8 character set.
static long totalSize(Path path)
Calculates the total size of the specified path.
static void touch(Path path)
Creates the specified path, if it doesn't exist, or sets its last modified time if it does.
@Nonnull static Path write(Path path, String value, OpenOption... options)
Writes the provided value to the specified path using the UTF-8 character set.
@Nonnull static Path write(Path path, String value, Charset charset, OpenOption... options)
Writes the provided value to the specified path using the provided character set.
[Expand]
Inherited Methods
From class java.lang.Object

Public Methods

public static void cleanDirectory (Path directory)

Deletes any files or subdirectories in the specified directory and leaves the directory empty.

Parameters
directory the directory to clean
Throws
IOException if the path does not denote a directory, or the directory's contents could not be deleted

public static void deleteOnExit (Path path)

Registers the provided path to be deleted when the JVM exits.

Delete-on-exit is performed on a best-effort basis, and should not be relied upon as the primary solution for deleting files. Additionally, it only works for files and empty directories.

Parameters
path the path to register for deletion when the JVM exits
See Also

public static boolean deleteQuietly (Path path)

Recursively deletes the specified path, suppressing any IOExceptions that are thrown.

Parameters
path the path to delete, which may be a file or a directory
Returns
  • true if the path was deleted; otherwise, false if it did not exist or could not be deleted

public static void deleteRecursively (Path path)

Recursively deletes the specified path.

If the specified Path denotes a directory, the directory's contents are recursively deleted, depth-first, to empty the directory so it can be deleted. If any files or subdirectories can't be deleted, an exception will be thrown. Note that some files and subdirectories may have been deleted prior to the exception being thrown. Additionally, if the directory contains any symbolic links the links themselves are deleted, not their targets.

If the specified Path denotes a symbolic link, the symbolic link itself is deleted, rather than the target of the link. If the path is a symbolic link to a directory, that directory's contents are not removed.

If the specified Path denotes a file, it is deleted.

If the specified path does not exist, nothing happens and no exception is thrown.

Parameters
path the path to delete, which may be a file or a directory
Throws
IOException if the specified path cannot be deleted

public static long getLastModified (Path path)

Gets the last modified time for the specified Path, in milliseconds.

Like lastModified(), if the path does not exist or its attributes cannot be read, 0L is returned rather than throwing an exception. Use getLastModifiedTime(Path, LinkOption...) directly if an exception is desired.

Parameters
path the path to retrieve the last modified time for
Returns
  • the file's last modified time, in milliseconds, or 0L if the time could not be determined

public static boolean isAclSupported (Path path)

Gets the file store for the specified Path, and returns whether the file store supports ACLs. NTFS on Windows supports ACLs, but most Linux filesystems, and APFS and HFS+ on macOS, do not; they use POSIX instead.

Parameters
path the path to check, which is used to find the appropriate file store
Returns
  • true if the path's file store supports ACLs; otherwise, false
Throws
IOException if the file store cannot be determined for the specified path

public static boolean isPosixSupported (Path path)

Gets the file store for the specified Path, and returns whether the file store supports POSIX. Most Linux filesystems support POSIX, as do APFS and HFS+ on macOS, but, for example, NTFS on Windows does not; it uses ACLs instead.

Parameters
path the path to check, which is used to find the appropriate file store
Returns
  • true if the path's file store supports POSIX; otherwise, false
Throws
IOException if the file store cannot be determined for the specified path

public static boolean isWithin (Path path, Path expectedParent)

Returns true if the specified path is contained within the expectedParent. This should be used to ensure paths created with user-entered data don't "escape" the specified parent, to prevent path traversal attacks.

Parameters
path the path to validate
expectedParent the required parent directory
Returns
  • true if path is contained within expectedParent; otherwise, false
Throws
IllegalArgumentException if expectedParent does not exist or is not a directory
IOException if the real path for either of the provided paths cannot be resolved

@Nonnull public static Path mkdir (Path parent, String child)

Creates the specified child directory beneath the parent, if it does not already exist. If the path does exist, it is validated that it is a directory and not a file.

Parameters
parent the base path for creating the new directory
child the path beneath the parent for the new directory
Returns
  • the created directory
Throws
IllegalArgumentException if the child path is blank or empty
IllegalStateException if the child path already exists and is not a directory, or if the directory cannot be created
NullPointerException if the provided parent or child is null

@Nonnull public static Path mkdir (Path directory)

Creates the specified directory, if it does not already exist. If the path does exist, it is validated that it is a directory and not a file.

Parameters
directory the directory to create
Returns
  • the created directory
Throws
IllegalStateException if the directory path already exists and is not a directory, or if the directory cannot be created
NullPointerException if the provided directory is null

public static void requireWithin (Path path, Path expectedParent)

Validates that the specified path is contained within the expectedParent. This should be used to ensure paths created with user-entered data don't "escape" the specified parent, to prevent path traversal attacks.

Parameters
path the path to validate
expectedParent the required parent directory
Throws
IllegalArgumentException if expectedParent does not exist or is not a directory, or if path is not contained within it
IOException if the real path for either of the provided paths cannot be resolved

@Nonnull public static Path resolve (Path path, String first, String... more)

Simplifies resolving several subpaths in a single call.

Parameters
path the base path, from which subpaths should be resolved
first the first subpath, used to enforce that at least a single subpath is provided
more zero or more additional subpaths
Returns
  • the resolved path

public static void setPermissions (SetFilePermissionRequest request)

Sets the file permissions according to the specifications provided in the request. For Unix systems this will map the provided permissions to the corresponding PosixFilePermission. For Windows systems AclEntry ACL entries will be put together as follows:

  • Owner permissions: These will be applied to the Files#getOwner(Path, java.nio.file.LinkOption...) owner principal. Also, for convenience, they will be applied to the Administrator group (if it exists) since its members can override ACLs anyway
  • World permissions: These will be applied to the Everyone group.
  • Group permissions: These will be ignored. In POSIX-compliant OSes files and directories are associated with both a user and a group and the permission model explicitly provides for setting a group permission agnostic of the group's name. The ACL model used by Windows requires knowing the name of the group you want to provision.

Parameters
request describes the file permissions to set
Throws
IllegalArgumentException if the provided path does not exist, or exists and is not a regular file
IOException

public static long size (Path path)

Gets the size of the specified Path.

Like length(), if the path does not exist or its attributes cannot be read, 0L is returned rather than throwing an exception. Use size(Path) directly if an exception is desired.

Parameters
path the path to retrieve the size of
Returns
  • the file's size, or 0L if the size could not be determined

@Nonnull public static String toString (Path path, Charset charset)

Reads the entire contents of the specified path using the provided character set.

Callers should exercise caution when using this method, as it may result in reading a significant amount of data into memory. Where possible, callers are encouraged to stream file contents instead.

Parameters
path the path to read
charset the character set to use to decode the file's contents
Returns
  • the file's contents
Throws
IOException if the file cannot be read

@Nonnull public static String toString (Path path)

Reads the entire contents of the specified path using the UTF-8 character set.

Callers should exercise caution when using this method, as it may result in reading a significant amount of data into memory. Where possible, callers are encouraged to stream file contents instead.

Parameters
path the path to read
Returns
  • the file's contents
Throws
IOException if the file cannot be read

public static long totalSize (Path path)

Calculates the total size of the specified path.

If the specified Path denotes a directory, its contents are recursively traversed to compute its overall size. For directories containing a large number of files this can be quite slow, so it should be used with caution.

If the specified Path denotes a symbolic link, its size (generally the length of its target path) is reported. Symbolic links are not followed.

If the specified Path denotes a file, its size is reported.

Parameters
path the path to calculate a size for
Returns
  • the calculated size, or 0L if the size could not be calculated

public static void touch (Path path)

Creates the specified path, if it doesn't exist, or sets its last modified time if it does.

Parameters
path the path to create or set a last modification time for
Throws
IOException if a nonexistent file cannot be created, or if the last modification time cannot be set for an existing file

@Nonnull public static Path write (Path path, String value, OpenOption... options)

Writes the provided value to the specified path using the UTF-8 character set.

Parameters
path the path to write
value the value to write
options OpenOptions to control how the path is accessed
Returns
  • the provided path
Throws
IOException if the file cannot be written

@Nonnull public static Path write (Path path, String value, Charset charset, OpenOption... options)

Writes the provided value to the specified path using the provided character set.

Parameters
path the path to write
value the value to write
charset the character set to use to encode the value to bytes
options OpenOptions to control how the path is accessed
Returns
  • the provided path
Throws
IOException if the file cannot be written