com.bristle.javalib.io
Class FileUtil

java.lang.Object
  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