Package com.globalmentor.io

Class Paths

java.lang.Object

com.globalmentor.io.Paths

public class Paths
extends java.lang.Object

Utility methods to manipulate Paths.

Author:

Magno Nascimento, Garret Wilson

Method Summary

Modifier and Type	Method	Description
static java.nio.file.Path	addExtension(java.nio.file.Path path, java.lang.String extension)	Adds the given extension to a path and returns the new path with the new extension.
static java.util.function.Predicate<java.nio.file.Path>	byBaseFilename(java.lang.String baseFilename)	Returns a predicate for matching paths by a base filename.
static java.util.function.Predicate<java.nio.file.Path>	byFilenamePattern(java.util.regex.Pattern filenamePattern)	Returns a predicate for a given filename pattern.
static java.nio.file.Path	changeBase(java.nio.file.Path path, java.nio.file.Path oldBasePath, java.nio.file.Path newBasePath)	Changes a path from one base to another.
static java.nio.file.Path	changeExtension(java.nio.file.Path path, java.lang.String extension)	Changes the last extension of a path's filename and returns a new path with the filename with the new extension.
static java.nio.file.Path	checkArgumentAbsolute(java.nio.file.Path path)	Ensures that a path is absolute.
static java.nio.file.Path	checkArgumentDirectory(java.nio.file.Path path)	Ensures that a path is a directory.
static void	checkArgumentDisjoint(java.nio.file.Path path1, java.nio.file.Path path2)	Ensures two paths are disjoint, that is, neither one is a subpath of (or equal to) the other.
static java.nio.file.Path	checkArgumentExists(java.nio.file.Path path)	Ensures that a path exists.
static java.nio.file.Path	checkArgumentRegularFile(java.nio.file.Path path, java.nio.file.LinkOption... options)	Ensures that a path is a regular file with opaque content.
static java.nio.file.Path	checkArgumentSubPath(java.nio.file.Path basePath, java.nio.file.Path subPath)	Ensures one path is a subpath of another; that is, they both share a base path with no backtracking.
static boolean	isDisjoint(java.nio.file.Path path1, java.nio.file.Path path2)	Determines whether two paths are disjoint, that is, neither one is a subpath of (or equal to) the other.
static boolean	isDotfile(java.nio.file.Path path)	Determines whether the path is for a so-called "dotfile", the filename of which begins with a dot but is neither "." or "..".
static boolean	isSubPath(java.nio.file.Path basePath, java.nio.file.Path subPath)	Determines whether one path is a subpath of another; that is, they both share a base path with no backtracking.
static java.nio.file.Path	removeExtension(java.nio.file.Path path)	Removes the last extension, if any, of a path's filename and returns a new filename with no extension.

Methods inherited from class java.lang.Object

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

Method Detail

changeBase

public static java.nio.file.Path changeBase(@Nonnull
                                            java.nio.file.Path path,
                                            java.nio.file.Path oldBasePath,
                                            java.nio.file.Path newBasePath)

Changes a path from one base to another. For example, /example/base1/test.txt changed from base /example/base1/ to base /example/base2/level2/ yields /example/base2/level2/test.txt. If the old and new base paths are the same, a path equal to the given path is returned.

The paths are normalized before the base is changed.

Parameters:

path - The path the base of which to change.

oldBasePath - The current base path.

newBasePath - The base path of the new path to return .

Returns:

A new path constructed by relativizing the path to the old base path and resolving the resulting path against the new base path.

Throws:

java.lang.IllegalArgumentException - if the old base path is not a base path (or the same path) of the given path.

See Also:

Path.relativize(Path), Path.resolveSibling(Path)

checkArgumentAbsolute

public static java.nio.file.Path checkArgumentAbsolute(@Nonnull
                                                       java.nio.file.Path path)

Ensures that a path is absolute.

Parameters:

path - The path to check to be absolute.

Returns:

The given path.

Throws:

java.lang.IllegalArgumentException - if the given path is not absolute.

See Also:

Path.isAbsolute()

checkArgumentDirectory

public static java.nio.file.Path checkArgumentDirectory(@Nonnull
                                                        java.nio.file.Path path)

Ensures that a path is a directory.

Parameters:

path - The path to check.

Returns:

The given path.

Throws:

java.lang.IllegalArgumentException - if the given path is not a directory.

See Also:

Files.isDirectory(Path, LinkOption...)

checkArgumentExists

public static java.nio.file.Path checkArgumentExists(@Nonnull
                                                     java.nio.file.Path path)

Ensures that a path exists.

Parameters:

path - The path to check.

Returns:

The given path.

Throws:

java.lang.IllegalArgumentException - if the given path does not exist.

See Also:

Files.exists(Path, LinkOption...)

checkArgumentRegularFile

public static java.nio.file.Path checkArgumentRegularFile(@Nonnull
                                                          java.nio.file.Path path,
                                                          @Nonnull
                                                          java.nio.file.LinkOption... options)

Ensures that a path is a regular file with opaque content.

The options array may be used to indicate how symbolic links are handled for the case that the file is a symbolic link. By default, symbolic links are followed and the file attribute of the final target of the link is read. If the option NOFOLLOW_LINKS is present then symbolic links are not followed.

Parameters:

path - The path to check.

options - The options indicating how symbolic links are handled.

Returns:

The given path.

Throws:

java.lang.IllegalArgumentException - if the given path is not a regular file.

See Also:

Files.isRegularFile(Path, LinkOption...)

checkArgumentSubPath

public static java.nio.file.Path checkArgumentSubPath(@Nonnull
                                                      java.nio.file.Path basePath,
                                                      @Nonnull
                                                      java.nio.file.Path subPath)

Ensures one path is a subpath of another; that is, they both share a base path with no backtracking. This method allows the paths to be identical.

Parameters:

basePath - The base path against which the other path will be compared.

subPath - The potential subpath.

Returns:

The given subpath.

Throws:

java.lang.IllegalArgumentException - if the given subpath is not a subpath of (or the same path as) the base path.

See Also:

isSubPath(Path, Path)

checkArgumentDisjoint

public static void checkArgumentDisjoint(@Nonnull
                                         java.nio.file.Path path1,
                                         @Nonnull
                                         java.nio.file.Path path2)

Ensures two paths are disjoint, that is, neither one is a subpath of (or equal to) the other.

Parameters:

path1 - The first path to compare.

path2 - The second path.

Throws:

java.lang.IllegalArgumentException - if the two path trees overlap.

See Also:

isDisjoint(Path, Path)

isDisjoint

public static boolean isDisjoint(@Nonnull
                                 java.nio.file.Path path1,
                                 @Nonnull
                                 java.nio.file.Path path2)

Determines whether two paths are disjoint, that is, neither one is a subpath of (or equal to) the other.

Parameters:

path1 - The first path to compare.

path2 - The second path.

Returns:

true if the two path trees do not overlap.

See Also:

isSubPath(Path, Path)

isSubPath

public static boolean isSubPath(@Nonnull
                                java.nio.file.Path basePath,
                                @Nonnull
                                java.nio.file.Path subPath)

Determines whether one path is a subpath of another; that is, they both share a base path with no backtracking. This method allows the paths to be identical.

Parameters:

basePath - The base path against which the other path will be compared.

subPath - The potential subpath.

Returns:

true if the given subpath is truly a subpath of (or the same path as) the base path.

isDotfile

public static boolean isDotfile(@Nonnull
                                java.nio.file.Path path)

Determines whether the path is for a so-called "dotfile", the filename of which begins with a dot but is neither "." or "..". This method does not make a distinction between files and directories.

Parameters:

path - The path to check.

Returns:

true if the path contains a filename that is considered a dotfile.

See Also:

Why do some file/folder names on Windows have a dot in front of them?, Dotfiles, Path.getFileName(), Filenames.isDotfileFilename(CharSequence)

addExtension

public static java.nio.file.Path addExtension(@Nonnull
                                              java.nio.file.Path path,
                                              @Nonnull
                                              java.lang.String extension)

Adds the given extension to a path and returns the new path with the new extension. The filename is not checked to see if it currently has an extension.

Implementation Specification:

This method delegates to Filenames.addExtension(String, String).

Parameters:

path - The path to which to add an extension.

extension - The extension to add.

Returns:

The path with the new extension.

Throws:

java.lang.IllegalArgumentException - If a filename is not present.

See Also:

Filenames.addExtension(String, String)

changeExtension

public static java.nio.file.Path changeExtension(@Nonnull
                                                 java.nio.file.Path path,
                                                 @Nullable
                                                 java.lang.String extension)

Changes the last extension of a path's filename and returns a new path with the filename with the new extension. If the filename does not currently have an extension, one will be added.

Implementation Specification:

This method delegates to Filenames.changeExtension(String, String).

Parameters:

path - The path for which an extension will be changed.

extension - The extension to set, or null if the extension should be removed.

Returns:

The path with the filename with the new extension.

Throws:

java.lang.IllegalArgumentException - If a filename is not present, or if the name is just a "/".

See Also:

Filenames.changeExtension(String, String)

removeExtension

public static java.nio.file.Path removeExtension(@Nonnull
                                                 java.nio.file.Path path)

Removes the last extension, if any, of a path's filename and returns a new filename with no extension.

Implementation Specification:

This method delegates to Filenames.removeExtension(String).

Parameters:

path - The path for which an extension will be removed.

Returns:

The path with the filename with no extension.

See Also:

Filenames.removeExtension(String)

byBaseFilename

public static java.util.function.Predicate<java.nio.file.Path> byBaseFilename(@Nonnull
                                                                              java.lang.String baseFilename)

Returns a predicate for matching paths by a base filename. Only paths that have a filename and which filename has the given base name (the given base name followed by one or more filename extensions) will pass the predicate.

Parameters:

baseFilename - The filename base name to match.

Returns:

A predicate for matching path filenames against the given base name.

See Also:

Filenames.getBaseFilenamePattern(String)

byFilenamePattern

public static java.util.function.Predicate<java.nio.file.Path> byFilenamePattern(@Nonnull
                                                                                 java.util.regex.Pattern filenamePattern)

Returns a predicate for a given filename pattern. Only paths that have a filename and which filename matches the given filename pattern will pass the predicate.

Parameters:

filenamePattern - The pattern for matching a filename.

Returns:

A predicate for matching path filenames against the given pattern.