extensions.java.io.File

Class ManFileExt

java.lang.Object

extensions.java.io.File.ManFileExt

public class ManFileExt
extends Object

A collection of useful extensions to java.io.File. Partially adapted from kotlin.io.files.Utils.kt

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ManFileExt.OnErrorAction Enum that can be used to specify behaviour of the `copyRecursively()` function in exceptional conditions.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_BUFFER_SIZE

Constructor Summary

Constructors

Constructor and Description
ManFileExt()

Method Summary

Modifier and Type	Method and Description
static boolean	copyRecursively(File thiz, File target) Copies this file with all its children to the specified destination [target] path.
static boolean	copyRecursively(File thiz, File target, boolean overwrite, java.util.function.BiFunction<File,IOException,ManFileExt.OnErrorAction> onError)
static boolean	copyRecursively(File thiz, File target, boolean overwrite, java.util.function.BiFunction<File,IOException,ManFileExt.OnErrorAction> onError, java.util.function.Predicate<File> filter)
static boolean	copyRecursively(File thiz, File target, java.util.function.Predicate<File> filter)
static File	copyTo(File thiz, File target) Copies this file to the given [target] file.
static File	copyTo(File thiz, File target, boolean overwrite, int bufferSize)
static File	createTempDir() Creates an empty directory in the specified [directory], using the given [prefix] and [suffix] to generate its name.
static File	createTempDir(String prefix, String suffix, File directory)
static boolean	deleteRecursively(File thiz) Delete this file with all its children.
static boolean	endsWith(File thiz, File other) Determines whether this file path ends with the path of [other] file.
static boolean	endsWith(File thiz, String other) Determines whether this file belongs to the same root as [other] and ends with all components of [other] in the same order.
static String	getExtension(File thiz) Returns the extension of this file (not including the dot), or an empty string if it doesn't have one.
static boolean	isRooted(File thiz) Determines whether this file has a root or it represents a relative path.
static String	nameWithoutExtension(File thiz) Returns file's name without an extension.
static File	normalize(File thiz) Removes all .
static List<File>	normalize(List<File> segments)
static File	relativeTo(File thiz, File base) Calculates the relative path for this file from [base] file.
static File	relativeToOrNull(File thiz, File base) Calculates the relative path for this file from [base] file.
static File	relativeToOrSelf(File thiz, File base) Calculates the relative path for this file from [base] file.
static File	resolve(File thiz, File relative) Adds [relative] file to this, considering this as a directory.
static File	resolve(File thiz, String relative) Adds [relative] name to this, considering this as a directory.
static File	resolveSibling(File thiz, File relative) Adds [relative] file to this parent directory.
static File	resolveSibling(File thiz, String relative) Adds [relative] name to this parent directory.
static String	slashPath(File thiz) Returns [path] of this File using the invariant separator '/' to separate the names in the name sequence.
static boolean	startsWith(File thiz, File other) Determines whether this file belongs to the same root as [other] and starts with all components of [other] in the same order.
static boolean	startsWith(File thiz, String other) Determines whether this file belongs to the same root as [other] and starts with all components of [other] in the same order.
static FilePathComponents	toComponents(File thiz) Splits the file into path components (the names of containing directories and the name of the file itself) and returns the resulting collection of components.
static String	toRelativeString(File thiz, File base) Calculates the relative path for this file from [base] file.
static FileTreeWalk	walk(File thiz, FileTreeWalk.FileWalkDirection direction) Gets an iterable for visiting this directory and all its content.
static FileTreeWalk	walkBottomUp(File thiz) Gets a sequence for visiting this directory and all its content in bottom-up order.
static FileTreeWalk	walkTopDown(File thiz) Gets a sequence for visiting this directory and all its content in top-down order.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_BUFFER_SIZE

public static final int DEFAULT_BUFFER_SIZE

See Also:

Constant Field Values

Constructor Detail

ManFileExt

public ManFileExt()

Method Detail

createTempDir

public static File createTempDir()
                          throws IOException

Creates an empty directory in the specified [directory], using the given [prefix] and [suffix] to generate its name.

If [prefix] is not specified then some unspecified name will be used. If [suffix] is not specified then ".tmp" will be used. If [directory] is not specified then the default temporary-file directory will be used.

Returns:

a file object corresponding to a newly-created directory.

Throws:

IOException - in case of input/output error.

IllegalArgumentException - if [prefix] is shorter than three symbols.

createTempDir

public static File createTempDir(String prefix,
                                 String suffix,
                                 File directory)
                          throws IOException

Throws:

IOException

getExtension

public static String getExtension(File thiz)

Returns the extension of this file (not including the dot), or an empty string if it doesn't have one.

slashPath

public static String slashPath(File thiz)

Returns [path] of this File using the invariant separator '/' to separate the names in the name sequence.

nameWithoutExtension

public static String nameWithoutExtension(File thiz)

Returns file's name without an extension.

toRelativeString

public static String toRelativeString(File thiz,
                                      File base)

Calculates the relative path for this file from [base] file. Note that the [base] file is treated as a directory. If this file matches the [base] file, then an empty string will be returned.

Returns:

relative path from [base] to this.

Throws:

IllegalArgumentException - if this and base paths have different roots.

relativeTo

public static File relativeTo(File thiz,
                              File base)

Calculates the relative path for this file from [base] file. Note that the [base] file is treated as a directory. If this file matches the [base] file, then a [File] with empty path will be returned.

Returns:

File with relative path from [base] to this.

Throws:

IllegalArgumentException - if this and base paths have different roots.

relativeToOrSelf

public static File relativeToOrSelf(File thiz,
                                    File base)

Calculates the relative path for this file from [base] file. Note that the [base] file is treated as a directory. If this file matches the [base] file, then a [File] with empty path will be returned.

Returns:

File with relative path from [base] to this, or `this` if this and base paths have different roots.

relativeToOrNull

public static File relativeToOrNull(File thiz,
                                    File base)

Calculates the relative path for this file from [base] file. Note that the [base] file is treated as a directory. If this file matches the [base] file, then a [File] with empty path will be returned.

Returns:

File with relative path from [base] to this, or `null` if this and base paths have different roots.

toComponents

public static FilePathComponents toComponents(File thiz)

Splits the file into path components (the names of containing directories and the name of the file itself) and returns the resulting collection of components.

isRooted

public static boolean isRooted(File thiz)

Determines whether this file has a root or it represents a relative path.

Returns `true` when this file has non-empty root.

copyTo

public static File copyTo(File thiz,
                          File target)

Copies this file to the given [target] file.

If some directories on a way to the [target] are missing, they will be created. If the [target] file already exists, this function will fail unless [overwrite] argument is set to `true`.

When [overwrite] is `true` and [target] is a directory, it is replaced only if it is empty.

If this file is a directory, it is copied without its content, i.e. an empty [target] directory is created. If you want to copy directory including its contents, use [copyRecursively].

The operation doesn't preserve copied file attributes such as creation/modification date, permissions, etc.

Parameters:

overwrite - `true` if destination overwrite is allowed.

bufferSize - the buffer size to use when copying.

Returns:

the [target] file.

Throws:

NoSuchFileException - if the source file doesn't exist.

FileAlreadyExistsException - if the destination file already exists and 'rewrite' argument is set to `false`.

IOException - if any errors occur while copying.

copyTo

public static File copyTo(File thiz,
                          File target,
                          boolean overwrite,
                          int bufferSize)

copyRecursively

public static boolean copyRecursively(File thiz,
                                      File target)

Copies this file with all its children to the specified destination [target] path. If some directories on the way to the destination are missing, they will be created.

If this file path points to a single file, it will be copied to a file with the path [target]. If this file path points to a directory, its children will be copied to a directory with the path [target].

If the [target] already exists, it will be deleted before copying when the [overwrite] parameter permits so.

The operation doesn't preserve copied file attributes such as creation/modification date, permissions, etc.

If any errors occur during the copying, further actions will depend on the result of the call to `onError(File, IOException)` function, that will be called with arguments, specifying the file that caused the error and the exception itself. By default this function rethrows exceptions.

Exceptions that can be passed to the `onError` function:

- NoSuchFileException - if there was an attempt to copy a non-existent file - FileAlreadyExistsException - if there is a conflict - AccessDeniedException - if there was an attempt to open a directory that didn't succeed. - IOException - if some problems occur when copying.

Note that if this function fails, partial copying may have taken place.

Returns:

`false` if the copying was terminated, `true` otherwise.

copyRecursively

public static boolean copyRecursively(File thiz,
                                      File target,
                                      java.util.function.Predicate<File> filter)

copyRecursively

public static boolean copyRecursively(File thiz,
                                      File target,
                                      boolean overwrite,
                                      java.util.function.BiFunction<File,IOException,ManFileExt.OnErrorAction> onError)

copyRecursively

public static boolean copyRecursively(File thiz,
                                      File target,
                                      boolean overwrite,
                                      java.util.function.BiFunction<File,IOException,ManFileExt.OnErrorAction> onError,
                                      java.util.function.Predicate<File> filter)

walk

public static FileTreeWalk walk(File thiz,
                                FileTreeWalk.FileWalkDirection direction)

Gets an iterable for visiting this directory and all its content.

Parameters:

direction - walk direction, top-down (by default) or bottom-up.

walkTopDown

public static FileTreeWalk walkTopDown(File thiz)

Gets a sequence for visiting this directory and all its content in top-down order. Depth-first search is used and directories are visited before all their files.

walkBottomUp

public static FileTreeWalk walkBottomUp(File thiz)

Gets a sequence for visiting this directory and all its content in bottom-up order. Depth-first search is used and directories are visited after all their files.

deleteRecursively

public static boolean deleteRecursively(File thiz)

Delete this file with all its children. Note that if this operation fails then partial deletion may have taken place.

Returns:

`true` if the file or directory is successfully deleted, `false` otherwise.

startsWith

public static boolean startsWith(File thiz,
                                 File other)

Determines whether this file belongs to the same root as [other] and starts with all components of [other] in the same order. So if [other] has N components, first N components of `this` must be the same as in [other].

Returns:

`true` if this path starts with [other] path, `false` otherwise.

startsWith

public static boolean startsWith(File thiz,
                                 String other)

Determines whether this file belongs to the same root as [other] and starts with all components of [other] in the same order. So if [other] has N components, first N components of `this` must be the same as in [other].

Returns:

`true` if this path starts with [other] path, `false` otherwise.

endsWith

public static boolean endsWith(File thiz,
                               File other)

Determines whether this file path ends with the path of [other] file.

If [other] is rooted path it must be equal to this. If [other] is relative path then last N components of `this` must be the same as all components in [other], where N is the number of components in [other].

Returns:

`true` if this path ends with [other] path, `false` otherwise.

endsWith

public static boolean endsWith(File thiz,
                               String other)

Determines whether this file belongs to the same root as [other] and ends with all components of [other] in the same order. So if [other] has N components, last N components of `this` must be the same as in [other]. For relative [other], `this` can belong to any root.

Returns:

`true` if this path ends with [other] path, `false` otherwise.

normalize

public static File normalize(File thiz)

Removes all . and resolves all possible .. in this file name. For instance, `File("/foo/./bar/gav/../baaz").normalize()` is `File("/foo/bar/baaz")`.

Returns:

normalized pathname with . and possibly .. removed.

normalize

public static List<File> normalize(List<File> segments)

resolve

public static File resolve(File thiz,
                           File relative)

Adds [relative] file to this, considering this as a directory. If [relative] has a root, [relative] is returned back. For instance, `File("/foo/bar").resolve(File("gav"))` is `File("/foo/bar/gav")`. This function is complementary with [relativeTo], so `f.resolve(g.relativeTo(f)) == g` should be always `true` except for different roots case.

Returns:

concatenated this and [relative] paths, or just [relative] if it's absolute.

resolve

public static File resolve(File thiz,
                           String relative)

Adds [relative] name to this, considering this as a directory. If [relative] has a root, [relative] is returned back. For instance, `File("/foo/bar").resolve("gav")` is `File("/foo/bar/gav")`.

Returns:

concatenated this and [relative] paths, or just [relative] if it's absolute.

resolveSibling

public static File resolveSibling(File thiz,
                                  File relative)

Adds [relative] file to this parent directory. If [relative] has a root or this has no parent directory, [relative] is returned back. For instance, `File("/foo/bar").resolveSibling(File("gav"))` is `File("/foo/gav")`.

Returns:

concatenated this.parent and [relative] paths, or just [relative] if it's absolute or this has no parent.

resolveSibling

public static File resolveSibling(File thiz,
                                  String relative)

Adds [relative] name to this parent directory. If [relative] has a root or this has no parent directory, [relative] is returned back. For instance, `File("/foo/bar").resolveSibling("gav")` is `File("/foo/gav")`.

Returns:

concatenated this.parent and [relative] paths, or just [relative] if it's absolute or this has no parent.