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

Methods
`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.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` `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 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, finalize, 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 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.

#### 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:
  `If` - an IO error occurs.
  `java.io.IOException`

#### 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:
  `If` - an IO error occurs.
  `java.io.IOException`

#### 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:
  `If` - an IO error occurs.
  `java.io.IOException`

#### 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:
  `If` - an IO error occurs.
  `java.io.IOException`

#### 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:
  `If` - the file cannot be found.
  `java.io.FileNotFoundException`

#### 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`