Package com.pixelmed.utils

## Class FileUtilities

- java.lang.Object
- - com.pixelmed.utils.FileUtilities

-     public class FileUtilities
      extends java.lang.Object

  Various static methods helpful for handling files.

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static java.lang.String` | `digest​(java.io.InputStream in, java.lang.String algorithm)` | Return a message digest of an InputStream.
    `static java.lang.String` | `digest​(java.lang.String fileName, java.lang.String algorithm)` | Return a message digest of a file.
    `static java.util.ArrayList<java.lang.String>` | `getCanonicalFileNames​(java.util.ArrayList<java.io.File> files)` |
    `static java.io.File` | `getFileFromNameInsensitiveToCaseIfNecessary​(java.lang.String fileName)` | Determine if a file corresponding to the specified name exists, checking for case insensitive variants if necessary.
    `static java.util.List<java.lang.String>` | `getFilePathComponents​(java.io.File path)` | Get the individual components of the canonical form of the path as a list.
    `static java.util.ArrayList<java.io.File>` | `listFilesRecursively​(java.io.File initialPath)` | Recursively traverse the specified directory and its sub-directory and produce a list of all the files contained therein, in no particular order.
    `static java.lang.String` | `makePathToFileInUsersHomeDirectory​(java.lang.String fileName)` | Given a file name, such as the properties file name, make a path to it in the user's home directory.
    `static java.io.File` | `makeSameRelativePathNameInDifferentFolder​(java.io.File srcFolder, java.io.File dstFolder, java.io.File srcFile)` | Create a new path that re-creates the relative path of the source file in the destination folder.
    `static java.io.File` | `makeSameRelativePathNameInDifferentFolder​(java.lang.String srcFolderName, java.lang.String dstFolderName, java.lang.String srcFileName)` | Create a new path that re-creates the relative path of the source file in the destination folder.
    `static java.lang.String` | `makeTemporaryFileName()` | Create a temporary filename.
    `static java.lang.String` | `md5​(java.io.InputStream in)` | Return an MD5 message digest of an InputStream.
    `static java.lang.String` | `md5​(java.lang.String fileName)` | Return an MD5 message digest of a file.
    `static byte[]` | `readAllBytes​(java.io.InputStream stream)` | Read an entire input stream, such as from a resource in a jar file, into an array of bytes.
    `static java.lang.String` | `readFile​(java.io.File file)` | Read an entire file into a string.
    `static java.lang.String` | `readFile​(java.io.InputStream stream)` | Read an entire file into a string.
    `static java.lang.String` | `readFile​(java.io.Reader reader)` | Read an entire file into a string.
    `static java.lang.String` | `readFile​(java.lang.String filename)` | Read an entire file into a string.
    `static void` | `renameElseCopyTo​(java.io.File srcFile, java.io.File dstFile)` | Rename a file, if possible, else make a copy of it.

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

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

- - ### Method Detail

    - #### renameElseCopyTo

          public static final void renameElseCopyTo​(java.io.File srcFile,
                                                    java.io.File dstFile)
                                             throws java.io.IOException

      Rename a file, if possible, else make a copy of it.

      Parameters:
        `srcFile` - the source
        `dstFile` - the destination
      Throws:
        `java.io.IOException` - thrown if the copying fails for any reason

    - #### listFilesRecursively

          public static final java.util.ArrayList<java.io.File> listFilesRecursively​(java.io.File initialPath)

      Recursively traverse the specified directory and its sub-directory and produce a list of all the files contained therein, in no particular order.

      If the path is a file, just return that.

      Any security (permission) exceptions are caught and logged to stderr and not propagated.

      Parameters:
        `initialPath` - The abstract pathname of the directory to begin searching
      Returns:
        An ArrayList of abstract pathnames denoting the files found. The ArrayList will be empty if the path is empty or does not exist or if an error occurs.

    - #### getCanonicalFileNames

          public static final java.util.ArrayList<java.lang.String> getCanonicalFileNames​(java.util.ArrayList<java.io.File> files)
                                                                                   throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### readFile

          public static final java.lang.String readFile​(java.io.Reader reader)
                                                 throws java.io.IOException

      Read an entire file into a string.

      Parameters:
        `reader` - The file reader
      Returns:
        The contents of the file as a `String`.
      Throws:
        `java.io.IOException` - If an IO error occurs.

    - #### readFile

          public static final java.lang.String readFile​(java.io.InputStream stream)
                                                 throws java.io.IOException

      Read an entire file into a string.

      Parameters:
        `stream` - The input stream (e.g., from `class.getResourceAsStream()`)
      Returns:
        The contents of the file as a `String`.
      Throws:
        `java.io.IOException` - If an IO error occurs.

    - #### readFile

          public static final java.lang.String readFile​(java.io.File file)
                                                 throws java.io.IOException

      Read an entire file into a string.

      Parameters:
        `file` - The file
      Returns:
        The contents of the file as a `String`.
      Throws:
        `java.io.IOException` - If an IO error occurs.

    - #### readFile

          public static final java.lang.String readFile​(java.lang.String filename)
                                                 throws java.io.IOException

      Read an entire file into a string.

      Parameters:
        `filename` - The file
      Returns:
        The contents of the file as a `String`.
      Throws:
        `java.io.IOException` - If an IO error occurs.

    - #### readAllBytes

          public static byte[] readAllBytes​(java.io.InputStream stream)
                                     throws java.io.IOException

      Read an entire input stream, such as from a resource in a jar file, into an array of bytes.

      Modelled after Files.readAllBytes(InputStream(Path path), from which the following description is paraphrased:

      Reads all the bytes from an input stream. The method ensures that the input stream is closed when all bytes have been read or an I/O error, or other runtime exception, is thrown.

      Note that this method is intended for simple cases where it is convenient to read all bytes into a byte array. It is not intended for reading in large input streams.

      Parameters:
        `stream` - The input stream (e.g., from `class.getResourceAsStream()`)
      Returns:
        The contents of the stream
      Throws:
        `java.io.IOException` - If an IO error occurs.

    - #### getFileFromNameInsensitiveToCaseIfNecessary

          public static final java.io.File getFileFromNameInsensitiveToCaseIfNecessary​(java.lang.String fileName)
                                                                                throws java.io.FileNotFoundException

      Determine if a file corresponding to the specified name exists, checking for case insensitive variants if necessary.

      Parameters:
        `fileName` - The name of the file to find
      Returns:
        A file if found.
      Throws:
        `java.io.FileNotFoundException` - If the file cannot be found.

    - #### makeTemporaryFileName

          public static final java.lang.String makeTemporaryFileName()

      Create a temporary filename.

      Returns:
        a string that does not include delimiter characters and is unique within this JVM.

    - #### makePathToFileInUsersHomeDirectory

          public static final java.lang.String makePathToFileInUsersHomeDirectory​(java.lang.String fileName)

      Given a file name, such as the properties file name, make a path to it in the user's home directory.

      Parameters:
        `fileName` - the file name to make a path to

    - #### digest

          public static final java.lang.String digest​(java.lang.String fileName,
                                                      java.lang.String algorithm)
                                               throws java.io.IOException,
                                                      java.security.NoSuchAlgorithmException

      Return a message digest of a file.

      Parameters:
        `fileName` - the file name
        `algorithm` - the digest algorithm, such as "MD5" or "SHA"
      Returns:
        string representation of the digest
      Throws:
        `java.io.IOException`
        `java.security.NoSuchAlgorithmException`

    - #### digest

          public static final java.lang.String digest​(java.io.InputStream in,
                                                      java.lang.String algorithm)
                                               throws java.io.IOException,
                                                      java.security.NoSuchAlgorithmException

      Return a message digest of an InputStream.

      Parameters:
        `in` - the InputStream
        `algorithm` - the digest algorithm, such as "MD5" or "SHA"
      Returns:
        string representation of the digest
      Throws:
        `java.io.IOException`
        `java.security.NoSuchAlgorithmException`

    - #### md5

          public static final java.lang.String md5​(java.lang.String fileName)
                                            throws java.io.IOException,
                                                   java.security.NoSuchAlgorithmException

      Return an MD5 message digest of a file.

      Parameters:
        `fileName` - the file name
      Returns:
        string representation of the digest
      Throws:
        `java.io.IOException`
        `java.security.NoSuchAlgorithmException`

    - #### md5

          public static final java.lang.String md5​(java.io.InputStream in)
                                            throws java.io.IOException,
                                                   java.security.NoSuchAlgorithmException

      Return an MD5 message digest of an InputStream.

      Parameters:
        `in` - the InputStream
      Returns:
        string representation of the digest
      Throws:
        `java.io.IOException`
        `java.security.NoSuchAlgorithmException`

    - #### getFilePathComponents

          public static java.util.List<java.lang.String> getFilePathComponents​(java.io.File path)
                                                                        throws java.io.IOException

      Get the individual components of the canonical form of the path as a list.

      Parameters:
        `path` -
      Returns:
        each component of the path, starting with the root
      Throws:
        `java.io.IOException`

    - #### makeSameRelativePathNameInDifferentFolder

          public static java.io.File makeSameRelativePathNameInDifferentFolder​(java.lang.String srcFolderName,
                                                                               java.lang.String dstFolderName,
                                                                               java.lang.String srcFileName)
                                                                        throws java.io.IOException

      Create a new path that re-creates the relative path of the source file in the destination folder.

      Parameters:
        `srcFolderName` -
        `dstFolderName` -
        `srcFileName` -
      Returns:
        a File in the destination folder
      Throws:
        `java.io.IOException`

    - #### makeSameRelativePathNameInDifferentFolder

          public static java.io.File makeSameRelativePathNameInDifferentFolder​(java.io.File srcFolder,
                                                                               java.io.File dstFolder,
                                                                               java.io.File srcFile)
                                                                        throws java.io.IOException

      Create a new path that re-creates the relative path of the source file in the destination folder.

      Parameters:
        `srcFolder` -
        `dstFolder` -
        `srcFile` -
      Returns:
        a File in the destination folder
      Throws:
        `java.io.IOException`