com.bristle.javalib.io
Class FileUtil

java.lang.Object
  extended by com.bristle.javalib.io.FileUtil

public class FileUtil
extends Object

This class contains utility routines for manipulating files.

Usage:
   - The typical scenario for using this class is:
       String s = FileUtil.getTextFileContents("/dir/filename.txt");

   - See the source code of the inner Tester class for more examples.
  
Assumptions:
Effects:
       - None.
Anticipated Changes:
Notes:
Implementation Notes:
Portability Issues:
Revision History:
   $Log$


Nested Class Summary
static class FileUtil.ExtensionFilenameFilter
          This class implements FilenameFilter, filtering based on one or more filename extensions.
static class FileUtil.FileDeleteException
          Thrown when an attempt to delete a file fails.
static class FileUtil.FileRenameException
          Thrown when an attempt to rename a file fails.
static class FileUtil.Tester
          Each class contains a Tester inner class with a main() for easier unit testing.
static class FileUtil.TooManyBytesException
          Thrown when an attempt is made to operate on too many bytes of data.
 
Field Summary
static long lngNO_MAX_BYTES
           
 
Constructor Summary
FileUtil()
           
 
Method Summary
static void appendToFile(String strFilename, String strString)
          Append the specified string to the specified file, opening and closing the file to do so.
static long copyBinaryFileToStream(String strFilenameIn, OutputStream streamOut, long lngMaxBytes)
          Copy the binary contents of the file with the specified name to the specified OutputStream, up to the specified number of bytes, returning the count of bytes written.
static void copyBinaryFileToWriter(String strFilename, Writer writer)
          Copy the contents of the specified binary file to the specified Writer.
static long copyBinaryFileToWriter(String strFilenameIn, Writer writerOut, long lngMaxBytes)
          Copy the binary contents of the file with the specified name to the specified Writer, up to the specified number of bytes, returning the count of bytes written.
static long copyBinaryStreamToFile(InputStream streamIn, String strFilenameOut, long lngMaxBytes)
          Copy the binary contents of the specified InputStream to the file with the specified name, up to the specified number of bytes, returning the count of bytes written.
static long copyBinaryStreamToStream(InputStream streamIn, OutputStream streamOut, long lngMaxBytes)
          Copy the binary contents of the specified InputStream to the specified OutputStream, up to the specified number of bytes, returning the count of bytes written.
static long copyBinaryStreamToWriter(InputStream streamIn, Writer writerOut, long lngMaxBytes)
          Copy the binary contents of the specified InputStream to the specified Writer, up to the specified number of bytes, returning the count of bytes written.
static void delete(String strFileName)
          Delete the file with the specified name.
static boolean deleteDirectoryTree(String strDirectoryName)
          Delete the directory tree with the specified name.
static boolean deleteIfExists(String strFileName)
          Delete the file with the specified name, if it exists, returning true if it existed and was successfully deleted.
static String getFileNameWithoutPath(String strFileName)
          Return the simple name, including extension, but not path, of the specified filename.
static String[] getSortedNames(File directory)
          Returns a sorted array of Strings naming the files and directories in the specified directory.
static String getTextFileContents(InputStream istream)
          Returns the contents of the requested text file as a string.
static String getTextFileContents(Reader reader)
          Returns the contents of the requested text file as a string.
static String getTextFileContents(String strFilename)
          Returns the contents of the requested text file as a string.
static String getTextFileContentsOrEmpty(InputStream istream)
          Returns the contents of the requested text file as a string, or the empty String ("") if no such file exists or any other error occurs.
static String getTextFileContentsOrEmpty(Reader reader)
          Returns the contents of the requested text file as a string, or the empty String ("") if no such file exists or any other error occurs.
static String getTextFileContentsOrEmpty(String strFilename)
          Returns the contents of the requested text file as a string, or the empty String ("") if no such file exists or any other error occurs.
static String getTextFileContentsOrNull(InputStream istream)
          Returns the contents of the requested text file as a string, or null if no such file exists or any other error occurs.
static String getTextFileContentsOrNull(Reader reader)
          Returns the contents of the requested text file as a string, or null if no such file exists or any other error occurs.
static String getTextFileContentsOrNull(String strFilename)
          Returns the contents of the requested text file as a string, or null if no such file exists or any other error occurs.
static void rename(String strOldFileName, String strNewFileName)
          Rename the file with the specified old name to the specified new name.
static long skipEntireStreamReturningCount(InputStream streamIn)
          Skip past all bytes in the specified InputStream, returning the count of bytes found.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

lngNO_MAX_BYTES

public static final long lngNO_MAX_BYTES
See Also:
Constant Field Values
Constructor Detail

FileUtil

public FileUtil()
Method Detail

getTextFileContents

public static String getTextFileContents(Reader reader)
                                  throws IOException
Returns the contents of the requested text file as a string.

Parameters:
reader - Reader of the file to get.
Returns:
Contents of the file as a string.
Throws:
IOException - When an error occurs reading the file.

getTextFileContentsOrNull

public static String getTextFileContentsOrNull(Reader reader)
Returns the contents of the requested text file as a string, or null if no such file exists or any other error occurs.

Parameters:
reader - Reader of the file to get.
Returns:
Contents of the file as a string.

getTextFileContentsOrEmpty

public static String getTextFileContentsOrEmpty(Reader reader)
Returns the contents of the requested text file as a string, or the empty String ("") if no such file exists or any other error occurs.

Parameters:
reader - Reader of the file to get.
Returns:
Contents of the file as a string.

getTextFileContents

public static String getTextFileContents(InputStream istream)
                                  throws IOException
Returns the contents of the requested text file as a string.

Parameters:
istream - InputStream of the file to get.
Returns:
Contents of the file as a string.
Throws:
IOException - When an error occurs reading the file.

getTextFileContentsOrNull

public static String getTextFileContentsOrNull(InputStream istream)
Returns the contents of the requested text file as a string, or null if no such file exists or any other error occurs.

Parameters:
istream - InputStream of the file to get.
Returns:
Contents of the file as a string.

getTextFileContentsOrEmpty

public static String getTextFileContentsOrEmpty(InputStream istream)
Returns the contents of the requested text file as a string, or the empty String ("") if no such file exists or any other error occurs.

Parameters:
istream - InputStream of the file to get.
Returns:
Contents of the file as a string.

getTextFileContents

public static String getTextFileContents(String strFilename)
                                  throws FileNotFoundException,
                                         IOException
Returns the contents of the requested text file as a string.

Parameters:
strFilename - String name of the file to get.
Returns:
Contents of the file as a string.
Throws:
FileNotFoundException - When the specified file is not found.
IOException - When an error occurs reading the file.

getTextFileContentsOrNull

public static String getTextFileContentsOrNull(String strFilename)
Returns the contents of the requested text file as a string, or null if no such file exists or any other error occurs.

Parameters:
strFilename - String name of the file to get.
Returns:
Contents of the file as a string.

getTextFileContentsOrEmpty

public static String getTextFileContentsOrEmpty(String strFilename)
Returns the contents of the requested text file as a string, or the empty String ("") if no such file exists or any other error occurs.

Parameters:
strFilename - String name of the file to get.
Returns:
Contents of the file as a string.

copyBinaryFileToWriter

public static void copyBinaryFileToWriter(String strFilename,
                                          Writer writer)
                                   throws FileNotFoundException,
                                          IOException
Copy the contents of the specified binary file to the specified Writer.

Parameters:
strFilename - Name of the file to copy.
writer - Writer to write to.
Throws:
FileNotFoundException - When binary file not found.
IOException - When an I/O error occurs reading the file or writing it to the Writer.

copyBinaryStreamToStream

public static long copyBinaryStreamToStream(InputStream streamIn,
                                            OutputStream streamOut,
                                            long lngMaxBytes)
                                     throws FileUtil.TooManyBytesException,
                                            IOException
Copy the binary contents of the specified InputStream to the specified OutputStream, up to the specified number of bytes, returning the count of bytes written.

Parameters:
streamIn - InputStream to read from
streamOut - OutputStream to write to
lngMaxBytes - Max number of bytes to copy, or lngNO_MAX_BYTES for unlimited
Returns:
Count of bytes written
Throws:
FileUtil.TooManyBytesException - When streamIn contains more than intMaxBytes, resulting in a partially copied binary stream.
IOException - When an I/O error occurs reading or writing a stream.

copyBinaryStreamToWriter

public static long copyBinaryStreamToWriter(InputStream streamIn,
                                            Writer writerOut,
                                            long lngMaxBytes)
                                     throws FileUtil.TooManyBytesException,
                                            IOException
Copy the binary contents of the specified InputStream to the specified Writer, up to the specified number of bytes, returning the count of bytes written.

Parameters:
streamIn - InputStream to read from
writerOut - Writer to write to
lngMaxBytes - Max number of bytes to copy, or lngNO_MAX_BYTES for unlimited
Returns:
Count of bytes written
Throws:
FileUtil.TooManyBytesException - When streamIn contains more than intMaxBytes, resulting in a partially copied binary stream.
IOException - When an I/O error occurs reading or writing a stream or Writer.

copyBinaryStreamToFile

public static long copyBinaryStreamToFile(InputStream streamIn,
                                          String strFilenameOut,
                                          long lngMaxBytes)
                                   throws FileUtil.TooManyBytesException,
                                          FileNotFoundException,
                                          IOException
Copy the binary contents of the specified InputStream to the file with the specified name, up to the specified number of bytes, returning the count of bytes written.

Parameters:
streamIn - InputStream to read from
strFilenameOut - String name of the file to write to
lngMaxBytes - Max number of bytes to copy, or lngNO_MAX_BYTES for unlimited
Returns:
Count of bytes written
Throws:
FileUtil.TooManyBytesException - When streamIn contains more than intMaxBytes, resulting in a partially copied binary stream. The file is still closed properly.
FileNotFoundException - When the output file cannot be created or written.
IOException - When an I/O error occurs reading or writing a stream or file.

copyBinaryFileToStream

public static long copyBinaryFileToStream(String strFilenameIn,
                                          OutputStream streamOut,
                                          long lngMaxBytes)
                                   throws FileUtil.TooManyBytesException,
                                          FileNotFoundException,
                                          IOException
Copy the binary contents of the file with the specified name to the specified OutputStream, up to the specified number of bytes, returning the count of bytes written.

Parameters:
strFilenameIn - String name of the file to read from
streamOut - OutputStream to write to
lngMaxBytes - Max number of bytes to copy, or lngNO_MAX_BYTES for unlimited
Returns:
Count of bytes written
Throws:
FileUtil.TooManyBytesException - When the input file contains more than intMaxBytes, resulting in a partially copied binary stream. The input file is still closed properly, and the output stream is flushed.
FileNotFoundException - When the input file cannot be found or read.
IOException - When an I/O error occurs reading or writing a stream or file.

copyBinaryFileToWriter

public static long copyBinaryFileToWriter(String strFilenameIn,
                                          Writer writerOut,
                                          long lngMaxBytes)
                                   throws FileUtil.TooManyBytesException,
                                          FileNotFoundException,
                                          IOException
Copy the binary contents of the file with the specified name to the specified Writer, up to the specified number of bytes, returning the count of bytes written.

Parameters:
strFilenameIn - String name of the file to read from
writerOut - Writer to write to
lngMaxBytes - Max number of bytes to copy, or lngNO_MAX_BYTES for unlimited
Returns:
Count of bytes written
Throws:
FileUtil.TooManyBytesException - When the input file contains more than intMaxBytes, resulting in a partially copied binary stream. The input file is still closed properly, and the Writer is flushed.
FileNotFoundException - When the input file cannot be found or read.
IOException - When an I/O error occurs reading or writing a Writer or file.

skipEntireStreamReturningCount

public static long skipEntireStreamReturningCount(InputStream streamIn)
                                           throws IOException
Skip past all bytes in the specified InputStream, returning the count of bytes found.

Parameters:
streamIn - InputStream to read from
Returns:
Count of bytes found in the stream.
Throws:
IOException - When an I/O error occurs reading or writing a stream.

appendToFile

public static void appendToFile(String strFilename,
                                String strString)
                         throws IOException
Append the specified string to the specified file, opening and closing the file to do so.

Parameters:
strFilename - String name of the file to get.
strString - String to append to the file.
Throws:
IOException - When an error occurs writing the file.

getSortedNames

public static String[] getSortedNames(File directory)
Returns a sorted array of Strings naming the files and directories in the specified directory.

Parameters:
directory - The directory to search
Returns:
Sorted array of file and directories in the directory.

rename

public static void rename(String strOldFileName,
                          String strNewFileName)
                   throws FileUtil.FileRenameException
Rename the file with the specified old name to the specified new name.

Parameters:
strOldFileName - Old name of the file.
strNewFileName - New name of the file.
Throws:
FileUtil.FileRenameException - When unable to rename the file.

deleteIfExists

public static boolean deleteIfExists(String strFileName)
Delete the file with the specified name, if it exists, returning true if it existed and was successfully deleted.

Parameters:
strFileName - Name of the file to delete.

delete

public static void delete(String strFileName)
                   throws FileUtil.FileDeleteException
Delete the file with the specified name.

Parameters:
strFileName - Name of the file to delete.
Throws:
FileUtil.FileDeleteException - When unable to delete the file.

deleteDirectoryTree

public static boolean deleteDirectoryTree(String strDirectoryName)
Delete the directory tree with the specified name. Note: This uses a brute force approach, failing on all non-empty directories potentially multiple times before finally emptying them all and succeeding. It would be better to use a post-order iterator, one that returns the contents of a subdirectory before returning the subdirectory itself. It also deletes files as they are being iterated, which may confuse the iteration, generating errors before finally succeeding. It would be better to use an iterator that implements delete(), or to collect the names first and delete afterwards. For now, this works, and is useful for cleaning after the test cases of FileTreeIterator.

Parameters:
strDirectoryName - String name of the directory tree to delete.
Returns:
True if successful; false otherwise. Can fail if a file is locked or protected, for example.

getFileNameWithoutPath

public static String getFileNameWithoutPath(String strFileName)
Return the simple name, including extension, but not path, of the specified filename. Note: This only works for filenames that use the syntax of the native OS. To parse Windows filenames on a Unix system, or vice versa, for example, when uploading files from a Web browser to a Web server and parsing the filenames sent by the browser, use org.apache.commons.io.FilenameUtils.getName() instead.

Parameters:
strFileName - File name
Returns:
Simple file name