saker.build Documentation TaskDoc JavaDoc Packages
public final class SakerPath implements Comparable<SakerPath>, Externalizable, Cloneable
Immutable class representing an absolute or relative file path.

An instance consists of a root and given path names under that root. If the root is null then the path is relative. The root can be one of the following format:

  • Simple "/" character as a String. Matching the Unix root drive semantics.
  • A root string in a drive format similar to Windows semantics. The drive name can have multiple characters, and ends with the colon ':' character. The drive letters are lowercase and in the range of 'a' - 'z'. E.g.: "c:", "drive:".
    When a path is constructed, the root name is always normalized to a lowercase format.

When parsing paths, they can contain the "." and ".." path names which represent the current and the parent paths accordingly. Absolute paths cannot escape their root name using the ".." path name. The paths are normalized during their construction.

Relative paths can contain only the special ".." name at the start of it. Intermediate ".." names are normalized during resolution.

Absolute paths will not contains any of the above special path names.
"." names are never present in any path as they are omitted during construction.

All methods in this class work in a case-sensitive manner unless indicated accordingly.

When an instance is constructed all backslash characters are treated as forward slash.

Examples for paths:

  • /home/User
  • c:/Users/User
  • drive:
  • Relative: dir/child
  • Relative: ../sibling
  • Relative: ../in/parent/tree
  • Automatically normalized relative: some/../directory/tree will be normalized to directory/tree
Nested types
public static final class
SakerPath builder.
Fields
public static final SakerPath
Single instance for an empty path.
public static final SakerPath
Single instance for the first absolute path that is ordered by the Comparable contract of this class.
public static final SakerPath
Single instance for the first path that is ordered by the Comparable contract of this class which root is not the slash drive.
public static final SakerPath
Single instance for a relative parent path.
public static final SakerPath
Singleton instance that represents the slash root.
public static final String
Path name representing the forward slash root.
Constructors
public
Methods
public SakerPath
Appends the parameter relative path to this path.
public static Builder
Creates a relative path builder.
public static Builder
Creates a path builder with the given root.
public SakerPath
Shallow clones this path instance.
public int
Compares this path to the parameter.
public int
Compares this path to the argument in a case-insensitive manner.
public boolean
Check if the parameter is a path and represents the same location.
public boolean
Equals method with already known type of the parameter.
public boolean
Check if this path equals the argument in a case-insensitive manner.
public SakerPath
Forces the path to be relative by removing any root if present.
public int
Counts how many common starting path names does this and the parameter have.
public SakerPath
Returns the common path of this and the parameter path.
public String
Gets the last path name of this path if it represents a valid file name.
public String
Gets the last path name in this path.
public String
getName(int index)
Gets the name at the specified index.
public String[]
Returns an array copy of the path names of this path.
public int
Gets the path name count in this path.
public List<String>
Returns an unmodifiable list of this path's names.
public List<String>
getNameList(int startindex, int endindex)
Returns an unmodifiable list of this path's names in the given range.
public SakerPath
Returns the path which represents the parent of this path or null if it cannot exist.
public String[]
Returns an array copy of the optional root and path names of this path.
public List<String>
Returns an unmodifiable list of this path's optional root and path names of this path.
public String
Gets the root for this path.
public SakerPath
Returns a path that contains only the root of this path.
public int
Returns a hash code value for the object.
public int
Finds the first occurence of the parameter path name in this path.
public boolean
Returns true if the path is absolute.
public boolean
Checks if the argument path represents a location that is under this path.
public boolean
Returns if this is relative and resolving it against an other path will not escape to its parent path.
public boolean
Returns true if the path is relative.
public boolean
Checks if the parameter path can be relativized against this path.
public static boolean
Checks if the parameter character can be considered as a path separator slash character.
public static boolean
Checks if the parameter is a valid path name.
public static boolean
Checks if the parameter has a valid root name format.
public Iterable<String>
Creates an iterable that creates iterators for the path names in this instance.
public ListIterator<String>
Creates an iterator for the path names in this instance.
public ListIterator<String>
nameIterator(int index)
Creates an iterator for the path names starting at a given index.
public SakerPath
Returns the next sibling path in the natural order specified by compareTo(SakerPath).
public SakerPath
Returns the first subpath that starts with this path specified by the natural order.
public static String
Normalizes the parameter root for unified representation.
public Iterable<String>
Creates an iterable that creates iterators for the root and path names in this instance.
public Iterator<String>
Creates an iterator for the root and path names in this instance.
public SakerPath
Promotes the first path name of this relative path to construct an absolute one.
public void
The object implements the readExternal method to restore its contents by calling the methods of DataInput for primitive types and readObject for objects, strings and arrays.
public SakerPath
Relativizes this path against the parameter.
public SakerPath
Constructs a path which has the parameter as root.
public SakerPath
Resolves the given path names against this path.
public SakerPath
Resolves the given path names against this path.
public SakerPath
Resolves the given relative argument against this path.
public SakerPath
Resolves the given relative argument against this path.
public SakerPath
resolve(String... paths)
Resolves the given path names against this path.
public SakerPath
Resolves the path to a sibling name.
public static SakerPath
Creates a relative path with a single path name.
public boolean
Checks if this path starts with the parameter path.
public SakerPath
subPath(int beginindex)
Creates a relative subpath starting from the given index.
public SakerPath
subPath(int beginindex, int endindex)
Creates a relative subpath in the given range.
public SakerPath
subPath(String root, int beginindex)
Creates a subpath starting from the given index with a specific root.
public SakerPath
subPath(String root, int beginindex, int endindex)
Creates a subpath in the given range with a specific root.
public SakerPath
Converts this path to an all lowercase representation.
public SakerPath
Converts this path to an all lowercase representation using the specified locale.
public String
Converts this path to a String.
public String
Converts this path to string, but does not include the root if any.
public SakerPath
Tries to relativize this path against the parameter.
public SakerPath
Tries to resolve the parameter path against this path.
public static SakerPath
Parses the parameter String and creates a path.
public static SakerPath
Creates a path from the given path argument.
public static SakerPath
valueOf(SakerPath relativeresolve, String path)
Parses the parameter String and resolves it against the parameter path is it is relative.
public void
The object implements the writeExternal method to save its contents by calling the methods of DataOutput for its primitive values or calling the writeObject method of ObjectOutput for objects, strings, and arrays.
public static final SakerPath EMPTY
Single instance for an empty path.
public static final SakerPath FIRST_ABSOLUTE_PATH
Single instance for the first absolute path that is ordered by the Comparable contract of this class.

All relative paths are ordered before this instance in the natural order.

Single instance for the first path that is ordered by the Comparable contract of this class which root is not the slash drive.

All relative paths and all slash root paths are ordered before this instance in the natural order.

This instance does not represent a valid path for use.

public static final SakerPath PARENT
Single instance for a relative parent path.
public static final SakerPath PATH_SLASH
Singleton instance that represents the slash root.
public static final String ROOT_SLASH = "/"
Path name representing the forward slash root.
public SakerPath()
For Externalizable.

Creates the empty path.

Appends the parameter relative path to this path.

Appending differs from the resolving only that the resulting path is not normalized. It is the responsibility of the user to provide a path that is forward relative.

otherThe parameter to append.
The first path appended with the parameter.
InvalidPathFormatExceptionIf the parameter is not relative, or contains semantically specific path names (E.g. "..").
public static Builder builder()
Creates a relative path builder.
The builder.
public static Builder builder(String root) throws InvalidPathFormatException
Creates a path builder with the given root.

The parameter might be null to construct a relative path.

rootThe root to use for the constructing builder.
The builder.
InvalidPathFormatExceptionIf the root has an invalid format.
public SakerPath clone()
Shallow clones this path instance.

All the backing fields are the same for the new instance as this one.

a clone of this instance.
public int compareTo(SakerPath o)
Compares this path to the parameter.

Relative paths are ordered first.

This method compares the root and the path names sequentially. Shorter paths ordered first.

The method works in a case-sensitive manner.

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.
Compares this path to the argument in a case-insensitive manner.
oThe path to compare against.
A negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.
public boolean equals(Object obj)
Check if the parameter is a path and represents the same location.

This method works in a case-sensitive manner.

true if this object is the same as the obj argument; false otherwise.
public boolean equals(SakerPath path)
Equals method with already known type of the parameter.
pathThe object to check equality against.
If the two paths equal.
public boolean equalsIgnoreCase(SakerPath path)
Check if this path equals the argument in a case-insensitive manner.
pathThe path to check case-insensitive equality for.
true if the paths equal in a case-insensitive manner.
Forces the path to be relative by removing any root if present.

This method can be used to construct a path which contains the same names as this but has no root assigned.

The resulting path will be relative.

The method returns this if this is already relative.

A forced relativized path.
public int getCommonNameCount(SakerPath other)
Counts how many common starting path names does this and the parameter have.

This method computes how many common starting path names does this path have with the parameter.

If the paths have different roots, then the result will be -1.

Else this method will return the number of matching path names at the start of both paths.

otherThe path to compare with.
-1 if the roots differ, else common starting path name count.
Returns the common path of this and the parameter path.

This works in the same way as getCommonNameCount(SakerPath), but will extract the common part of both paths as a result.

If the roots differ then the result will be null.

otherThe path to compare with.
The common sub path or null if the roots differ.
Gets the last path name of this path if it represents a valid file name.

The last path name represents the file name of the location represented by this path.

If this path is relative and only consists of ".." names then the result will be null as there is no explicit file name defined.

The file name for this path or null if the file name cannot be determined.
Gets the last path name in this path.

This method is similar to getFileName(), but does not examine the returned name if it is actually a valid file name. If the last name is ".." then it will be returned.

The last path name or null if this path contains none.
public String getName(int index) throws IndexOutOfBoundsException
Gets the name at the specified index.
indexThe index of the requested path name.
The path name at index.
IndexOutOfBoundsExceptionif the index is out of range
public String[] getNameArray()
Returns an array copy of the path names of this path.
The names of this path in an array.
public int getNameCount()
Gets the path name count in this path.
The name count.
Returns an unmodifiable list of this path's names.
An unmodifiable list of path names.
public List<String> getNameList(int startindex, int endindex) throws IndexOutOfBoundsException
Returns an unmodifiable list of this path's names in the given range.
startindexThe start index (inclusive).
endindexThe end index (exclusive).
An unmodifiable list of path names.
IndexOutOfBoundsExceptionIf any if the indices are out of range.
Returns the path which represents the parent of this path or null if it cannot exist.

The parent of a path is determined by resolving the ".." path name against it. If the parent path cannot exist (e.g. this is a simple root without subfolders like "/" or "c:") this function returns null.

Relative paths always have parent paths.

The parent path or null if it cannot exist.
public String[] getPathArray()
Returns an array copy of the optional root and path names of this path.

The root name will be the first element in the array if the path is absolute.

If the path is relative this method returns the same as getNameArray().

The array containing the root (optional) and path names.
Returns an unmodifiable list of this path's optional root and path names of this path.
An unmodifiable list of path components.
public String getRoot()
Gets the root for this path.
The root of this path or null if relative.
Returns a path that contains only the root of this path.

The resulting path will contain the root of this path and have no path names assigned. If this path is already contains no path names the result is this.

If this path is relative then the result will be the empty path instance.

The path that contains only the root of this path.
public int hashCode()
Overridden from: Object
Returns a hash code value for the object. This method is supported for the benefit of hash tables such as those provided by HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the Object.equals(Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the Java™ programming language.)

a hash code value for this object.
public int indexOfName(String pathname)
Finds the first occurence of the parameter path name in this path.
pathnameThe path name to find.
The index of the path name if found or -1 if not.
public boolean isAbsolute()
Returns true if the path is absolute.

It will only be true if getRoot() is null.

true if the path is absolute.
public boolean isChildPath(SakerPath other)
Checks if the argument path represents a location that is under this path.

This method works in the same way as startsWith(SakerPath), but in reverse order.

otherThe path to test.
true if the argument is a child path of this.
public boolean isForwardRelative()
Returns if this is relative and resolving it against an other path will not escape to its parent path.

This method returns true if resolving this path against any given path X to result R, then R.startsWith(X) will return true.

Examples by resolving against c:/Users:

  • Forward relative: dir/subdir -> c:/Users/dir/subdir
  • Forward relative: dir/.. -> c:/Users
  • Forward relative: dir/../otherdir -> c:/Users/otherdir
  • Not forward relative: ../dir -> c:/dir
true if this path is forward relative.
public boolean isRelative()
Returns true if the path is relative.

It will only be true if getRoot() is not null.

true if the path is relative.
public boolean isRelativizable(SakerPath other)
Checks if the parameter path can be relativized against this path.

This method requires the following conditions to be met to return true:

  • Both path have the same root.
  • If the paths are relative then this path must have less or equal number of ".." path names at the start of it than the parameter.

    E.g. "../dir" is not relativizable against "some/otherdir" as a path cannot be constructed in order to navigate outside of the ".." name at the start.

otherThe path to check relativization against.
true if the paths are relativizable.
public static boolean isSlashCharacter(char c)
Checks if the parameter character can be considered as a path separator slash character.
cThe character to test.
true if the parameter equals '\\' or '/'.
public static boolean isValidPathName(CharSequence n)
Checks if the parameter is a valid path name.

Returns true if it doesn't contain any directory separators and colons (':').

nThe name to check.
true if it is a valid path name.
public static boolean isValidRootName(CharSequence r)
Checks if the parameter has a valid root name format.

Valid root name formats are:

  • Single forward ('/') or backward ('\\') slash character.
  • Drive format matching the following regex: "[a-zA-Z]+:"
rThe root name to check.
true if it is a valid root name.
Creates an iterable that creates iterators for the path names in this instance.

The iterable will not contain the root name. See pathIterable() for including the root too.

An unmodifiable iterable.
Creates an iterator for the path names in this instance.
An unmodifiable iterator.
public ListIterator<String> nameIterator(int index)
Creates an iterator for the path names starting at a given index.

The iterator will not contain the root name. See pathIterator() for including the root too.

indexThe index to start the iterator form.
An unmodifiable iterator.
Returns the next sibling path in the natural order specified by compareTo(SakerPath).

It is ensured that this.compareTo(result) < 0 is always true. Any other path that compares greater than this and less than the result of this function is a subpath of this path.

The resulting path is not semantically correct, it should not be used with files, and should be restricted for ordering comparisons.

The next path in natural order.
Returns the first subpath that starts with this path specified by the natural order.

It is ensured that this.compareTo(result) < 0 is always true.

The resulting path is not semantically correct, it should not be used with files, and should be restricted for ordering comparisons.

The next path in natural order.
Normalizes the parameter root for unified representation.

If the parameter is "\\" then it will return "/".

In any other case the parameter will be converted to lowercase and any trailing slashes will be removed. It is ensured that the parameter is in a valid root format defined by this class.

rootThe root to normalize.
The normalized root.
NullPointerExceptionIf the argument is null.
InvalidPathFormatExceptionIf the root format is invalid.
Creates an iterable that creates iterators for the root and path names in this instance.
An unmodifiable iterable.
Creates an iterator for the root and path names in this instance.

If this path is absolute then the first element will be the root name.

If this path is relative this call is the same as nameIterator();

An unmodifiable iterator.
Promotes the first path name of this relative path to construct an absolute one.

This method takes the first path name in this path and promotes it to be the root of the newly constructed one. The new root will be removed from the list of path names and will not be duplicated.

The promoted path.
IllegalStateExceptionIf this path is not relative or empty.
InvalidPathFormatExceptionIf the first path name is not a valid root name.
Overridden from: Externalizable
The object implements the readExternal method to restore its contents by calling the methods of DataInput for primitive types and readObject for objects, strings and arrays. The readExternal method must read the values in the same sequence and with the same types as were written by writeExternal.
inthe stream to read data from in order to restore the object
IOExceptionif I/O errors occur
ClassNotFoundExceptionIf the class for an object being restored cannot be found.
Relativizes this path against the parameter.

The result of this operation constructs a path which is resolved against this will result in the parameter path.

The following will be true for any two relativizable paths:

 SakerPath first = ...;
 SakerPath other = ...;
 // the following is true:
 first.resolve(first.relativize(other)).equals(other);
 
Examples:
  • "/home" relativized against "/home/user" is "user"
  • "/home/user" relativized against "/home" is ".."
  • "/home/user" relativized against "/home/user" is ""
  • "/home/user" relativized against "/home/john" is "../john"
The same applies for paths without a root name.
otherThe path to relativize against.
The relativized path.
IllegalArgumentExceptionIf the paths are not relativizable. (See isRelativizable(SakerPath))
Constructs a path which has the parameter as root.

The parameter root is normalized and can be null to construct a relative path with the current names.

newrootThe new root.
The result path.
InvalidPathFormatExceptionIf the root format is invalid.
Resolves the given path names against this path.

Any directory separator characters are normalized.

pathsThe paths to resolve.
The resolved path.
InvalidPathFormatExceptionIf the path has an invalid format.
Resolves the given path names against this path.

Any directory separator characters are normalized.

pathThe path to resolve.
The resolved path.
InvalidPathFormatExceptionIf the path has an invalid format.
Resolves the given relative argument against this path.
pathThe path to resolve.
The parameter path resolved against this.
InvalidPathFormatExceptionIf the parameter is not relative, or the argument cannot be resolved against this path.
Resolves the given relative argument against this path.

Path resolution is a binary operation which results in a single path that is the result of the first path and the second path concatenated. During concatenation any semantically significant path names are normalized ("." and "..")

One can look at this process as navigating to the first path in the filesystem, then navigating according to the second path. The result path is taken using the current path after the navigation.

If this path is absolute, and the argument would escape the root of this path, then an InvalidPathFormatException is thrown. (E.g.: this path is /home and argument is ../../file)

otherThe path to resolve.
The parameter path resolved against this.
InvalidPathFormatExceptionIf the parameter is not relative, or the argument cannot be resolved against this path.
Resolves the given path names against this path.

Any directory separator characters are normalized.

pathsThe paths to resolve.
The resolved path.
InvalidPathFormatExceptionIf the path has an invalid format.
Resolves the path to a sibling name.

Sibling resolution is taking the parent of this and then resolving the parameter against it.

The sibling resolution will not escape root boundaries and works for relative paths too.

This method is generally useful when a direct sibling of a path is needed.

E.g.
Sibling of "/home/user" for "john" is "/home/john"
Sibling of "/home/user" for "john/content" is "/home/john/content"
Sibling of "../directory" for "second" is ../second"

pathThe sibling path.
The resolved path.
InvalidPathFormatExceptionIf this path is absolute and has no path names.
Creates a relative path with a single path name.

The resulting path will be relative and contain only the parameter path name.

pathThe path name.
The result path with single path name.
NullPointerExceptionIf the argument is null.
InvalidPathFormatExceptionIf the parameter path name is not valid.
public boolean startsWith(SakerPath other)
Checks if this path starts with the parameter path.

Returns true if both paths have the same roots and all of the path names of the parameter occurs at the start of this path.

This method works in a case-sensitive manner.

otherThe base path to check for.
If this path starts with the parameter.
public SakerPath subPath(int beginindex) throws IndexOutOfBoundsException
Creates a relative subpath starting from the given index.
beginindexThe first index (inclusive).
The relative subpath.
IndexOutOfBoundsExceptionIf the indices are out of range.
public SakerPath subPath(int beginindex, int endindex) throws IndexOutOfBoundsException
Creates a relative subpath in the given range.
beginindexThe first index (inclusive).
endindexThe last index (exclusive).
The relative subpath.
IndexOutOfBoundsExceptionIf the indices are out of range.
public SakerPath subPath(String root, int beginindex) throws IndexOutOfBoundsException
Creates a subpath starting from the given index with a specific root.
rootThe root for the resulting path to use or null.
beginindexThe first index (inclusive).
The relative subpath.
IndexOutOfBoundsExceptionIf the indices are out of range.
public SakerPath subPath(String root, int beginindex, int endindex) throws IndexOutOfBoundsException
Creates a subpath in the given range with a specific root.
rootThe root for the resulting path to use or null.
beginindexThe first index (inclusive).
endindexThe last index (exclusive).
The relative subpath.
IndexOutOfBoundsExceptionIf the indices are out of range.
Converts this path to an all lowercase representation.

The default locale is used to convert each character of the path.

Same as:

 toLowerCase(Locale.getDefault())
 
The all lowercase representation of the path.
Converts this path to an all lowercase representation using the specified locale.

As paths have a case-sensitive representation, it may be useful to convert them to a lowercase representation when comparing them for equality in some cases.

localeThe locale to use when converting the path names to lower case.
The all lowercase representation of the path.
NullPointerExceptionIf the locale is null.
public String toString()
Converts this path to a String. All path names are separated by forward slashes ('/').

Passing the result of this method to valueOf(String) will result in a path that equals with this.

Converting a path that contains only a single drive root will not end in forward slash.

a string representation of the object.
Converts this path to string, but does not include the root if any.
The string representation of this path without the root.
Tries to relativize this path against the parameter.

If the paths are not relativizable, the parameter path is returned.

otherThe path to relativize against.
The relativized path if succeeded, or the parameter path.
Tries to resolve the parameter path against this path.

If the parameter is not relative, then it is returned without modification. Else the parameter path is resolved against this.

otherThe path to resolve.
The resolved path.
Parses the parameter String and creates a path.

Equivalent to calling valueOf(SakerPath, String) with null relative resolve parameter.

pathThe path to parse.
The parsed path.
NullPointerExceptionIf the argument is null.
InvalidPathFormatExceptionIn case of an invalid path name.
public static SakerPath valueOf(Path path) throws NullPointerException
Creates a path from the given path argument.

The resulting path will be relative only if the argument path is relative. Roots are normalized and extraneous "." and ".." path names are normalized.

pathThe path to convert.
The resulting path.
NullPointerExceptionIf the path is null.
Parses the parameter String and resolves it against the parameter path is it is relative.

This function parses the passed String parameter and constructs a valid immutable SakerPath instance. The path names are semantically checked and an exception is thrown if they are in an illegal format.

The parsed path may be relative or absolute. If it is relative then it will be resolved against the passed path parameter if not null.

relativeresolveThe path to resolve the result against if is relative. May be null.
pathThe path to parse.
The parsed path.
NullPointerExceptionIf the path is null.
InvalidPathFormatExceptionIn case of an invalid path name.
public void writeExternal(ObjectOutput out) throws IOException
Overridden from: Externalizable
The object implements the writeExternal method to save its contents by calling the methods of DataOutput for its primitive values or calling the writeObject method of ObjectOutput for objects, strings, and arrays.
outthe stream to write the object to
IOExceptionIncludes any I/O exceptions that may occur