com.github.fge.filesystem

Class MoreFiles

java.lang.Object

com.github.fge.filesystem.MoreFiles

@ParametersAreNonnullByDefault
public final class MoreFiles
extends Object

Utility class to complement JDK's Files

Unless otherwise noted, all methods in this class do not accept null arguments and will throw a NullPointerException if a null argument is passed to them.

Method Summary

Methods

Modifier and Type	Method and Description
static Path	changeMode(Path target, String instructions) Change POSIX file permissions of a file/directory using a chmod-like modification string
static void	copyRecursive(Path source, Path destination, RecursionMode mode, CopyOption... options) Recursively copy a source to a destination
static Path	createDirectories(Path dir, int mode) Create a new directory and all its missing parents with a set of absolute POSIX permissions
static Path	createDirectories(Path dir, String permissions) Create a new directory and all its missing parents with a set of absolute POSIX permissions
static Path	createDirectory(Path dir, int mode) Create a new directory with a set of absolute POSIX permissions
static Path	createDirectory(Path dir, String permissions) Create a new directory with a set of absolute POSIX permissions
static Path	createFile(Path path, int mode) Create a new file with a set of absolute POSIX permissions
static Path	createFile(Path path, String permissions) Create a new file with a set of absolute POSIX permissions
static void	deleteRecursive(Path victim, RecursionMode mode) Delete a path recursively
static Path	setMode(Path path, int mode) Change POSIX file permissions of a path
static Path	setMode(Path path, String permissions) Change POSIX file permissions of a path
static Path	touch(Path path) Update the last access and modification time of a file, or create a file

Methods inherited from class java.lang.Object

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

Method Detail

copyRecursive

public static void copyRecursive(Path source,
                 Path destination,
                 RecursionMode mode,
                 CopyOption... options)
                          throws IOException

Recursively copy a source to a destination

This command will work even across filesystems.

Note that this command only supports directories and files. If the source is a symbolic link, though, it will be followed (see Path.toRealPath(LinkOption...)). Any symbolic link encountered during a copy will trigger an UnsupportedOperationException.

There are two recursion modes: fail fast and keep going. In the first mode, copy will stop at the first error encountered and this error will be thrown. In the second mode, the copy will continue even if one or more errors are encountered and this method will throw a RecursiveCopyException. The list of exceptions which occured during the copy operations are available via Throwable.getSuppressed().

The only supported copy option is StandardCopyOption.REPLACE_EXISTING.

Parameters:

source - the source to copy (either a file or a directory)

destination - the destination

mode - the recursion mode (see description)

options - the set of copy options

Throws:

NoSuchFileException - source does not exist; or a parent of the destination does not exist when attempting to create the destination

UnsupportedOperationException - unsupported copy option; or a symbolic link was encountered during copy

FileAlreadyExistsException - StandardCopyOption.REPLACE_EXISTING was not specified, and the destination path already exists

DirectoryNotEmptyException - StandardCopyOption.REPLACE_EXISTING was specified but the destination path is a non empty directory

RecursiveCopyException - RecursionMode.KEEP_GOING was specified, however one or more errors were encountered during the copy operation

IOException - other I/O errors (access denied, etc)

See Also:

MorePaths.resolve(Path, Path), Files.walkFileTree(Path, FileVisitor), Files.copy(Path, Path, CopyOption...), FailFastCopyVisitor, KeepGoingCopyVisitor

deleteRecursive

public static void deleteRecursive(Path victim,
                   RecursionMode mode)
                            throws IOException

Delete a path recursively

Note that if a symbolic link is encountered, the symbolic link itself will be deleted. The target (if valid) is left untouched.

There are two modes of operation: fail fast and keep going. In the first mode, deletion will stop at the first error encountered and throw the exception. In the second mode, deletion will continue, and this method will throw a RecursiveDeletionException. The list of exceptions encountered during the deletion operation is available using Throwable.getSuppressed().

Parameters:

victim - the victim

mode - the recursion mode (see description)

Throws:

NoSuchFileException - victim does not exist (lucky you)

RecursiveDeletionException - RecursionMode.KEEP_GOING was specified, and one or more errors were encountered during the deletion operation (see description)

IOException - other I/O errors

See Also:

FailFastDeletionVisitor, KeepGoingDeletionVisitor, Files.delete(Path)

setMode

@Nonnull
public static Path setMode(Path path,
                   int mode)
                    throws IOException

Change POSIX file permissions of a path

This method will take an integer as an argument, just like the Unix chmod command, with one difference: you must prefix the integer mode with 0 so that Java read it as an octal number; that is, use setMode(myPath, 0644) and not setMode(myPath, 644).

Parameters:

path - the path to change

mode - the permissions to set, as an integer

Returns:

the path

Throws:

InvalidIntModeException - integer mode is not valid

UnsupportedOperationException - the filesystem associated with this path does not support POSIX file permissions

IOException - failed to set permissions

See Also:

Files.setPosixFilePermissions(Path, Set), PosixModes.intModeToPosix(int)

setMode

@Nonnull
public static Path setMode(Path path,
                   String permissions)
                    throws IOException

Change POSIX file permissions of a path

This command accepts a string representing the absolute POSIX permissions to set; for instance, setMode(thePath, "rw-r-----").

Only classical modes are supported; you cannot set the suid bit nor sticky bit using this command. Attempting to do so will throw an IllegalArgumentException.

Parameters:

path - the path to alter

permissions - the permissions to set, as a mode string

Returns:

the path

Throws:

IllegalArgumentException - invalid permission string

UnsupportedOperationException - the filesystem associated with this path does not support POSIX file permissions

IOException - failed to set the modes

See Also:

PosixFilePermissions.fromString(String), Files.setPosixFilePermissions(Path, Set)

createFile

@Nonnull
public static Path createFile(Path path,
                      String permissions)
                       throws IOException

Create a new file with a set of absolute POSIX permissions

Files.createFile(Path, FileAttribute[]) can be used to set initial POSIX file permissions; however, those permissions are altered by the process' umask.

This method is not "umask sensitive"; however, this means that unlike the command from Files, it is not atomic either: the file is first created, then the permissions are set.

Parameters:

path - the file to create

permissions - the permissions to create the file with, as a mode string

Returns:

the created path

Throws:

IllegalArgumentException - invalid mode string specified

UnsupportedOperationException - the filesystem associated with this path does not support POSIX file permissions

FileAlreadyExistsException - the path already exists

IOException - failed to create the file

See Also:

PosixFilePermissions.fromString(String), PosixFilePermissions.asFileAttribute(Set)

createFile

@Nonnull
public static Path createFile(Path path,
                      int mode)
                       throws IOException

Create a new file with a set of absolute POSIX permissions

Files.createFile(Path, FileAttribute[]) can be used to set initial POSIX file permissions; however, those permissions are altered by the process' umask.

This method is not "umask sensitive"; however, this means that unlike the command from Files, it is not atomic either: the file is first created, then the permissions are set.

Parameters:

path - the path to create

mode - the permissions to create the file with, as an integer

Returns:

the path

Throws:

InvalidIntModeException - invalid integer mode specified

UnsupportedOperationException - the filesystem associated with this path does not support POSIX file permissions

FileAlreadyExistsException - the path already exists

IOException - failed to create the file

See Also:

PosixModes.intModeToPosix(int), PosixFilePermissions.asFileAttribute(Set)

createDirectory

@Nonnull
public static Path createDirectory(Path dir,
                           String permissions)
                            throws IOException

Create a new directory with a set of absolute POSIX permissions

Files.createDirectory(Path, FileAttribute[])} can be used to set initial POSIX file permissions; however, those permissions are altered by the process' umask.

This method is not "umask sensitive"; however, this means that unlike the command from Files, it is not atomic either: the directory is first created, then the permissions are set.

Parameters:

dir - the directory to create

permissions - the permissions to create the directory with, as a mode string

Returns:

the created path

Throws:

IllegalArgumentException - invalid mode string specified

UnsupportedOperationException - the filesystem associated with this path does not support POSIX file permissions

FileAlreadyExistsException - the path already exists

IOException - failed to create the directory

See Also:

PosixFilePermissions.fromString(String), PosixFilePermissions.asFileAttribute(Set)

createDirectory

@Nonnull
public static Path createDirectory(Path dir,
                           int mode)
                            throws IOException

Create a new directory with a set of absolute POSIX permissions

Files.createDirectory(Path, FileAttribute[]) can be used to set initial POSIX file permissions; however, those permissions are altered by the process' umask.

This method is not "umask sensitive"; however, this means that unlike the command from Files, it is not atomic either: the directory is first created, then the permissions are set.

Parameters:

dir - the directory to create

mode - the permissions to create the directory with, as an integer

Returns:

the created path

Throws:

InvalidIntModeException - invalid integer mode specified

UnsupportedOperationException - the filesystem associated with this path does not support POSIX file permissions

FileAlreadyExistsException - the path already exists

IOException - failed to create the directory

See Also:

PosixModes.intModeToPosix(int), PosixFilePermissions.asFileAttribute(Set)

createDirectories

@Nonnull
public static Path createDirectories(Path dir,
                             String permissions)
                              throws IOException

Create a new directory and all its missing parents with a set of absolute POSIX permissions

Files.createDirectories(Path, FileAttribute[])} can be used to set initial POSIX file permissions; however, those permissions are altered by the process' umask.

This method is not "umask sensitive"; however, this means that unlike the command from Files, it is not atomic either: the directories are first created, then the permissions are set.

The permissions of already existing directories are not altered.

Parameters:

dir - the directory (and its missing parents) to create

permissions - the permissions to create the missing directories4 with, as a mode string

Returns:

the created path

Throws:

IllegalArgumentException - invalid mode string specified

UnsupportedOperationException - the filesystem associated with this path does not support POSIX file permissions

IOException - failed to create the directory

See Also:

PosixFilePermissions.fromString(String), PosixFilePermissions.asFileAttribute(Set)

createDirectories

@Nonnull
public static Path createDirectories(Path dir,
                             int mode)
                              throws IOException

Create a new directory and all its missing parents with a set of absolute POSIX permissions

Files.createDirectories(Path, FileAttribute[])} can be used to set initial POSIX file permissions; however, those permissions are altered by the process' umask.

This method is not "umask sensitive"; however, this means that unlike the command from Files, it is not atomic either: the directories are first created, then the permissions are set.

The permissions of already existing directories are not altered.

Parameters:

dir - the directory (and its missing parents) to create

mode - the permissions to create the missing directories with, as an integer

Returns:

the created path

Throws:

InvalidIntModeException - invalid integer mode specified

UnsupportedOperationException - the filesystem associated with this path does not support POSIX file permissions

IOException - failed to create the directory

See Also:

PosixModes.intModeToPosix(int), PosixFilePermissions.asFileAttribute(Set)

touch

@Nonnull
public static Path touch(Path path)
                  throws IOException

Update the last access and modification time of a file, or create a file

This command works similarly to the Unix touch command. If the given path does not exist, it is created (as an empty regular file); otherwise, its last access and modification time are changed to the current time.

Parameters:

path - the path to alter/create

Returns:

the altered/created path

Throws:

UnsupportedOperationException - the filesystem associated with the path, or the associated filesystem object associated with the path, does not support setting file times

IOException - cannot update the times and/or create the file; other reasons

See Also:

System.currentTimeMillis(), FileTime.fromMillis(long), Files.createFile(Path, FileAttribute[]), BasicFileAttributeView.setTimes(FileTime, FileTime, FileTime)

changeMode

@Nonnull
public static Path changeMode(Path target,
                      String instructions)
                       throws IOException

Change POSIX file permissions of a file/directory using a chmod-like modification string

The modification string is the same as chmod. For instance:

     MoreFiles.changeMode(path, "o-rwx,g+r,g-w");
 

See ModeParser.buildPermissionsSet(String) for the list of supported constructs.

Parameters:

target - the target to alter

instructions - the modification instructions

Returns:

the target path

Throws:

UnsupportedOperationException - the target's filesystem does not support getting/setting POSIX file permissions

IOException - failed to change permissions