org.unitils.thirdparty.org.apache.commons.io

Class FileUtils

java.lang.Object

org.unitils.thirdparty.org.apache.commons.io.FileUtils

public class FileUtils
extends Object

General file manipulation utilities.

Facilities are provided in the following areas:

• writing to a file
• reading from a file
• make a directory including parent directories
• copying files and directories
• deleting files and directories
• converting to and from a URL
• listing files and directories by filter and extension
• comparing file content
• file last changed date

Origin of code: Excalibur, Alexandria, Commons-Utils

Version:

$Id: FileUtils.java 384037 2006-03-07 22:26:37Z scolebourne $

Author:

Kevin A. Burton, Scott Sanders, Daniel Rall, Christoph.Reck, Peter Donald, Jeff Turner, Matthew Hawthorne, Jeremias Maerki, Stephen Colebourne, Ian Springer, Chris Eldredge, Jim Harrington, Niall Pemberton, Sandy McArthur

Field Summary

Fields

Modifier and Type	Field and Description
static File[]	EMPTY_FILE_ARRAY An empty array of type File.
static long	ONE_GB The number of bytes in a gigabyte.
static long	ONE_KB The number of bytes in a kilobyte.
static long	ONE_MB The number of bytes in a megabyte.

Constructor Summary

Constructors

Constructor and Description
FileUtils() Instances should NOT be constructed in standard programming.

Method Summary

Methods

Modifier and Type	Method and Description
static String	byteCountToDisplaySize(long size) Returns a human-readable version of the file size, where the input represents a specific number of bytes.
static void	cleanDirectory(File directory) Clean a directory without deleting it.
static boolean	contentEquals(File file1, File file2) Compare the contents of two files to determine if they are equal or not.
static File[]	convertFileCollectionToFileArray(Collection<?> files) Converts a Collection containing java.io.File instanced into array representation.
static void	copyDirectory(File srcDir, File destDir) Copies a whole directory to a new location preserving the file dates.
static void	copyDirectory(File srcDir, File destDir, boolean preserveFileDate) Copies a whole directory to a new location.
static void	copyDirectoryToDirectory(File srcDir, File destDir) Copies a directory to within another directory preserving the file dates.
static void	copyFile(File srcFile, File destFile) Copies a file to a new location preserving the file date.
static void	copyFile(File srcFile, File destFile, boolean preserveFileDate) Copies a file to a new location.
static void	copyFileToDirectory(File srcFile, File destDir) Copies a file to a directory preserving the file date.
static void	copyURLToFile(URL source, File destination) Copies bytes from the URL source to a file destination.
static void	deleteDirectory(File directory) Recursively delete a directory.
static void	forceDelete(File file) Delete a file.
static void	forceDeleteOnExit(File file) Schedule a file to be deleted when JVM exits.
static void	forceMkdir(File directory) Make a directory, including any necessary but nonexistent parent directories.
static boolean	isFileNewer(File file, Date date) Tests if the specified File is newer than the specified Date.
static boolean	isFileNewer(File file, File reference) Tests if the specified File is newer than the reference File.
static boolean	isFileNewer(File file, long timeMillis) Tests if the specified File is newer than the specified time reference.
static String	readFileToString(File file, String encoding) Reads the contents of a file into a String.
static List	readLines(File file, String encoding) Reads the contents of a file line by line to a List of Strings.
static long	sizeOfDirectory(File directory) Recursively count size of a directory (sum of the length of all files).
static File	toFile(URL url) Convert from a URL to a File.
static File[]	toFiles(URL[] urls) Converts each of an array of URL to a File.
static void	touch(File file) Implements the same behaviour as the "touch" utility on Unix.
static URL[]	toURLs(File[] files) Converts each of an array of File to a URL.
static boolean	waitFor(File file, int seconds) Waits for NFS to propagate a file creation, imposing a timeout.
static void	writeByteArrayToFile(File file, byte[] data) Writes a byte array to a file creating the file if it does not exist.
static void	writeLines(File file, String encoding, Collection<?> lines) Writes the toString() value of each item in a collection to the specified File line by line.
static void	writeLines(File file, String encoding, Collection<?> lines, String lineEnding) Writes the toString() value of each item in a collection to the specified File line by line.
static void	writeStringToFile(File file, String data, String encoding) Writes a String to a file creating the file if it does not exist.

Methods inherited from class java.lang.Object

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

Field Detail

ONE_KB

public static final long ONE_KB

The number of bytes in a kilobyte.

See Also:

Constant Field Values

ONE_MB

public static final long ONE_MB

The number of bytes in a megabyte.

See Also:

Constant Field Values

ONE_GB

public static final long ONE_GB

The number of bytes in a gigabyte.

See Also:

Constant Field Values

EMPTY_FILE_ARRAY

public static final File[] EMPTY_FILE_ARRAY

An empty array of type File.

Constructor Detail

FileUtils

public FileUtils()

Instances should NOT be constructed in standard programming.

Method Detail

byteCountToDisplaySize

public static String byteCountToDisplaySize(long size)

Returns a human-readable version of the file size, where the input represents a specific number of bytes.

Parameters:

size - the number of bytes

Returns:

a human-readable display value (includes units)

touch

public static void touch(File file)
                  throws IOException

Implements the same behaviour as the "touch" utility on Unix. It creates a new file with size 0 or, if the file exists already, it is opened and closed without modifying it, but updating the file date and time.

Parameters:

file - the File to touch

Throws:

IOException - If an I/O problem occurs

convertFileCollectionToFileArray

public static File[] convertFileCollectionToFileArray(Collection<?> files)

Converts a Collection containing java.io.File instanced into array representation. This is to account for the difference between File.listFiles() and FileUtils.listFiles().

Parameters:

files - a Collection containing java.io.File instances

Returns:

an array of java.io.File

contentEquals

public static boolean contentEquals(File file1,
                    File file2)
                             throws IOException

Compare the contents of two files to determine if they are equal or not.

This method checks to see if the two files are different lengths or if they point to the same file, before resorting to byte-by-byte comparison of the contents.

Code origin: Avalon

Parameters:

file1 - the first file

file2 - the second file

Returns:

true if the content of the files are equal or they both don't exist, false otherwise

Throws:

IOException - in case of an I/O error

toFile

public static File toFile(URL url)

Convert from a URL to a File.

From version 1.1 this method will decode the URL. Syntax such as file:///my%20docs/file.txt will be correctly decoded to /my docs/file.txt.

Parameters:

url - the file URL to convert, null returns null

Returns:

the equivalent File object, or null if the URL's protocol is not file

Throws:

IllegalArgumentException - if the file is incorrectly encoded

toFiles

public static File[] toFiles(URL[] urls)

Converts each of an array of URL to a File.

Returns an array of the same size as the input. If the input is null, an empty array is returned. If the input contains null, the output array contains null at the same index.

This method will decode the URL. Syntax such as file:///my%20docs/file.txt will be correctly decoded to /my docs/file.txt.

Parameters:

urls - the file URLs to convert, null returns empty array

Returns:

a non-null array of Files matching the input, with a null item if there was a null at that index in the input array

Throws:

IllegalArgumentException - if any file is not a URL file

IllegalArgumentException - if any file is incorrectly encoded

Since:

Commons IO 1.1

toURLs

public static URL[] toURLs(File[] files)
                    throws IOException

Converts each of an array of File to a URL.

Returns an array of the same size as the input.

Parameters:

files - the files to convert

Returns:

an array of URLs matching the input

Throws:

IOException - if a file cannot be converted

copyFileToDirectory

public static void copyFileToDirectory(File srcFile,
                       File destDir)
                                throws IOException

Copies a file to a directory preserving the file date.

This method copies the contents of the specified source file to a file of the same name in the specified destination directory. The destination directory is created if it does not exist. If the destination file exists, then this method will overwrite it.

Parameters:

srcFile - an existing file to copy, must not be null

destDir - the directory to place the copy in, must not be null

Throws:

NullPointerException - if source or destination is null

IOException - if source or destination is invalid

IOException - if an IO error occurs during copying

See Also:

copyFile(File, File, boolean)

copyFile

public static void copyFile(File srcFile,
            File destFile)
                     throws IOException

Copies a file to a new location preserving the file date.

This method copies the contents of the specified source file to the specified destination file. The directory holding the destination file is created if it does not exist. If the destination file exists, then this method will overwrite it.

Parameters:

srcFile - an existing file to copy, must not be null

destFile - the new file, must not be null

Throws:

NullPointerException - if source or destination is null

IOException - if source or destination is invalid

IOException - if an IO error occurs during copying

See Also:

copyFileToDirectory(java.io.File, java.io.File)

copyFile

public static void copyFile(File srcFile,
            File destFile,
            boolean preserveFileDate)
                     throws IOException

Copies a file to a new location.

This method copies the contents of the specified source file to the specified destination file. The directory holding the destination file is created if it does not exist. If the destination file exists, then this method will overwrite it.

Parameters:

srcFile - an existing file to copy, must not be null

destFile - the new file, must not be null

preserveFileDate - true if the file date of the copy should be the same as the original

Throws:

NullPointerException - if source or destination is null

IOException - if source or destination is invalid

IOException - if an IO error occurs during copying

See Also:

copyFileToDirectory(java.io.File, java.io.File)

copyDirectoryToDirectory

public static void copyDirectoryToDirectory(File srcDir,
                            File destDir)
                                     throws IOException

Copies a directory to within another directory preserving the file dates.

This method copies the source directory and all its contents to a directory of the same name in the specified destination directory.

The destination directory is created if it does not exist. If the destination directory did exist, then this method merges the source with the destination, with the source taking precedence.

Parameters:

srcDir - an existing directory to copy, must not be null

destDir - the directory to place the copy in, must not be null

Throws:

NullPointerException - if source or destination is null

IOException - if source or destination is invalid

IOException - if an IO error occurs during copying

Since:

Commons IO 1.2

copyDirectory

public static void copyDirectory(File srcDir,
                 File destDir)
                          throws IOException

Copies a whole directory to a new location preserving the file dates.

This method copies the specified directory and all its child directories and files to the specified destination. The destination is the new location and name of the directory.

The destination directory is created if it does not exist. If the destination directory did exist, then this method merges the source with the destination, with the source taking precedence.

Parameters:

srcDir - an existing directory to copy, must not be null

destDir - the new directory, must not be null

Throws:

NullPointerException - if source or destination is null

IOException - if source or destination is invalid

IOException - if an IO error occurs during copying

Since:

Commons IO 1.1

copyDirectory

public static void copyDirectory(File srcDir,
                 File destDir,
                 boolean preserveFileDate)
                          throws IOException

Copies a whole directory to a new location.

This method copies the contents of the specified source directory to within the specified destination directory.

The destination directory is created if it does not exist. If the destination directory did exist, then this method merges the source with the destination, with the source taking precedence.

Parameters:

srcDir - an existing directory to copy, must not be null

destDir - the new directory, must not be null

preserveFileDate - true if the file date of the copy should be the same as the original

Throws:

NullPointerException - if source or destination is null

IOException - if source or destination is invalid

IOException - if an IO error occurs during copying

Since:

Commons IO 1.1

copyURLToFile

public static void copyURLToFile(URL source,
                 File destination)
                          throws IOException

Copies bytes from the URL source to a file destination. The directories up to destination will be created if they don't already exist. destination will be overwritten if it already exists.

Parameters:

source - A URL to copy bytes from.

destination - A non-directory File to write bytes to (possibly overwriting).

Throws:

IOException - if

• source URL cannot be opened
• destination cannot be written to
• an IO error occurs during copying

deleteDirectory

public static void deleteDirectory(File directory)
                            throws IOException

Recursively delete a directory.

Parameters:

directory - directory to delete

Throws:

IOException - in case deletion is unsuccessful

cleanDirectory

public static void cleanDirectory(File directory)
                           throws IOException

Clean a directory without deleting it.

Parameters:

directory - directory to clean

Throws:

IOException - in case cleaning is unsuccessful

waitFor

public static boolean waitFor(File file,
              int seconds)

Waits for NFS to propagate a file creation, imposing a timeout.

This method repeatedly tests File.exists() until it returns true up to the maximum time specified in seconds.

Parameters:

file - the file to check, not null

seconds - the maximum time in seconds to wait

Returns:

true if file exists

Throws:

NullPointerException - if the file is null

readFileToString

public static String readFileToString(File file,
                      String encoding)
                               throws IOException

Reads the contents of a file into a String. The file is always closed.

There is no readFileToString method without encoding parameter because the default encoding can differ between platforms and will have inconsistent results.

Parameters:

file - the file to read

encoding - the encoding to use, null means platform default

Returns:

the file contents or null if read failed

Throws:

IOException - in case of an I/O error

UnsupportedEncodingException - if the encoding is not supported by the VM

readLines

public static List readLines(File file,
             String encoding)
                      throws IOException

Reads the contents of a file line by line to a List of Strings. The file is always closed.

There is no readLines method without encoding parameter because the default encoding can differ between platforms and will have inconsistent results.

Parameters:

file - the file to read

encoding - the encoding to use, null means platform default

Returns:

the list of Strings representing each line in the file

Throws:

IOException - in case of an I/O error

UnsupportedEncodingException - if the encoding is not supported by the VM

Since:

Commons IO 1.1

writeStringToFile

public static void writeStringToFile(File file,
                     String data,
                     String encoding)
                              throws IOException

Writes a String to a file creating the file if it does not exist.

There is no writeStringToFile method without encoding parameter because the default encoding can differ between platforms and will have inconsistent results.

Parameters:

file - the file to write

data - the content to write to the file

encoding - the encoding to use, null means platform default

Throws:

IOException - in case of an I/O error

UnsupportedEncodingException - if the encoding is not supported by the VM

writeByteArrayToFile

public static void writeByteArrayToFile(File file,
                        byte[] data)
                                 throws IOException

Writes a byte array to a file creating the file if it does not exist.

Parameters:

file - the file to write to

data - the content to write to the file

Throws:

IOException - in case of an I/O error

Since:

Commons IO 1.1

writeLines

public static void writeLines(File file,
              String encoding,
              Collection<?> lines)
                       throws IOException

Writes the toString() value of each item in a collection to the specified File line by line. The specified character encoding and the default line ending will be used.

There is no writeLines method without encoding parameter because the default encoding can differ between platforms and will have inconsistent results.

Parameters:

file - the file to write to

encoding - the encoding to use, null means platform default

lines - the lines to write, null entries produce blank lines

Throws:

IOException - in case of an I/O error

UnsupportedEncodingException - if the encoding is not supported by the VM

Since:

Commons IO 1.1

writeLines

public static void writeLines(File file,
              String encoding,
              Collection<?> lines,
              String lineEnding)
                       throws IOException

Writes the toString() value of each item in a collection to the specified File line by line. The specified character encoding and the line ending will be used.

There is no writeLines method without encoding parameter because the default encoding can differ between platforms and will have inconsistent results.

Parameters:

file - the file to write to

encoding - the encoding to use, null means platform default

lines - the lines to write, null entries produce blank lines

lineEnding - the line separator to use, null is system default

Throws:

IOException - in case of an I/O error

UnsupportedEncodingException - if the encoding is not supported by the VM

Since:

Commons IO 1.1

forceDelete

public static void forceDelete(File file)
                        throws IOException

Delete a file. If file is a directory, delete it and all sub-directories.

The difference between File.delete() and this method are:

• A directory to be deleted does not have to be empty.
• You get exceptions when a file or directory cannot be deleted. (java.io.File methods returns a boolean)

Parameters:

file - file or directory to delete, not null

Throws:

NullPointerException - if the directory is null

IOException - in case deletion is unsuccessful

forceDeleteOnExit

public static void forceDeleteOnExit(File file)
                              throws IOException

Schedule a file to be deleted when JVM exits. If file is directory delete it and all sub-directories.

Parameters:

file - file or directory to delete, not null

Throws:

NullPointerException - if the file is null

IOException - in case deletion is unsuccessful

forceMkdir

public static void forceMkdir(File directory)
                       throws IOException

Make a directory, including any necessary but nonexistent parent directories. If there already exists a file with specified name or the directory cannot be created then an exception is thrown.

Parameters:

directory - directory to create, not null

Throws:

NullPointerException - if the directory is null

IOException - if the directory cannot be created

sizeOfDirectory

public static long sizeOfDirectory(File directory)

Recursively count size of a directory (sum of the length of all files).

Parameters:

directory - directory to inspect, not null

Returns:

size of directory in bytes, 0 if directory is security restricted

Throws:

NullPointerException - if the directory is null

isFileNewer

public static boolean isFileNewer(File file,
                  File reference)

Tests if the specified File is newer than the reference File.

Parameters:

file - the File of which the modification date must be compared, not null

reference - the File of which the modification date is used, not null

Returns:

true if the File exists and has been modified more recently than the reference File

Throws:

IllegalArgumentException - if the file is null

IllegalArgumentException - if the reference file is null or doesn't exist

isFileNewer

public static boolean isFileNewer(File file,
                  Date date)

Tests if the specified File is newer than the specified Date.

Parameters:

file - the File of which the modification date must be compared, not null

date - the date reference, not null

Returns:

true if the File exists and has been modified after the given Date.

Throws:

IllegalArgumentException - if the file is null

IllegalArgumentException - if the date is null

isFileNewer

public static boolean isFileNewer(File file,
                  long timeMillis)

Tests if the specified File is newer than the specified time reference.

Parameters:

file - the File of which the modification date must be compared, not null

timeMillis - the time reference measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970)

Returns:

true if the File exists and has been modified after the given time reference.

Throws:

IllegalArgumentException - if the file is null