org.apache.commons.io

Class FileUtils


public class FileUtils
extends java.lang.Object

General file manipulation utilities.

Facilities are provided in the following areas:

Origin of code: Excalibur, Alexandria, Commons-Utils

Version:
$Id: FileUtils.java 384037 2006-03-07 22:26:37Z scolebourne $
Authors:
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

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

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

Method Summary

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.
private static void
cleanDirectoryOnExit(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.
private static void
deleteDirectoryOnExit(File directory)
Recursively schedule directory for deletion on JVM exit.
private static void
doCopyDirectory(File srcDir, File destDir, boolean preserveFileDate)
Internal copy directory method.
private static void
doCopyFile(File srcFile, File destFile, boolean preserveFileDate)
Internal copy file method.
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.
private static void
innerListFiles(Collection files, File directory, IOFileFilter filter)
Finds files within a given directory (and optionally its subdirectories).
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 Iterator
iterateFiles(File directory, String[] extensions, boolean recursive)
Allows iteration over the files in a given directory (and optionally its subdirectories) which match an array of extensions.
static Iterator
iterateFiles(File directory, IOFileFilter fileFilter, IOFileFilter dirFilter)
Allows iteration over the files in given directory (and optionally its subdirectories).
static LineIterator
lineIterator(File file, String encoding)
Return an Iterator for the lines in a File.
static Collection
listFiles(File directory, String[] extensions, boolean recursive)
Finds files within a given directory (and optionally its subdirectories) which match an array of extensions.
static Collection
listFiles(File directory, IOFileFilter fileFilter, IOFileFilter dirFilter)
Finds files within a given directory (and optionally its subdirectories).
static byte[]
readFileToByteArray(File file)
Reads the contents of a file into a byte array.
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.
private static String[]
toSuffixes(String[] extensions)
Converts an array of file extensions to suffixes for use with IOFileFilters.
static URL[]
toURLs(File[] files)
Converts each of an array of File to a URL.
static void
touch(File file)
Implements the same behaviour as the "touch" utility on Unix.
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.

Field Details

EMPTY_FILE_ARRAY

public static final File[] EMPTY_FILE_ARRAY
An empty array of type File.

ONE_GB

public static final long ONE_GB
The number of bytes in a gigabyte.

ONE_KB

public static final long ONE_KB
The number of bytes in a kilobyte.
Field Value:
1024L

ONE_MB

public static final long ONE_MB
The number of bytes in a megabyte.

Constructor Details

FileUtils

public FileUtils()
Instances should NOT be constructed in standard programming.

Method Details

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)

cleanDirectory

public static void cleanDirectory(File directory)
            throws IOException
Clean a directory without deleting it.
Parameters:
directory - directory to clean

cleanDirectoryOnExit

private static void cleanDirectoryOnExit(File directory)
            throws IOException
Clean a directory without deleting it.
Parameters:
directory - directory to clean, not null

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

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

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
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
Since:
Commons IO 1.1

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
Since:
Commons IO 1.2

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

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

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

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).

deleteDirectory

public static void deleteDirectory(File directory)
            throws IOException
Recursively delete a directory.
Parameters:
directory - directory to delete

deleteDirectoryOnExit

private static void deleteDirectoryOnExit(File directory)
            throws IOException
Recursively schedule directory for deletion on JVM exit.
Parameters:
directory - directory to delete, not null

doCopyDirectory

private static void doCopyDirectory(File srcDir,
                                    File destDir,
                                    boolean preserveFileDate)
            throws IOException
Internal copy directory method.
Parameters:
srcDir - the validated source directory, not null
destDir - the validated destination directory, not null
preserveFileDate - whether to preserve the file date
Since:
Commons IO 1.1

doCopyFile

private static void doCopyFile(File srcFile,
                               File destFile,
                               boolean preserveFileDate)
            throws IOException
Internal copy file method.
Parameters:
srcFile - the validated source file, not null
destFile - the validated destination file, not null
preserveFileDate - whether to preserve the file date

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

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

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

innerListFiles

private static void innerListFiles(Collection files,
                                   File directory,
                                   IOFileFilter filter)
Finds files within a given directory (and optionally its subdirectories). All files found are filtered by an IOFileFilter.
Parameters:
files - the collection of files found.
directory - the directory to search in.
filter - the filter to apply to files and directories.

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.

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

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.

iterateFiles

public static Iterator iterateFiles(File directory,
                                    String[] extensions,
                                    boolean recursive)
Parameters:
directory - the directory to search in
extensions - an array of extensions, ex. {"java","xml"}. If this parameter is null, all files are returned.
recursive - if true all subdirectories are searched as well
Returns:
an iterator of java.io.File with the matching files
Since:
Commons IO 1.2

iterateFiles

public static Iterator iterateFiles(File directory,
                                    IOFileFilter fileFilter,
                                    IOFileFilter dirFilter)
Allows iteration over the files in given directory (and optionally its subdirectories).

All files found are filtered by an IOFileFilter. This method is based on listFiles(File,IOFileFilter,IOFileFilter).

Parameters:
directory - the directory to search in
fileFilter - filter to apply when finding files.
dirFilter - optional filter to apply when finding subdirectories. If this parameter is null, subdirectories will not be included in the search. Use TrueFileFilter.INSTANCE to match all directories.
Returns:
an iterator of java.io.File for the matching files
Since:
Commons IO 1.2

lineIterator

public static LineIterator lineIterator(File file,
                                        String encoding)
            throws IOException
Return an Iterator for the lines in a File.

This method opens an InputStream for the file. When you have finished with the iterator you should close the stream to free internal resources. This can be done by calling the LineIterator.close() or LineIterator.closeQuietly(LineIterator) method.

The recommended usage pattern is:

 LineIterator it = FileUtils.lineIterator(file, "UTF-8");
 try {
   while (it.hasNext()) {
     String line = it.nextLine();
     /// do something with line
   }
 } finally {
   LineIterator.closeQuietly(iterator);
 }
 

If an exception occurs during the creation of the iterator, the underlying stream is closed.

There is no lineIterator 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:
an Iterator of the lines in the file, never null
Since:
Commons IO 1.2

listFiles

public static Collection listFiles(File directory,
                                   String[] extensions,
                                   boolean recursive)
Finds files within a given directory (and optionally its subdirectories) which match an array of extensions.
Parameters:
directory - the directory to search in
extensions - an array of extensions, ex. {"java","xml"}. If this parameter is null, all files are returned.
recursive - if true all subdirectories are searched as well
Returns:
an collection of java.io.File with the matching files

listFiles

public static Collection listFiles(File directory,
                                   IOFileFilter fileFilter,
                                   IOFileFilter dirFilter)
Finds files within a given directory (and optionally its subdirectories). All files found are filtered by an IOFileFilter.

If your search should recurse into subdirectories you can pass in an IOFileFilter for directories. You don't need to bind a DirectoryFileFilter (via logical AND) to this filter. This method does that for you.

An example: If you want to search through all directories called "temp" you pass in FileFilterUtils.NameFileFilter("temp")

Another common usage of this method is find files in a directory tree but ignoring the directories generated CVS. You can simply pass in FileFilterUtils.makeCVSAware(null).

Parameters:
directory - the directory to search in
fileFilter - filter to apply when finding files.
dirFilter - optional filter to apply when finding subdirectories. If this parameter is null, subdirectories will not be included in the search. Use TrueFileFilter.INSTANCE to match all directories.
Returns:
an collection of java.io.File with the matching files

readFileToByteArray

public static byte[] readFileToByteArray(File file)
            throws IOException
Reads the contents of a file into a byte array. The file is always closed.
Parameters:
file - the file to read
Returns:
the file contents or null if read failed
Since:
Commons IO 1.1

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

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
Since:
Commons IO 1.1

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

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

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
Since:
Commons IO 1.1

toSuffixes

private static String[] toSuffixes(String[] extensions)
Converts an array of file extensions to suffixes for use with IOFileFilters.
Parameters:
extensions - an array of extensions. Format: {"java", "xml"}
Returns:
an array of suffixes. Format: {".java", ".xml"}

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

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

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

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