| Modifier and Type | Method and Description |
|---|---|
static boolean |
canOpen(Path path)
An NFS-safe version of
Files.exists(Path, LinkOption...)} which actually opens the file to
verify its existence. |
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. |
static Path |
mkdir(Path directory)
Creates the specified
directory, if it does not already exist. |
static Path |
mkdir(Path parent,
String child)
Creates the specified
child directory beneath the parent, if it does not already exist. |
static String |
pathSafe(String value)
Creates a path-safe version of a string, replacing all potentially unsafe characters with a
- character. |
static void |
requireWithin(Path path,
Path expectedParent)
Validates that the specified path is contained within the
expectedParent. |
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)
|
static String |
toString(Path path)
Reads the entire contents of the specified path using the UTF-8 character set.
|
static String |
toString(Path path,
Charset charset)
Reads the entire contents of the specified path using the provided 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. |
static Path |
write(Path path,
String value,
Charset charset,
OpenOption... options)
Writes the provided value to the specified path using the provided character set.
|
static Path |
write(Path path,
String value,
OpenOption... options)
Writes the provided value to the specified path using the UTF-8 character set.
|
public static boolean canOpen(@Nonnull Path path)
Files.exists(Path, LinkOption...)} which actually opens the file to
verify its existence.
NFS can cache file stat information, which can lead to Files.exists(Path, LinkOption...)}
returning true for files that no longer exist when files are deleted on other nodes. The only
way to ensure the file really exists is to open it, which won't be fooled by cached stat information.
path - the path to the file to testtrue if the file can be opened; otherwise, false if notpublic static void cleanDirectory(@Nonnull Path directory) throws IOException
directory - the directory to cleanIOException - if the path does not denote a directory, or the directory's contents could not
be deletedpublic static void deleteOnExit(@Nonnull Path path)
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.
path - the path to register for deletion when the JVM exitsFile.deleteOnExit()public static boolean deleteQuietly(@Nonnull Path path)
Recursively deletes the specified path, suppressing any IOExceptions
that are thrown.path - the path to delete, which may be a file or a directorytrue if the path was deleted; otherwise, false if it did not exist or could not
be deletedpublic static void deleteRecursively(@Nonnull Path path) throws IOException
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.
path - the path to delete, which may be a file or a directoryIOException - if the specified path cannot be deletedpublic static long getLastModified(@Nonnull Path path)
last modified time for the specified Path, in
milliseconds.
Like File.lastModified(), if the path does not exist or its attributes cannot be read, 0L
is returned rather than throwing an exception. Use Files.getLastModifiedTime(java.nio.file.Path, java.nio.file.LinkOption...) directly if an
exception is desired.
path - the path to retrieve the last modified time for0L if the time could not be determinedpublic static boolean isAclSupported(@Nonnull Path path) throws IOException
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.path - the path to check, which is used to find the appropriate file storetrue if the path's file store supports ACLs; otherwise, falseIOException - if the file store cannot be determined for the specified pathpublic static boolean isPosixSupported(@Nonnull Path path) throws IOException
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.path - the path to check, which is used to find the appropriate file storetrue if the path's file store supports POSIX; otherwise, falseIOException - if the file store cannot be determined for the specified pathpublic static boolean isWithin(@Nonnull Path path, @Nonnull Path expectedParent) throws IOException
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.path - the path to validateexpectedParent - the required parent directorytrue if path is contained within expectedParent; otherwise, falseIllegalArgumentException - if expectedParent does not exist or is not a directoryIOException - if the real path for either of the provided paths cannot be resolved@Nonnull public static Path mkdir(@Nonnull Path directory)
directory, if it does not already exist. If the path does exist, it is validated
that it is a directory and not a file.directory - the directory to createIllegalStateException - if the directory path already exists and is not a directory, or if the
directory cannot be createdNullPointerException - if the provided directory is null@Nonnull public static Path mkdir(@Nonnull Path parent, @Nonnull String child)
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.parent - the base path for creating the new directorychild - the path beneath the parent for the new directoryIllegalArgumentException - if the child path is blank or emptyIllegalStateException - if the child path already exists and is not a directory, or if the
directory cannot be createdNullPointerException - if the provided parent or child is null@Nonnull public static String pathSafe(@Nonnull String value)
- character.value - the value to transform into a path safe stringpublic static void requireWithin(@Nonnull Path path, @Nonnull Path expectedParent) throws IOException
expectedParent. This should be used to
ensure paths created with user-entered data don't "escape" the specified parent, to prevent path traversal
attacks.path - the path to validateexpectedParent - the required parent directoryIllegalArgumentException - if expectedParent does not exist or is not a directory, or if
path is not contained within itIOException - if the real path for either of the provided paths cannot be resolved@Nonnull public static Path resolve(@Nonnull Path path, @Nonnull String first, @Nonnull String... more)
resolving several subpaths in a single call.path - the base path, from which subpaths should be resolvedfirst - the first subpath, used to enforce that at least a single subpath is providedmore - zero or more additional subpathspublic static void setPermissions(@Nonnull SetFilePermissionRequest request) throws IOException
request.
For Unix systems this will map the provided permissions to the corresponding PosixFilePermission.
For Windows systems ACL entries will be put together as follows:
Owner permissions: These will be applied to the
owner principal. Also, for convenience,
they will be applied to the Administrator group (if it exists) since its members can override
ACLs anywayWorld 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.request - describes the file permissions to setIllegalArgumentException - if the provided path does not exist,
or exists and is not a regular fileIOException - if the real path for either of the provided paths cannot be resolvedpublic static long size(@Nonnull Path path)
size of the specified Path.
Like File.length(), if the path does not exist or its attributes cannot be read, 0L is
returned rather than throwing an exception. Use Files.size(java.nio.file.Path) directly if an exception is desired.
path - the path to retrieve the size of0L if the size could not be determinedpublic static long totalSize(@Nonnull Path 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.
path - the path to calculate a size for0L if the size could not be calculatedpublic static void touch(@Nonnull Path path) throws IOException
Creates the specified path, if it doesn't exist, or
sets its last modified time if it does.path - the path to create or set a last modification time forIOException - if a nonexistent file cannot be created, or if the last modification time cannot be
set for an existing file@Nonnull public static String toString(@Nonnull Path path) throws IOException
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.
path - the path to readIOException - if the file cannot be read@Nonnull public static String toString(@Nonnull Path path, @Nonnull Charset charset) throws IOException
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.
path - the path to readcharset - the character set to use to decode the file's contentsIOException - if the file cannot be read@Nonnull public static Path write(@Nonnull Path path, @Nonnull String value, @Nonnull OpenOption... options) throws IOException
path - the path to writevalue - the value to writeoptions - OpenOptions to control how the path is accessedIOException - if the file cannot be written@Nonnull public static Path write(@Nonnull Path path, @Nonnull String value, @Nonnull Charset charset, @Nonnull OpenOption... options) throws IOException
path - the path to writevalue - the value to writecharset - the character set to use to encode the value to bytesoptions - OpenOptions to control how the path is accessedIOException - if the file cannot be writtenCopyright © 2022 Atlassian. All rights reserved.