Package com.helger.io.file

Class PathHelper

java.lang.Object
com.helger.io.file.PathHelper
@Immutable public final class PathHelper extends Object
Miscellaneous file utility methods.
Author:
Philip Helger

  • Method Summary

    Modifier and Type
    Method
    Description
    static boolean
    canReadAndWriteFile(@Nullable Path aFile)
    Check if the passed file can read and write.
    static @NonNull com.helger.base.state.EChange
    ensureParentDirectoryIsPresent(@NonNull Path aFile)
    Ensure that the parent directory of the passed path is present.
    static boolean
    equalPaths(@NonNull Path aObj1, @NonNull Path aObj2)
    Compare two paths for equality by resolving their real paths.
    static @Nullable URL
    getAsURL(@NonNull Path aPath)
    Convert the passed path to a URL.
    static @Nullable com.helger.base.io.nonblocking.NonBlockingBufferedInputStream
    getBufferedInputStream(@NonNull Path aFile)
    Get a buffered input stream for the passed path.
    static @Nullable com.helger.base.io.nonblocking.NonBlockingBufferedOutputStream
    getBufferedOutputStream(@NonNull Path aFile)
    Get a buffered output stream for the passed path using the default append mode.
    static @Nullable com.helger.base.io.nonblocking.NonBlockingBufferedOutputStream
    getBufferedOutputStream(@NonNull Path aFile, @NonNull com.helger.base.io.EAppend eAppend)
    Get a buffered output stream for the passed path.
    static @Nullable com.helger.base.io.nonblocking.NonBlockingBufferedReader
    getBufferedReader(@NonNull Path aFile, @NonNull Charset aCharset)
    Get a buffered Reader for the passed path using the specified charset.
    static @Nullable com.helger.base.io.nonblocking.NonBlockingBufferedWriter
    getBufferedWriter(@NonNull Path aFile, @NonNull com.helger.base.io.EAppend eAppend, @NonNull Charset aCharset)
    Get a buffered Writer for the passed path using the specified append mode and charset.
    static @Nullable Path
    getCanonicalFile(@Nullable Path aFile)
    Get the canonical file of the passed file, if the file is not null.
    static @Nullable Path
    getCanonicalFileOrNull(@Nullable Path aFile)
    Get the canonical file of the passed file, if the file is not null.
    static @Nullable String
    getCanonicalPath(@Nullable Path aFile)
    Get the canonical path of the passed file, if the file is not null.
    static @Nullable String
    getCanonicalPathOrNull(@Nullable Path aFile)
    Get the canonical path of the passed file, if the file is not null.
    static @NonNull com.helger.collection.commons.ICommonsList<Path>
    getDirectoryContent(@NonNull Path aDirectory)
    This is a replacement for Path.listFiles() doing some additional checks on permissions.
    static @NonNull com.helger.collection.commons.ICommonsList<Path>
    getDirectoryContent(@NonNull Path aDirectory, @Nullable Predicate<? super Path> aPathFilter)
    This is a replacement for Path.listFiles(FilenameFilter) doing some additional checks on permissions.
    static int
    getDirectoryObjectCount(@NonNull Path aDirectory)
    Returns the number of files and directories contained in the passed directory excluding the system internal directories.
    static @Nullable InputStream
    getInputStream(@NonNull Path aFile)
    Get an InputStream for the passed path.
    static @Nullable OutputStream
    getOutputStream(@NonNull Path aFile)
    Get an output stream for writing to a file.
    static @Nullable OutputStream
    getOutputStream(@NonNull Path aFile, @NonNull com.helger.base.io.EAppend eAppend)
    Get an output stream for writing to a file.
    static @Nullable Reader
    getReader(@NonNull Path aFile, @NonNull Charset aCharset)
    Get a Reader for the passed path using the specified charset.
    static @Nullable Writer
    getWriter(@NonNull Path aFile, @NonNull com.helger.base.io.EAppend eAppend, @NonNull Charset aCharset)
    Get a Writer for the passed path using the specified append mode and charset.
    static boolean
    isFileNewer(@NonNull Path aFile1, @NonNull Path aFile2)
    Returns true if the first file is newer than the second file.
    static boolean
    isParentDirectory(@NonNull Path aSearchDirectory, @NonNull Path aStartDirectory)
    Check if the searched directory is a parent object of the start directory
    static @NonNull Path
    walkFileTree(@NonNull Path aStart, int nMaxDepth, @NonNull FileVisitor<? super Path> aVisitor)
    Walk a file tree with no FileVisitOptions.
    static @NonNull Path
    walkFileTree(@NonNull Path aStart, @NonNull Set<FileVisitOption> aOptions, int nMaxDepth, @NonNull FileVisitor<? super Path> aVisitor)
    Walks a file tree.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • equalPaths

      public static boolean equalPaths(@NonNull Path aObj1, @NonNull Path aObj2)
      Compare two paths for equality by resolving their real paths.
      Parameters:
      aObj1 - The first path. May not be null.
      aObj2 - The second path. May not be null.
      Returns:
      true if the two paths point to the same location, false otherwise.

    • canReadAndWriteFile

      public static boolean canReadAndWriteFile(@Nullable Path aFile)
      Check if the passed file can read and write. If the file already exists, the file itself is checked. If the file does not exist, the parent directory
      Parameters:
      aFile - The file to be checked. May be null.
      Returns:
      true if the file can be read and written

    • ensureParentDirectoryIsPresent

      public static @NonNull com.helger.base.state.EChange ensureParentDirectoryIsPresent(@NonNull Path aFile)
      Ensure that the parent directory of the passed path is present. If it is not present, it will be created.
      Parameters:
      aFile - The path whose parent directory should be present. May not be null.
      Returns:
      EChange.CHANGED if the parent directory was created, EChange.UNCHANGED if it already existed.
      Throws:
      IllegalStateException - If the parent directory could not be created.

    • getCanonicalFile

      public static @Nullable Path getCanonicalFile(@Nullable Path aFile) throws IOException
      Get the canonical file of the passed file, if the file is not null.
      Parameters:
      aFile - The file to get the canonical path from. May be null.
      Returns:
      null if the passed file is null.
      Throws:
      IOException - If an I/O error occurs, which is possible because the construction of the canonical pathname may require filesystem queries

    • getCanonicalFileOrNull

      public static @Nullable Path getCanonicalFileOrNull(@Nullable Path aFile)
      Get the canonical file of the passed file, if the file is not null. In case of an IOException, null is returned.
      Parameters:
      aFile - The file to get the canonical path from. May be null.
      Returns:
      null if the passed file is null or an exception occurred.

    • getCanonicalPath

      public static @Nullable String getCanonicalPath(@Nullable Path aFile) throws IOException
      Get the canonical path of the passed file, if the file is not null.
      Parameters:
      aFile - The file to get the canonical path from. May be null.
      Returns:
      null if the passed file is null.
      Throws:
      IOException - If an I/O error occurs, which is possible because the construction of the canonical pathname may require filesystem queries

    • getCanonicalPathOrNull

      public static @Nullable String getCanonicalPathOrNull(@Nullable Path aFile)
      Get the canonical path of the passed file, if the file is not null. In case of an IOException, null is returned.
      Parameters:
      aFile - The file to get the canonical path from. May be null.
      Returns:
      null if the passed file is null.

    • isParentDirectory

      public static boolean isParentDirectory(@NonNull Path aSearchDirectory, @NonNull Path aStartDirectory)
      Check if the searched directory is a parent object of the start directory
      Parameters:
      aSearchDirectory - The directory to be searched. May not be null.
      aStartDirectory - The directory where the search starts. May not be null.
      Returns:
      true if the search directory is a parent of the start directory, false otherwise.
      See Also:

    • getInputStream

      public static @Nullable InputStream getInputStream(@NonNull Path aFile)
      Get an InputStream for the passed path.
      Parameters:
      aFile - The path to open for reading. May not be null.
      Returns:
      null if the path does not exist or cannot be opened.

    • getBufferedInputStream

      public static @Nullable com.helger.base.io.nonblocking.NonBlockingBufferedInputStream getBufferedInputStream(@NonNull Path aFile)
      Get a buffered input stream for the passed path.
      Parameters:
      aFile - The path to open for reading. May not be null.
      Returns:
      null if the path does not exist or cannot be opened.

    • getReader

      public static @Nullable Reader getReader(@NonNull Path aFile, @NonNull Charset aCharset)
      Get a Reader for the passed path using the specified charset.
      Parameters:
      aFile - The path to open for reading. May not be null.
      aCharset - The charset to use. May not be null.
      Returns:
      null if the path does not exist or cannot be opened.

    • getBufferedReader

      public static @Nullable com.helger.base.io.nonblocking.NonBlockingBufferedReader getBufferedReader(@NonNull Path aFile, @NonNull Charset aCharset)
      Get a buffered Reader for the passed path using the specified charset.
      Parameters:
      aFile - The path to open for reading. May not be null.
      aCharset - The charset to use. May not be null.
      Returns:
      null if the path does not exist or cannot be opened.

    • getOutputStream

      public static @Nullable OutputStream getOutputStream(@NonNull Path aFile)
      Get an output stream for writing to a file.
      Parameters:
      aFile - The file to write to. May not be null.
      Returns:
      null if the file could not be opened

    • getOutputStream

      public static @Nullable OutputStream getOutputStream(@NonNull Path aFile, @NonNull com.helger.base.io.EAppend eAppend)
      Get an output stream for writing to a file.
      Parameters:
      aFile - The file to write to. May not be null.
      eAppend - Appending mode. May not be null.
      Returns:
      null if the file could not be opened

    • getBufferedOutputStream

      public static @Nullable com.helger.base.io.nonblocking.NonBlockingBufferedOutputStream getBufferedOutputStream(@NonNull Path aFile)
      Get a buffered output stream for the passed path using the default append mode.
      Parameters:
      aFile - The path to write to. May not be null.
      Returns:
      null if the path could not be opened.

    • getBufferedOutputStream

      public static @Nullable com.helger.base.io.nonblocking.NonBlockingBufferedOutputStream getBufferedOutputStream(@NonNull Path aFile, @NonNull com.helger.base.io.EAppend eAppend)
      Get a buffered output stream for the passed path.
      Parameters:
      aFile - The path to write to. May not be null.
      eAppend - Appending mode. May not be null.
      Returns:
      null if the path could not be opened.

    • getWriter

      public static @Nullable Writer getWriter(@NonNull Path aFile, @NonNull com.helger.base.io.EAppend eAppend, @NonNull Charset aCharset)
      Get a Writer for the passed path using the specified append mode and charset.
      Parameters:
      aFile - The path to write to. May not be null.
      eAppend - Appending mode. May not be null.
      aCharset - The charset to use. May not be null.
      Returns:
      null if the path could not be opened.

    • getBufferedWriter

      public static @Nullable com.helger.base.io.nonblocking.NonBlockingBufferedWriter getBufferedWriter(@NonNull Path aFile, @NonNull com.helger.base.io.EAppend eAppend, @NonNull Charset aCharset)
      Get a buffered Writer for the passed path using the specified append mode and charset.
      Parameters:
      aFile - The path to write to. May not be null.
      eAppend - Appending mode. May not be null.
      aCharset - The charset to use. May not be null.
      Returns:
      null if the path could not be opened.

    • isFileNewer

      public static boolean isFileNewer(@NonNull Path aFile1, @NonNull Path aFile2)
      Returns true if the first file is newer than the second file. Returns true if the first file exists and the second file does not exist. Returns false if the first file is older than the second file. Returns false if the first file does not exists but the second does. Returns false if none of the files exist.
      Parameters:
      aFile1 - First file. May not be null.
      aFile2 - Second file. May not be null.
      Returns:
      true if the first file is newer than the second file, false otherwise.

    • getDirectoryObjectCount

      @Nonnegative public static int getDirectoryObjectCount(@NonNull Path aDirectory)
      Returns the number of files and directories contained in the passed directory excluding the system internal directories.
      Parameters:
      aDirectory - The directory to check. May not be null and must be a directory.
      Returns:
      A non-negative number of objects in that directory.
      See Also:

    • walkFileTree

      public static @NonNull Path walkFileTree(@NonNull Path aStart, @Nonnegative int nMaxDepth, @NonNull FileVisitor<? super Path> aVisitor)
      Walk a file tree with no FileVisitOptions.
      Parameters:
      aStart - The starting path. May not be null.
      nMaxDepth - The maximum number of directory levels to visit. Must be ≥ 0.
      aVisitor - The file visitor to invoke for each file. May not be null.
      Returns:
      The starting path. Never null.
      Throws:
      UncheckedIOException - if an I/O error is thrown by a visitor method

    • walkFileTree

      public static @NonNull Path walkFileTree(@NonNull Path aStart, @NonNull Set<FileVisitOption> aOptions, @Nonnegative int nMaxDepth, @NonNull FileVisitor<? super Path> aVisitor)
      Walks a file tree.

      This method walks a file tree rooted at a given starting file. The file tree traversal is depth-first with the given FileVisitor invoked for each file encountered. File tree traversal completes when all accessible files in the tree have been visited, or a visit method returns a result of TERMINATE. Where a visit method terminates due an IOException, an uncaught error, or runtime exception, then the traversal is terminated and the error or exception is propagated to the caller of this method.

      For each file encountered this method attempts to read its BasicFileAttributes. If the file is not a directory then the visitFile method is invoked with the file attributes. If the file attributes cannot be read, due to an I/O exception, then the visitFileFailed method is invoked with the I/O exception.

      Where the file is a directory, and the directory could not be opened, then the visitFileFailed method is invoked with the I/O exception, after which, the file tree walk continues, by default, at the next sibling of the directory.

      Where the directory is opened successfully, then the entries in the directory, and their descendants are visited. When all entries have been visited, or an I/O error occurs during iteration of the directory, then the directory is closed and the visitor's postVisitDirectory method is invoked. The file tree walk then continues, by default, at the next sibling of the directory.

      By default, symbolic links are not automatically followed by this method. If the options parameter contains the FOLLOW_LINKS option then symbolic links are followed. When following links, and the attributes of the target cannot be read, then this method attempts to get the BasicFileAttributes of the link. If they can be read then the visitFile method is invoked with the attributes of the link (otherwise the visitFileFailed method is invoked as specified above).

      If the options parameter contains the FOLLOW_LINKS option then this method keeps track of directories visited so that cycles can be detected. A cycle arises when there is an entry in a directory that is an ancestor of the directory. Cycle detection is done by recording the file-key of directories, or if file keys are not available, by invoking the Files.isSameFile(java.nio.file.Path, java.nio.file.Path) method to test if a directory is the same file as an ancestor. When a cycle is detected it is treated as an I/O error, and the visitFileFailed method is invoked with an instance of FileSystemLoopException.

      The maxDepth parameter is the maximum number of levels of directories to visit. A value of 0 means that only the starting file is visited, unless denied by the security manager. A value of MAX_VALUE may be used to indicate that all levels should be visited. The visitFile method is invoked for all files, including directories, encountered at maxDepth, unless the basic file attributes cannot be read, in which case the visitFileFailed method is invoked.

      If a visitor returns a result of null then NullPointerException is thrown.

      When a security manager is installed and it denies access to a file (or directory), then it is ignored and the visitor is not invoked for that file (or directory).

      Parameters:
      aStart - the starting file
      aOptions - options to configure the traversal
      nMaxDepth - the maximum number of directory levels to visit
      aVisitor - the file visitor to invoke for each file
      Returns:
      the starting file
      Throws:
      UncheckedIOException - if an I/O error is thrown by a visitor method

    • getDirectoryContent

      @ReturnsMutableCopy public static @NonNull com.helger.collection.commons.ICommonsList<Path> getDirectoryContent(@NonNull Path aDirectory)
      This is a replacement for Path.listFiles() doing some additional checks on permissions. The order of the returned files is undefined. "." and ".." are not contained.
      Parameters:
      aDirectory - The directory to be listed. May not be null.
      Returns:
      Never null.

    • getDirectoryContent

      @ReturnsMutableCopy public static @NonNull com.helger.collection.commons.ICommonsList<Path> getDirectoryContent(@NonNull Path aDirectory, @Nullable Predicate<? super Path> aPathFilter)
      This is a replacement for Path.listFiles(FilenameFilter) doing some additional checks on permissions. The order of the returned files is undefined. "." and ".." are not contained.
      Parameters:
      aDirectory - The directory to be listed. May not be null.
      aPathFilter - The path filter to be used. May not be null.
      Returns:
      Never null.

    • getAsURL

      public static @Nullable URL getAsURL(@NonNull Path aPath)
      Convert the passed path to a URL.
      Parameters:
      aPath - The path to be converted. May not be null.
      Returns:
      null if the conversion to URL failed.