de.caff.util

## Class FileTool

- java.lang.Object
- - de.caff.util.FileTool

-     public final class FileTool
      extends java.lang.Object

  Helper tools for handling files.
  Since:
    March 05, 2019
  Author:
    Rammi

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.util.Comparator<java.io.File>` | `BY_NAME_CASE_INSENSITIVE` Sort by name (case insensitive).
    `static java.util.Comparator<java.io.File>` | `BY_NAME_CASE_SENSITIVE` Sort by name (case sensitive).
    `static java.util.Comparator<java.io.File>` | `DIRECTORIES_FIRST` Sort directories first.
    `static long` | `NO_DIFFERENCE` Return value of `firstDiff(File, File)` when both contents are equal.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `append(java.io.File file, byte[] data)` Append the given bytes to a file.
    `static void` | `append(java.io.File file, byte[] data, int offset, int length)` Append the given bytes to a file.
    `static void` | `append(java.lang.String file, byte[] data)` Append the given bytes to a file.
    `static void` | `append(java.lang.String file, byte[] data, int offset, int length)` Append the given bytes to a file.
    `static boolean` | `cleanup(java.io.File dir)` Cleanup a directory by removing its content.
    `static boolean` | `contentEquals(java.io.File file1, java.io.File file2)` Is the content of two files equal?
    `static boolean` | `contentEquals(java.nio.file.Path file1, java.nio.file.Path file2)` Is the content of two files equal?
    `static boolean` | `contentEquals(java.lang.String filePath1, java.lang.String filePath2)` Is the content of two files equal?
    `static boolean` | `deleteTree(java.io.File file)` Delete a file or file tree.
    `static java.io.File` | `expand(java.io.File dir, java.lang.String... subPath)` Append multiple path items to a file.
    `static long` | `firstDiff(java.io.File file1, java.io.File file2)` Get the position of the first difference of the content of two files.
    `static long` | `firstDiff(java.lang.String filePath1, java.lang.String filePath2)` Get the position of the first difference of the content of two files.
    `static java.lang.String` | `getExtension(java.io.File file)` Get the extension of the file name.
    `static java.lang.String` | `getExtension(java.lang.String fileName)` Get the extension of the file name.
    `static byte[]` | `load(java.io.File file)` Load a file into memory.
    `static byte[]` | `load(java.lang.String file)` Load a file into memory.
    `static java.io.File` | `multiExpand(java.io.File dir, char fileSeparator, java.lang.String subPath)` Append a complete path to a file.
    `static java.io.File` | `multiExpand(java.io.File dir, java.lang.String subPath)` Append a complete path to a file.
    `static java.util.List<java.io.File>` | `performGlobbing(java.io.File fileWithPossibleGlobbing)`
    `static void` | `store(java.io.File file, byte[] data)` Store the given bytes to a file.
    `static void` | `store(java.io.File file, byte[] data, int offset, int length)` Store the given bytes to a file.
    `static void` | `store(java.lang.String file, byte[] data)` Store the given bytes to a file.
    `static void` | `store(java.lang.String file, byte[] data, int offset, int length)` Store the given bytes to a file.
    `static void` | `walkTree(java.io.File file, java.util.function.Consumer<? super java.io.File> fileHandler)` Walk a file tree.
    `static void` | `walkTree(java.io.File file, java.util.function.Predicate<? super java.io.File> stepIntoDir, java.util.function.Consumer<? super java.io.File> fileHandler)` Walk a file tree.
    `static <E extends java.lang.Exception> void` | `walkTreeFragile(java.io.File file, FragileProcedure1<E,? super java.io.File> fileHandler)` Walk a file tree and apply a consumer which might throw an exception.
    `static <E extends java.lang.Exception> void` | `walkTreeFragile(java.io.File file, java.util.function.Predicate<java.io.File> stepIntoDir, FragileProcedure1<E,? super java.io.File> fileHandler)` Walk a file tree and apply a consumer which might throw an exception.
    `static void` | `walkTreeOrdered(java.io.File file, java.util.function.Consumer<? super java.io.File> fileHandler, java.util.Comparator<? super java.io.File> order)` Walk a file tree in a defined order.
    `static void` | `walkTreeOrdered(java.io.File file, java.util.function.Predicate<? super java.io.File> stepIntoDir, java.util.function.Consumer<? super java.io.File> fileHandler, java.util.Comparator<? super java.io.File> order)` Walk a file tree in a defined order.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### DIRECTORIES_FIRST

          public static final java.util.Comparator<java.io.File> DIRECTORIES_FIRST

      Sort directories first.

      Ignores names.

      Use `Comparator.thenComparing(Comparator)` with `BY_NAME_CASE_INSENSITIVE` or `BY_NAME_CASE_SENSITIVE` to get directories first, while names are ordered inside each group.

      Use `Comparator.reversed()` for the reverse of this.

    - #### BY_NAME_CASE_INSENSITIVE

          public static final java.util.Comparator<java.io.File> BY_NAME_CASE_INSENSITIVE

      Sort by name (case insensitive).

      Directories and files are mixed.

      Use `Comparator.reversed()` to reverse this order.

      See Also:
        `DIRECTORIES_FIRST`

    - #### BY_NAME_CASE_SENSITIVE

          public static final java.util.Comparator<java.io.File> BY_NAME_CASE_SENSITIVE

      Sort by name (case sensitive).

      Directories and files are mixed.

      Use `Comparator.reversed()` to reverse this order.

      See Also:
        `DIRECTORIES_FIRST`

    - #### NO_DIFFERENCE

          public static final long NO_DIFFERENCE

      Return value of `firstDiff(File, File)` when both contents are equal.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### walkTree

          public static void walkTree(@NotNull
                                      java.io.File file,
                                      @NotNull
                                      java.util.function.Predicate<? super java.io.File> stepIntoDir,
                                      @NotNull
                                      java.util.function.Consumer<? super java.io.File> fileHandler)

      Walk a file tree. This walks through the tree in depth-first order. Symbolic links are not handled specially. Files in a directory are encountered in 'natural' order.
      Parameters:
        `file` - file to start with, usually a directory
        `stepIntoDir` - Predicate allowing to avoid directories. Always called with a directory, i.e. `file.isDirectory()` is always `true`.
        `fileHandler` - Handler called for each file. File is never a directory, i.e. `file.isDirectory()` is always `false`.

    - #### walkTree

          public static void walkTree(@NotNull
                                      java.io.File file,
                                      @NotNull
                                      java.util.function.Consumer<? super java.io.File> fileHandler)

      Walk a file tree. This walks through the tree in depth first order. Symbolic links are not handled specially. This steps into every directory found. Files in a directory are encountered in 'natural' order.
      Parameters:
        `file` - file to start with, usually a directory
        `fileHandler` - Handler called for each file. File is never a directory, i.e. `file.isDirectory()` is always `false`.

    - #### walkTreeOrdered

          public static void walkTreeOrdered(@NotNull
                                             java.io.File file,
                                             @NotNull
                                             java.util.function.Predicate<? super java.io.File> stepIntoDir,
                                             @NotNull
                                             java.util.function.Consumer<? super java.io.File> fileHandler,
                                             @NotNull
                                             java.util.Comparator<? super java.io.File> order)

      Walk a file tree in a defined order. This walks through the tree in depth first order. Symbolic links are not handled specially. Files in a directory are encountered in the defined order.
      Parameters:
        `file` - file to start with, usually a directory
        `stepIntoDir` - Predicate allowing to avoid directories. Always called with a directory, i.e. `file.isDirectory()` is always `true`.
        `fileHandler` - Handler called for each file. File is never a directory, i.e. `file.isDirectory()` is always `false`.
        `order` - comparator defining the order in which files inside a directory are handled. Common orders can be defined by combining the comparators `DIRECTORIES_FIRST`, `BY_NAME_CASE_INSENSITIVE`, and `BY_NAME_CASE_SENSITIVE`.

    - #### walkTreeOrdered

          public static void walkTreeOrdered(@NotNull
                                             java.io.File file,
                                             @NotNull
                                             java.util.function.Consumer<? super java.io.File> fileHandler,
                                             @NotNull
                                             java.util.Comparator<? super java.io.File> order)

      Walk a file tree in a defined order. This walks through the tree in depth first order. Symbolic links are not handled specially. This steps into every directory found. Files in a directory are encountered in 'natural' order.
      Parameters:
        `file` - file to start with, usually a directory
        `fileHandler` - Handler called for each file. File is never a directory, i.e. `file.isDirectory()` is always `false`.
        `order` - comparator defining the order in which files inside a directory are handled. Common orders can be defined by combining the comparators `DIRECTORIES_FIRST`, `BY_NAME_CASE_INSENSITIVE`, and `BY_NAME_CASE_SENSITIVE`.

    - #### walkTreeFragile

          public static <E extends java.lang.Exception> void walkTreeFragile(@NotNull
                                                                             java.io.File file,
                                                                             @NotNull
                                                                             java.util.function.Predicate<java.io.File> stepIntoDir,
                                                                             @NotNull
                                                                             FragileProcedure1<E,? super java.io.File> fileHandler)
                                                                      throws E extends java.lang.Exception

      Walk a file tree and apply a consumer which might throw an exception. This walks through the tree in depth-first order. This allows to exclude or react on directories. Symbolic links are not handled specially. Files in a directory are encountered in 'natural' order.
      Type Parameters:
        `E` - exception thrown by fragile procedure, forwarded by this method
      Parameters:
        `file` - file to start with, usually a directory
        `stepIntoDir` - Predicate allowing to avoid directories. Always called with a directory, i.e. `file.isDirectory()` is always `true`, before stepping into that directory.
        `fileHandler` - Handler called for each file. File is never a directory, i.e. `file.isDirectory()` is always `false`.
      Throws:
        `E` - when `fileHandler` throws it
        `E extends java.lang.Exception`

    - #### walkTreeFragile

          public static <E extends java.lang.Exception> void walkTreeFragile(@NotNull
                                                                             java.io.File file,
                                                                             @NotNull
                                                                             FragileProcedure1<E,? super java.io.File> fileHandler)
                                                                      throws E extends java.lang.Exception

      Walk a file tree and apply a consumer which might throw an exception. This walks through the tree in depth-first order. Symbolic links are not handled specially. Files in a directory are encountered in 'natural' order.
      Type Parameters:
        `E` - exception thrown by fragile procedure, forwarded by this method
      Parameters:
        `file` - file to start with, usually a directory
        `fileHandler` - Handler called for each file. File is never a directory, i.e. `file.isDirectory()` is always `false`.
      Throws:
        `E` - when `fileHandler` throws it
        `E extends java.lang.Exception`

    - #### getExtension

          @Nullable
          public static java.lang.String getExtension(@NotNull
                                                                java.io.File file)

      Get the extension of the file name.
      Parameters:
        `file` - file with a possible extension
      Returns:
        everything after the last dot of the filename, possibly empty it the file ends with a dot, or `null` if the name does not contain any dots

    - #### getExtension

          @Nullable
          public static java.lang.String getExtension(@NotNull
                                                                java.lang.String fileName)

      Get the extension of the file name.
      Parameters:
        `fileName` - file name with a possible extension
      Returns:
        everything after the last dot of the filename, possibly empty it the file ends with a dot, or `null` if the name does not contain any dots

    - #### contentEquals

          public static boolean contentEquals(@NotNull
                                              java.io.File file1,
                                              @NotNull
                                              java.io.File file2)
                                       throws java.io.IOException

      Is the content of two files equal?
      Parameters:
        `file1` - first file
        `file2` - second file
      Returns:
        `true` if both files have the same content
        `false` if both files have different content
      Throws:
        `java.io.IOException` - on file open or read errors

    - #### contentEquals

          public static boolean contentEquals(@NotNull
                                              java.nio.file.Path file1,
                                              @NotNull
                                              java.nio.file.Path file2)
                                       throws java.io.IOException

      Is the content of two files equal?
      Parameters:
        `file1` - first file
        `file2` - second file
      Returns:
        `true` if both files have the same content
        `false` if both files have different content
      Throws:
        `java.io.IOException` - on file open or read errors

    - #### contentEquals

          public static boolean contentEquals(@NotNull
                                              java.lang.String filePath1,
                                              @NotNull
                                              java.lang.String filePath2)
                                       throws java.io.IOException

      Is the content of two files equal?
      Parameters:
        `filePath1` - path of first file
        `filePath2` - path of second file
      Returns:
        `true` if both files have the same content
        `false` if both files have different content
      Throws:
        `java.io.IOException` - on file open or read errors

    - #### firstDiff

          public static long firstDiff(@NotNull
                                       java.io.File file1,
                                       @NotNull
                                       java.io.File file2)
                                throws java.io.IOException

      Get the position of the first difference of the content of two files.
      Parameters:
        `file1` - first file
        `file2` - second file
      Returns:
        first position where both files differ, or `NO_DIFFERENCE` if both files have the same content
      Throws:
        `java.io.IOException` - on file open or read errors

    - #### firstDiff

          public static long firstDiff(@NotNull
                                       java.lang.String filePath1,
                                       @NotNull
                                       java.lang.String filePath2)
                                throws java.io.IOException

      Get the position of the first difference of the content of two files.
      Parameters:
        `filePath1` - path of first file
        `filePath2` - path of second file
      Returns:
        first position where both files differ, or `NO_DIFFERENCE` if both files have the same content
      Throws:
        `java.io.IOException` - on file open or read errors

    - #### load

          @NotNull
          public static byte[] load(@NotNull
                                             java.io.File file)
                                      throws java.io.IOException

      Load a file into memory.
      Parameters:
        `file` - file to load
      Returns:
        byte array with file content
      Throws:
        `java.io.IOException` - on read errors or if the file is too large to fit into a byte array
      See Also:
        `load(String)`

    - #### load

          @NotNull
          public static byte[] load(@NotNull
                                             java.lang.String file)
                                      throws java.io.IOException

      Load a file into memory.
      Parameters:
        `file` - file to load
      Returns:
        byte array with file content
      Throws:
        `java.io.IOException` - on read errors or if the file is too large to fit into a byte array
      See Also:
        `load(File)`

    - #### store

          public static void store(@NotNull
                                   java.io.File file,
                                   @NotNull
                                   byte[] data)
                            throws java.io.IOException

      Store the given bytes to a file. There are no safety belts, the file will ve overwritten if it exists.
      Parameters:
        `file` - file to write to
        `data` - data to write
      Throws:
        `java.io.IOException` - on write errors

    - #### store

          public static void store(@NotNull
                                   java.io.File file,
                                   @NotNull
                                   byte[] data,
                                   int offset,
                                   int length)
                            throws java.io.IOException

      Store the given bytes to a file. There are no safety belts, the file will ve overwritten if it exists.
      Parameters:
        `file` - file to write to
        `data` - data to write
        `offset` - start offset into the byte array
        `length` - number of bytes to be written
      Throws:
        `java.io.IOException` - on write errors

    - #### store

          public static void store(@NotNull
                                   java.lang.String file,
                                   @NotNull
                                   byte[] data)
                            throws java.io.IOException

      Store the given bytes to a file. There are no safety belts, the file will ve overwritten if it exists.
      Parameters:
        `file` - file to write to
        `data` - data to write
      Throws:
        `java.io.IOException` - on write errors

    - #### store

          public static void store(@NotNull
                                   java.lang.String file,
                                   @NotNull
                                   byte[] data,
                                   int offset,
                                   int length)
                            throws java.io.IOException

      Store the given bytes to a file. There are no safety belts, the file will ve overwritten if it exists.
      Parameters:
        `file` - file to write to
        `data` - data to write
        `offset` - start offset into the byte array
        `length` - number of bytes to be written
      Throws:
        `java.io.IOException` - on write errors

    - #### append

          public static void append(@NotNull
                                    java.io.File file,
                                    @NotNull
                                    byte[] data)
                             throws java.io.IOException

      Append the given bytes to a file.
      Parameters:
        `file` - file to append to
        `data` - data to append
      Throws:
        `java.io.IOException` - on write errors

    - #### append

          public static void append(@NotNull
                                    java.io.File file,
                                    @NotNull
                                    byte[] data,
                                    int offset,
                                    int length)
                             throws java.io.IOException

      Append the given bytes to a file.
      Parameters:
        `file` - file to append to
        `data` - data to append
        `offset` - start offset into the byte array
        `length` - number of bytes to be written
      Throws:
        `java.io.IOException` - on write errors

    - #### append

          public static void append(@NotNull
                                    java.lang.String file,
                                    @NotNull
                                    byte[] data)
                             throws java.io.IOException

      Append the given bytes to a file.
      Parameters:
        `file` - file to append to
        `data` - data to append
      Throws:
        `java.io.IOException` - on write errors

    - #### append

          public static void append(@NotNull
                                    java.lang.String file,
                                    @NotNull
                                    byte[] data,
                                    int offset,
                                    int length)
                             throws java.io.IOException

      Append the given bytes to a file.
      Parameters:
        `file` - file to append to
        `data` - data to append
        `offset` - the start offset into the byte array
        `length` - number of bytes to be written
      Throws:
        `java.io.IOException` - on write errors

    - #### deleteTree

          public static boolean deleteTree(@NotNull
                                           java.io.File file)

      Delete a file or file tree.

      If removing fails for whatever reason, further processing is stop and `false` returned.

      Parameters:
        `file` - file or directory
      Returns:
        `true` if deletion is complete
        `false` if deletion of the file or the tree (partially) failed

    - #### cleanup

          public static boolean cleanup(@NotNull
                                        java.io.File dir)

      Cleanup a directory by removing its content. If `dir` is not a directory, nothing will be deleted. If removing fails for whatever reason, further processing is stop and `false` returned.
      Parameters:
        `dir` - directory
      Returns:
        `true` if cleanup is complete
        `false` if cleanup of the directory (partially) failed

    - #### multiExpand

          @NotNull
          public static java.io.File multiExpand(@NotNull
                                                          java.io.File dir,
                                                          @NotNull
                                                          java.lang.String subPath)

      Append a complete path to a file. This method expects the system's default as a file separator.
      Parameters:
        `dir` - directory where paths are
        `subPath` - sub path, has to be relative
      Returns:
        evaluated file/directory

    - #### multiExpand

          public static java.io.File multiExpand(@NotNull
                                                 java.io.File dir,
                                                 char fileSeparator,
                                                 @NotNull
                                                 java.lang.String subPath)

      Append a complete path to a file.
      Parameters:
        `dir` - directory where paths are
        `fileSeparator` - file separator char, usually either `'/'` or ``\\``
        `subPath` - sub path, has to be relative
      Returns:
        evaluated file/directory

    - #### expand

          public static java.io.File expand(@NotNull
                                            java.io.File dir,
                                            @NotNull
                                            java.lang.String... subPath)

      Append multiple path items to a file.
      Parameters:
        `dir` - directory where paths are
        `subPath` - The sub path. User has to take care that the sub paths are valid file names and don't contain separator characters.
      Returns:
        evaluated file/directory

    - #### performGlobbing

          @NotNull
          public static java.util.List<java.io.File> performGlobbing(@NotNull
                                                                              java.io.File fileWithPossibleGlobbing)
                                                                       throws java.io.IOException

      Throws:
        `java.io.IOException`