saker.build Documentation TaskDoc JavaDoc Packages
public class FileUtils
Utility class containing functions for handling files, and file paths.
Fields
public static final String
The default hashing algorithm that this class uses.
Methods
public static String
changeExtension(String name, String extension)
Changes the extension of a file name.
public static long
Finds the index at which the given input of bytes and the contents of the specified file doesn't equal.
public static MessageDigest
Gets the message digest that has the default hash algorithm defined by this class.
public static String
Gets the extension from the given file name.
public static Modifier
Gets the WatchEvent.Modifier that is the FILE_TREE modifier.
public static String
Gets the last path name from an URL formatted string.
public static boolean
Checks if the given name has the specified extension in a case-insensitive manner.
public static byte[]
Hashes the files at the given path using the default hasher.
public static void
Updates the given message digest with the file contents at the given path.
public static byte[]
Hashes the bytes in the given input stream with the default hasher.
public static byte[]
Hashes a string using the default hasher.
public static boolean
isFileBytesSame(Path filepath, byte[] bytes)
Checks if the file contents at the given path matches the argument byte array.
public static boolean
Checks if the argument file attributes have the same size and last modified time.
public static boolean
Checks if the given char sequence contains only slash characters.
public static String
Removes the extension from the given file name.
public static String[]
Splits the given path into separate parts by its contained slashes ('\\' and '/').
public static void
Writes the contents of the input stream to the given file, and checking the bytes for equality before performing write operations.
public static final String DEFAULT_FILE_HASH_ALGORITHM = "MD5"
The default hashing algorithm that this class uses.
public static String changeExtension(String name, String extension) throws NullPointerException
Changes the extension of a file name.

The extension is the part of the file name that is after the last '.' dot character. If there are no dot characters in the file name, it has no extension.

This method takes the name of a file, removes the extension part, and appends it with the extension argument..

Note: if a file has an extension where the dot is the first character in the name, this method will not chane that. E.g. a name with a format of ".dotfile" is unchanged.

nameThe file name.
extensionThe extension. This shouldn't contain a preceeding dot.
The name with the change extension, or null if the name argument was null.
NullPointerExceptionIf the name is non-null, and the extension is null.
public static long fileMismatch(InputStream is, Path filepath) throws IOException, NullPointerException
Finds the index at which the given input of bytes and the contents of the specified file doesn't equal.

This method will read bytes from the argument InputStream and the file specified by the given Path simultaneously, and determine the index of the first byte that doesn't equal.

The method internally buffers the bytes from the input stream, and will leave the input stream in a state in which some bytes will be lost by the reader.

If the input stream contains the same amount of bytes, and all bytes match the ones in the file, this method will return -1, signaling that all bytes matched.

If the file doesn't exists, or reading from any of the inputs fail with exception it will be forwarded to the caller.

In any other cases, the method will return the index at which either a mismatching byte was found, or any of the inputs ended prematurely.

This method can handle large files without incurring heavy memory overhead. This method is similar to the Arrays.mismatch(byte[], byte[]) method (available on JDK9+), or ArrayUtils.mismatch(byte[], int, byte[], int, int).

isThe input stream to validate the file against.
filepathThe file to check the bytes of.
The index of the first mismatching byte, or -1 if all bytes equal.
IOExceptionIn case of any reading error.
NullPointerExceptionIf any of the arguments are null.
Gets the message digest that has the default hash algorithm defined by this class.

Callers should not rely on the returned digest to have a specific algorithm, and they shouldn't rely on it not chaning between different invocation of the Java Virtual Machine.

The default hash algorithm may change between library releases, and may be configureable by external properties in the future. Callers can only rely on the fact that the default file hasher algorithm will stay the same in the same JVM. (I.e. it will not change during the lifetime of the application.)

A message digest with the default hash algorithm.
AssertionErrorIf the default hash algorithm was not found.
public static String getExtension(String name)
Gets the extension from the given file name.

The extension is the part of the file name that is after the last '.' dot character. If there are no dot characters in the file name, it has no extension.

Note: if a file has an extension where the dot is the first character in the name, this method will not return that. E.g. a name with a format of ".dotfile" is considered to have no extension.

nameThe file name.
The extension of the given name, or null if the name doesn't have one.
Gets the WatchEvent.Modifier that is the FILE_TREE modifier.

The FILE_TREE modifier is an API in the JVM that may not be supported on all platforms. Therefore, it is necessary to error handle its absence, and this function will return null if it was not found.

The FILE_TREE watch event modifier or null if not supported.
Gets the last path name from an URL formatted string.

The method works in the following way:

  1. If the URL contains a '?' character, it and any consecutive part is removed. This is in order to remove the query string from the URL such as "http://example.com/path?some=query" will be "http://example.com/path".
  2. If the URL contains a '#' character, it and any consecutive part is removed. This is to remove any anchor parts from the URL, such as "http://example.com/path#anchor" will be "http://example.com/path".
  3. From the remaining string, the last path name will be retrieved, that is the last part after any slash characters. E.g. "http://example.com/path" will be "path".
If there are no path parts in the URL, null will be returned. (E.g. for "?some=query".)

Note that, for simple URLs, the result might be the same as the domain name. (E.g. for "http://example.com", "example.com" will be returned.)

The method doesn't strip trailing slash characters. (E.g. for "http://example.com/", null will be returned.)

urlThe URL to get the last path name from.
The last path name, or null if not present.
NullPointerExceptionIf the argument is null.
public static boolean hasExtensionIgnoreCase(String name, String ext) throws NullPointerException
Checks if the given name has the specified extension in a case-insensitive manner.

The extension of a file name is determined by taking the substring that is after the last '.' dot character in the name. If there is no dot character in the name, the name is considered to have no extension.

Note: if a file has an extension where the dot is the first character in the name, this method will return false for it. E.g. a name with a format of ".dotfile" is not be considered to have the "dotfile".

nameThe name to check the extension for.
extThe extension to check. This argument should not contain the preceeding '.' dot in it.
true if the given name has the specified extension.
public static byte[] hashFiles(Path path) throws IOException, NullPointerException
Hashes the files at the given path using the default hasher.

See hashFiles(Path, MessageDigest) for operational details.

pathThe path to hash.
The hash.
IOExceptionIn case of I/O error.
NullPointerExceptionIf the path is null.
public static void hashFiles(Path path, MessageDigest digest) throws IOException, NullPointerException
Updates the given message digest with the file contents at the given path.

If the path denotes a directory, then it will be recursively enumerated, and all files will be used to update the argument message digest. The files are enumerated in a deterministic order, therefore if this method is invoked multiple times, it should return the same hash if the files have not changed meanwhile.

If the path denotes a file, then the file will be fully read, and the contents are used to update the message digest.

If the method fails to open a file, an IOException is thrown.

pathThe path to hash.
digestThe message digest to update with the file contents.
IOExceptionIn case of I/O error.
NullPointerExceptionIf any of the arguments are null.
Hashes the bytes in the given input stream with the default hasher.

The input stream will be read until it returns no more bytes.

isThe input stream.
The hash of the bytes from the input stream.
IOExceptionIn case of I/O error.
NullPointerExceptionIf the argument is null.
public static byte[] hashString(String s) throws NullPointerException
Hashes a string using the default hasher.

The string will be converted to a byte sequence by encoding it using UTF-8.

sThe string to hash.
The hash.
NullPointerExceptionIf the argument is null.
public static boolean isFileBytesSame(Path filepath, byte[] bytes) throws NullPointerException
Checks if the file contents at the given path matches the argument byte array.

This method will open the file, check if the size of the file matches the argument array, and if so, will read the file and check if the contents match.

This method doesn't do any locking and such to ensure that the file is not modified during the contents are checked. The result of this method should not be used in a secure context, meaning that the result of this method should be considered immediately stale, as the file system is a shared resource, and others may have modified the checked file after this method returns.

If this method returns true, that doesn't ensure that the file contents are, and even were ever the same as the expected bytes. It just tells the caller that an input was opened to the file, and the same bytes were sequentally read from the input, during this method call.

filepathThe path of the file to check.
bytesThe expected byte contents of the file.
true if the file contents are the same as the argument bytes.
NullPointerExceptionIf any of the arguments are null.
Checks if the argument file attributes have the same size and last modified time.

This method handles null arguments. If both of them are null, returns true. If only one of them, returns false.

aThe first attributes.
bThe second attributes.
true if the size and last modification time is the same from the argument attributes.
public static boolean isSlashesOnly(CharSequence cs) throws NullPointerException
Checks if the given char sequence contains only slash characters.

The slash characters are: '/' and '\\'.

An empty string is considered to contains only slash characters.

csThe char sequence to examine.
true if there are only slash characters in the argument.
NullPointerExceptionIf the argument is null.
public static String removeExtension(String name)
Removes the extension from the given file name.

The extension is the part of the file name that is after the last '.' dot character. If there are no dot characters in the file name, it has no extension.

This method takes the name of a file, and removes the extension part, including the dot.

Note: if a file has an extension where the dot is the first character in the name, this method will not remove that. E.g. a name with a format of ".dotfile" is unchanged.

nameThe file name.
The name without the extension or null if the argument was null.
public static String[] splitPath(CharSequence path) throws NullPointerException
Splits the given path into separate parts by its contained slashes ('\\' and '/').

Multiple consecutive slashes will be stripped, e.g. "a//b" will return { "a", "b" }.

If there's a leading slash, an empty string will be the first element. Trailing slash characters will be removed. An empty string will not be the last element, if the last character is a slash character.

pathThe path to split.
The path split by its contained slash chracters.
NullPointerExceptionIf the argument is null.
Writes the contents of the input stream to the given file, and checking the bytes for equality before performing write operations.

This method will only write the bytes from the input stream to the given file if and only if they doesn't already equal. This means that if the file contents on the disk already matches the contents of the InputStream, no writing operations will be issued.

The method simultaneously reads the input from the stream and file, and only starts writing the file if a mismatch is found. See fileMismatch(InputStream, Path).

If the file cannot be opened for writing, the byte contents will still be checked for equality, and the method will successfully return if the file contents equal. This is an useful scenario when a client tries to write to a file that locked by another agent, but wants to handle gracefully is the file contents are the same. Often occurs when dynamic libraries are being exported and loaded by ClassLoaders.

If the file bytes mismatch, and the file cannot be opened for writing, the original write opening IOException is thrown.

isThe input stream of bytes to write.
filepathThe file path to write the bytes to.
IOExceptionIn case of I/O error.
NullPointerExceptionIf any of the arguments are null.