Package ca.corbett.extras.io

Class FileSystemUtil

java.lang.Object
ca.corbett.extras.io.FileSystemUtil
public class FileSystemUtil extends Object
Provides a number of handy static utility methods for working with files and directories. Searching for files by extension, reading and writing text files, sanitizing filenames, and more.
Since:
2012-07-28 (originally written for ICE, later generalized for ca.corbett.util)
Author:
scorbo2

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected static final Pattern
    INVALID_CHARS
     
    protected static final Pattern
    LEADING_DOTS
     
    protected static final Pattern
    WINDOWS_RESERVED
     

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    FileSystemUtil()
    Protected constructor to allow subclassing for application-specific utility methods while preventing direct instantiation of this utility class.

  • Method Summary

    Modifier and Type
    Method
    Description
    static String
    extractTextFileFromJar(String targetFilename, File jarFile)
    Looks for a small text file of the given name within the given Jar file, and returns its contents as a String if found.
    static String
    extractTextFileFromJar(String targetFilename, File jarFile, Charset charset)
    Looks for a small text file of the given name within the given Jar file, and returns its contents as a String if found.
    static List<File>
    findFiles(File rootDir, boolean recursive)
    Shorthand for findFiles without specifying a progress callback.
    static List<File>
    findFiles(File rootDir, boolean recursive, FileSearchListener listener)
    Scans the given directory (and optionally all of its subdirectories recursively) and will return a list of all files found.
    static List<File>
    findFiles(File rootDir, boolean recursive, String extension)
    Shorthand for findFiles without specifying a progress callback.
    static List<File>
    findFiles(File rootDir, boolean recursive, String extension, FileSearchListener listener)
    Scans the given directory (and optionally all of its subdirectories recursively) looking for files with the given extension.
    static List<File>
    findFiles(File rootDir, boolean recursive, List<String> extensions)
    Shorthand for findFiles without specifying a progress callback.
    static List<File>
    findFiles(File rootDir, boolean recursive, List<String> extensions, FileSearchListener listener)
    Scans the given directory (and optionally all of its subdirectories recursively) looking for files of one of the types specified in the given fileType list.
    static List<File>
    findFilesExcluding(File rootDir, boolean recursive, String extension)
    Shorthand for findFilesExcluding without specifying a progress callback.
    static List<File>
    findFilesExcluding(File rootDir, boolean recursive, String extension, FileSearchListener listener)
    Scans the given directory (and optionally all of its subdirectories recursively) looking for any files that do NOT match the given extension.
    static List<File>
    findFilesExcluding(File rootDir, boolean recursive, List<String> extensions)
    Shorthand for findFilesExcluding without specifying a progress callback.
    static List<File>
    findFilesExcluding(File rootDir, boolean recursive, List<String> extensions, FileSearchListener listener)
    Scans the given directory (and optionally all of its subdirectories recursively) looking for any files that do NOT match one of the given extensions.
    protected static List<File>
    findFilesRecurse(File rootDir, boolean recursive, Set<String> extSet, FileSearchListener listener, boolean invertSearch)
    Internally invoked as needed from findFiles to recurse through a directory structure.
    static List<File>
    findSubdirectories(File rootDir, boolean recursive)
    Shorthand for findSubdirectories without specifying a progress callback.
    static List<File>
    findSubdirectories(File rootDir, boolean recursive, FileSearchListener listener)
    Scans the given directory (and optionally all of its subdirectories recursively) and will return a list of all subdirectories found.
    protected static List<File>
    findSubdirectoriesInternal(File rootDir, boolean recursive, FileSearchListener listener)
    Invoked internally from findSubdirectories to do the actual work recursively.
    static String
    getPrintableSize(long size)
    Given a count of bytes, returns a human-readable String representation of it.
    static File
    getUniqueDestinationFile(File destinationDir, File candidateFile)
    Given a destination directory and a candidate File that we want to copy or move there, this method will check for name conflicts in the destination, and return a File object representing a unique filename within the destination directory.
    static List<String>
    readFileLines(File in)
    Reads each line of the given input file and returns them in a list, with line delimiters stripped out.
    static List<String>
    readFileLines(File in, String charset)
    Reads each line of the given input file and returns them in a list, with line delimiters stripped out.
    static String
    readFileToString(File in)
    Reads the contents of the given text file into a single String, which will include line delimiters as present in the file.
    static String
    readFileToString(File in, String charset)
    Reads the contents of the given text file into a single String using the given Charset.
    static String
    readStreamToString(InputStream in)
    Reads the contents of the given InputStream as one big String and returns it.
    static String
    readStreamToString(InputStream in, String charset)
    Reads the contents of the given InputStream as one big String and returns it.
    static String
    sanitizeFilename(String input)
    Given any arbitrary String, returns a sanitized version that is safe to use as a filename on any operating system.
    static String
    sanitizeFilename(String input, String defaultName)
    Given any arbitrary String, returns a sanitized version that is safe to use as a filename on any operating system.
    static void
    sortFiles(List<File> fileList)
    Sorts the given list of File objects by their name, in a non-retarded way (by default, Arrays.sort will sort upper case letters before lower case letters, such that A, B, and C will come before a, b, and c - but this is rarely expected).
    static void
    writeLinesToFile(List<String> lines, File out)
    Writes the given lines to the given output file using a default charset of UTF-8 and the System line delimiter.
    static void
    writeLinesToFile(List<String> lines, File out, String charset)
    Writes the given lines to the given output file using the given charset and the System line delimiter.
    static void
    writeStringToFile(String str, File out)
    Writes the given String as-is to the given File.
    static void
    writeStringToFile(String str, File out, String charset)
    Writes the given String as-is to the given File.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • INVALID_CHARS

      protected static final Pattern INVALID_CHARS

    • LEADING_DOTS

      protected static final Pattern LEADING_DOTS

    • WINDOWS_RESERVED

      protected static final Pattern WINDOWS_RESERVED

  • Constructor Details

    • FileSystemUtil

      protected FileSystemUtil()
      Protected constructor to allow subclassing for application-specific utility methods while preventing direct instantiation of this utility class.

  • Method Details

    • findFiles

      public static List<File> findFiles(File rootDir, boolean recursive, String extension)
      Shorthand for findFiles without specifying a progress callback. See findFiles(File,boolean,String,FileSearchListener) for details.
      Parameters:
      rootDir - see findFiles(File,boolean,String,FileSearchListener) for details.
      recursive - see findFiles(File,boolean,String,FileSearchListener) for details.
      extension - see findFiles(File,boolean,String,FileSearchListener) for details.
      Returns:
      see findFiles(File,boolean,String,FileSearchListener) for details.

    • findFiles

      public static List<File> findFiles(File rootDir, boolean recursive, List<String> extensions)
      Shorthand for findFiles without specifying a progress callback. See findFiles(File,boolean,List,FileSearchListener) for details.
      Parameters:
      rootDir - see findFiles(File,boolean,List,FileSearchListener) for details.
      recursive - see findFiles(File,boolean,List,FileSearchListener) for details.
      extensions - see findFiles(File,boolean,List,FileSearchListener) for details.
      Returns:
      see findFiles(File,boolean,List,FileSearchListener) for details.

    • findFiles

      public static List<File> findFiles(File rootDir, boolean recursive, String extension, FileSearchListener listener)
      Scans the given directory (and optionally all of its subdirectories recursively) looking for files with the given extension. Files matching the extension will be returned, while all other files will be excluded.
      Parameters:
      rootDir - The root directory for the search. Must exist and be readable.
      recursive - Indicates whether to search sub directories also or not.
      extension - A file extensions (eg "jpg") to search for.
      listener - A FileSearchListener which will receive notice for each file found.
      Returns:
      An array of File objects, one for each file discovered in the search.

    • findFiles

      public static List<File> findFiles(File rootDir, boolean recursive, List<String> extensions, FileSearchListener listener)
      Scans the given directory (and optionally all of its subdirectories recursively) looking for files of one of the types specified in the given fileType list. Files matching any of the extensions in that list will be returned, while all other files will be excluded.
      Parameters:
      rootDir - The root directory for the search. Must exist and be readable.
      recursive - Indicates whether to search sub directories also or not.
      extensions - A list of file extensions (eg "jpg") to search for.
      listener - A FileSearchListener which will receive notice for each file found.
      Returns:
      An array of File objects, one for each file discovered in the search.

    • findFilesRecurse

      protected static List<File> findFilesRecurse(File rootDir, boolean recursive, Set<String> extSet, FileSearchListener listener, boolean invertSearch)
      Internally invoked as needed from findFiles to recurse through a directory structure.

    • findFilesExcluding

      public static List<File> findFilesExcluding(File rootDir, boolean recursive, String extension)
      Shorthand for findFilesExcluding without specifying a progress callback. See findFilesExcluding(File,boolean,String,FileSearchListener) for details.
      Parameters:
      rootDir - see findFilesExcluding(File,boolean,String,FileSearchListener) for details.
      recursive - see findFilesExcluding(File,boolean,String,FileSearchListener) for details.
      extension - see findFilesExcluding(File,boolean,String,FileSearchListener) for details.
      Returns:
      see findFilesExcluding(File,boolean,String,FileSearchListener) for details.

    • findFilesExcluding

      public static List<File> findFilesExcluding(File rootDir, boolean recursive, List<String> extensions)
      Shorthand for findFilesExcluding without specifying a progress callback. See findFilesExcluding(File,boolean,List,FileSearchListener) for details.
      Parameters:
      rootDir - see findFilesExcluding(File,boolean,List,FileSearchListener) for details.
      recursive - see findFilesExcluding(File,boolean,List,FileSearchListener) for details.
      extensions - see findFilesExcluding(File,boolean,List,FileSearchListener) for details.
      Returns:
      see findFilesExcluding(File,boolean,List,FileSearchListener) for details.

    • findFilesExcluding

      public static List<File> findFilesExcluding(File rootDir, boolean recursive, String extension, FileSearchListener listener)
      Scans the given directory (and optionally all of its subdirectories recursively) looking for any files that do NOT match the given extension. Files that do not match the given extension are returned, while all other files will be excluded.
      Parameters:
      rootDir - The root directory for the search. Must exist and be readable.
      recursive - Indicates whether to search sub directories also or not.
      extension - A file extension (eg "jpg") to exclude from the search.
      listener - A FileSearchListener which will receive updates as files are found.
      Returns:
      An array of File objects, one for each file that does not match the given extensions.

    • findFilesExcluding

      public static List<File> findFilesExcluding(File rootDir, boolean recursive, List<String> extensions, FileSearchListener listener)
      Scans the given directory (and optionally all of its subdirectories recursively) looking for any files that do NOT match one of the given extensions. Files that do not match any of the given extensions are returned, while all other files will be excluded. To find and return ALL files, leave "extensions" empty.
      Parameters:
      rootDir - The root directory for the search. Must exist and be readable.
      recursive - Indicates whether to search sub directories also or not.
      extensions - A list of file extensions (eg "jpg") to exclude from the search.
      listener - A FileSearchListener which will receive updates as files are found.
      Returns:
      An array of File objects, one for each file that does not match the given extensions.

    • findFiles

      public static List<File> findFiles(File rootDir, boolean recursive)
      Shorthand for findFiles without specifying a progress callback. See findFiles(File,boolean,FileSearchListener) for details.
      Parameters:
      rootDir - see findFiles(File,boolean,FileSearchListener) for details.
      recursive - see findFiles(File,boolean,FileSearchListener) for details.
      Returns:
      see findFiles(File,boolean,FileSearchListener) for details.

    • findFiles

      public static List<File> findFiles(File rootDir, boolean recursive, FileSearchListener listener)
      Scans the given directory (and optionally all of its subdirectories recursively) and will return a list of all files found.
      Parameters:
      rootDir - The root directory for the search. Must exist and be readable.
      recursive - Indicates whether to search sub directories also or not.
      listener - A FileSearchListener that will receive updates about files found.
      Returns:
      A list of File objects, one for each file found.

    • findSubdirectories

      public static List<File> findSubdirectories(File rootDir, boolean recursive)
      Shorthand for findSubdirectories without specifying a progress callback. See findSubdirectories(File,boolean,FileSearchListener) for details.
      Parameters:
      rootDir - see findSubdirectories(File,boolean,FileSearchListener) for details.
      recursive - see findSubdirectories(File,boolean,FileSearchListener) for details.
      Returns:
      see findSubdirectories(File,boolean,FileSearchListener) for details.

    • findSubdirectories

      public static List<File> findSubdirectories(File rootDir, boolean recursive, FileSearchListener listener)
      Scans the given directory (and optionally all of its subdirectories recursively) and will return a list of all subdirectories found. The given root directory is NOT included in the results - only subdirectories. The returned list is sorted by full path name.
      Parameters:
      rootDir - The root directory for the search. Must exist and be readable.
      recursive - Indicates whether to search subdirectories also or not.
      listener - A FileSearchListener which will receive updates about found dirs.
      Returns:
      A list of directories, sorted by absolute path.

    • findSubdirectoriesInternal

      protected static List<File> findSubdirectoriesInternal(File rootDir, boolean recursive, FileSearchListener listener)
      Invoked internally from findSubdirectories to do the actual work recursively. This is pushed to a separate method so we can do sorting once after the recursive search is complete.
      Parameters:
      rootDir - The root directory for the search. Must exist and be readable.
      recursive - Indicates whether to search subdirectories also or not.
      listener - A FileSearchListener which will receive updates about found dirs.
      Returns:
      An unsorted list of directories.

    • sortFiles

      public static void sortFiles(List<File> fileList)
      Sorts the given list of File objects by their name, in a non-retarded way (by default, Arrays.sort will sort upper case letters before lower case letters, such that A, B, and C will come before a, b, and c - but this is rarely expected).
      Parameters:
      fileList - The list of files to sort. Will be sorted in place.

    • readFileToString

      public static String readFileToString(File in) throws IOException
      Reads the contents of the given text file into a single String, which will include line delimiters as present in the file. No check on file size or content is done here, so us with caution... larger files may cause problems. By default, we assume a charset of UTF-8 (a pretty safe default), but you can use readFileToString(File,String) to override that.

      If you prefer to iterate over the lines in the file one by one, use readFileLines() instead.

      Parameters:
      in - Any text file.
      Returns:
      The contents of the file as one single String including line delimiters.
      Throws:
      IOException - If something goes wrong.

    • readFileToString

      public static String readFileToString(File in, String charset) throws IOException
      Reads the contents of the given text file into a single String using the given Charset. This will include line delimiters as present in the file. No check on file size or content is done here, so us with caution... larger files may cause problems.

      If you prefer to iterate over the lines in the file one by one, use readFileLines() instead.

      Parameters:
      in - Any text file.
      charset - The name of the charset to use.
      Returns:
      The contents of the file as one single String including line delimiters.
      Throws:
      IOException - If something goes wrong.

    • readFileLines

      public static List<String> readFileLines(File in) throws IOException
      Reads each line of the given input file and returns them in a list, with line delimiters stripped out. No check on file size or content is done here, so use with caution... larger files may cause problems. By default, we assume a charset of UTF-8 (a pretty safe default), but you can use readFileLines(File, String) to override this.

      If you prefer to grab the file contents as one big String instead of a collection of individual lines, use readFileToString() instead.

      Parameters:
      in - Any text file.
      Returns:
      A List of lines from the file, with line delimiters stripped out.
      Throws:
      IOException - If something goes wrong.

    • readFileLines

      public static List<String> readFileLines(File in, String charset) throws IOException
      Reads each line of the given input file and returns them in a list, with line delimiters stripped out. No check on file size or content is done here, so use with caution... larger files may cause problems.

      If you prefer to grab the file contents as one big String instead of a collection of individual lines, use readFileToString() instead.

      Parameters:
      in - Any text file.
      charset - The charset to use.
      Returns:
      A List of lines from the file, with line delimiters stripped out.
      Throws:
      IOException - If something goes wrong.

    • readStreamToString

      public static String readStreamToString(InputStream in) throws IOException
      Reads the contents of the given InputStream as one big String and returns it. If the InputStream is considerably large, this operation may consume time and memory in huge quantities. By default, we assume a charsetof UTF-8 (a pretty safe default), but you can use readStreamToString(InputStream, String) to override this.
      Parameters:
      in - Any InputStream.
      Returns:
      The contents of the InputStream as one long String.
      Throws:
      IOException - If something goes wrong

    • readStreamToString

      public static String readStreamToString(InputStream in, String charset) throws IOException
      Reads the contents of the given InputStream as one big String and returns it. If the InputStream is considerably large, this operation may consume time and memory in huge quantities.
      Parameters:
      in - Any InputStream.
      charset - The Charset to use.
      Returns:
      The contents of the InputStream as one long String.
      Throws:
      IOException - If something goes wrong

    • writeStringToFile

      public static void writeStringToFile(String str, File out) throws IOException
      Writes the given String as-is to the given File. By default, we use UTF-8 for the charset, but you can use writeStringToFile(String, File, String) to override this.
      Parameters:
      str - Any String
      out - Any writable File
      Throws:
      IOException - If something goes wrong

    • writeStringToFile

      public static void writeStringToFile(String str, File out, String charset) throws IOException
      Writes the given String as-is to the given File.
      Parameters:
      str - Any String
      out - Any writable File
      charset - The name of the charset to use.
      Throws:
      IOException - If something goes wrong

    • writeLinesToFile

      public static void writeLinesToFile(List<String> lines, File out) throws IOException
      Writes the given lines to the given output file using a default charset of UTF-8 and the System line delimiter.
      Parameters:
      lines - A List of Strings.
      out - Any writable File. Will be overwritten if exists.
      Throws:
      IOException - If something goes wrong.

    • writeLinesToFile

      public static void writeLinesToFile(List<String> lines, File out, String charset) throws IOException
      Writes the given lines to the given output file using the given charset and the System line delimiter.
      Parameters:
      lines - A List of Strings.
      out - Any writable File. Will be overwritten if exists.
      charset - The Charset to use.
      Throws:
      IOException - If something goes wrong.

    • getPrintableSize

      public static String getPrintableSize(long size)
      Given a count of bytes, returns a human-readable String representation of it.

    • extractTextFileFromJar

      public static String extractTextFileFromJar(String targetFilename, File jarFile) throws Exception
      Looks for a small text file of the given name within the given Jar file, and returns its contents as a String if found. If not found, returns null. If the file appears to be binary data, an exception is thrown.
      Throws:
      Exception

    • extractTextFileFromJar

      public static String extractTextFileFromJar(String targetFilename, File jarFile, Charset charset) throws Exception
      Looks for a small text file of the given name within the given Jar file, and returns its contents as a String if found. If not found, returns null. If the file appears to be binary data, an exception is thrown.
      Throws:
      Exception

    • sanitizeFilename

      public static String sanitizeFilename(String input)
      Given any arbitrary String, returns a sanitized version that is safe to use as a filename on any operating system. If the given input is null or empty, or if the resulting sanitized filename is empty, "unnamed" will be returned.

      The only allowable characters are alphanumeric characters, dots (.), hyphens (-), and underscores (_). All other characters are replaced with underscores. Leading dots are removed. On Windows, reserved filenames such as "CON" or "AUX" are prefixed with an underscore. The resulting filename is truncated to a maximum of 200 characters.

    • sanitizeFilename

      public static String sanitizeFilename(String input, String defaultName)
      Given any arbitrary String, returns a sanitized version that is safe to use as a filename on any operating system. If the given input is null or empty, or if the resulting sanitized filename is empty, the given defaultName will be returned.

      The only allowable characters are alphanumeric characters, dots (.), hyphens (-), and underscores (_). All other characters are replaced with underscores. Leading dots are removed. On Windows, reserved filenames such as "CON" or "AUX" are prefixed with an underscore. The resulting filename is truncated to a maximum of 200 characters.

    • getUniqueDestinationFile

      public static File getUniqueDestinationFile(File destinationDir, File candidateFile)
      Given a destination directory and a candidate File that we want to copy or move there, this method will check for name conflicts in the destination, and return a File object representing a unique filename within the destination directory. If a file with the original name already exists, a number will be appended to the name (before the extension) to make it unique.

      Both destinationDir and candidateFile must be non-null. If either argument is null, this method will throw an IllegalArgumentException.

      Parameters:
      destinationDir - The directory where we want to place the file. Must exist and must be a directory.
      candidateFile - The File we want to copy or move to the destination directory.
      Returns:
      A File object representing a unique filename within the destination directory.