org.apache.commons.io

Class FileUtils

public class FileUtils extends Object

General file manipulation utilities.

Facilities are provided in the following areas:

Origin of code: Excalibur, Alexandria, Commons-Utils

Version: $Id: FileUtils.java 610810 2008-01-10 15:04:49Z niallp $

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
static File[]EMPTY_FILE_ARRAY
An empty array of type File.
static longONE_GB
The number of bytes in a gigabyte.
static longONE_KB
The number of bytes in a kilobyte.
static longONE_MB
The number of bytes in a megabyte.
Constructor Summary
FileUtils()
Instances should NOT be constructed in standard programming.
Method Summary
static StringbyteCountToDisplaySize(long size)
Returns a human-readable version of the file size, where the input represents a specific number of bytes.
static Checksumchecksum(File file, Checksum checksum)
Computes the checksum of a file using the specified checksum object.
static longchecksumCRC32(File file)
Computes the checksum of a file using the CRC32 checksum routine.
static voidcleanDirectory(File directory)
Cleans a directory without deleting it.
static voidcleanDirectoryOnExit(File directory)
Cleans a directory without deleting it.
static booleancontentEquals(File file1, File file2)
Compares 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 voidcopyDirectory(File srcDir, File destDir)
Copies a whole directory to a new location preserving the file dates.
static voidcopyDirectory(File srcDir, File destDir, boolean preserveFileDate)
Copies a whole directory to a new location.
static voidcopyDirectory(File srcDir, File destDir, FileFilter filter)
Copies a filtered directory to a new location preserving the file dates.
static voidcopyDirectory(File srcDir, File destDir, FileFilter filter, boolean preserveFileDate)
Copies a filtered directory to a new location.
static voidcopyDirectoryToDirectory(File srcDir, File destDir)
Copies a directory to within another directory preserving the file dates.
static voidcopyFile(File srcFile, File destFile)
Copies a file to a new location preserving the file date.
static voidcopyFile(File srcFile, File destFile, boolean preserveFileDate)
Copies a file to a new location.
static voidcopyFileToDirectory(File srcFile, File destDir)
Copies a file to a directory preserving the file date.
static voidcopyFileToDirectory(File srcFile, File destDir, boolean preserveFileDate)
Copies a file to a directory optionally preserving the file date.
static voidcopyURLToFile(URL source, File destination)
Copies bytes from the URL source to a file destination.
static voiddeleteDirectory(File directory)
Deletes a directory recursively.
static voiddeleteDirectoryOnExit(File directory)
Schedules a directory recursively for deletion on JVM exit.
static booleandeleteQuietly(File file)
Deletes a file, never throwing an exception.
static voiddoCopyDirectory(File srcDir, File destDir, FileFilter filter, boolean preserveFileDate, List exclusionList)
Internal copy directory method.
static voiddoCopyFile(File srcFile, File destFile, boolean preserveFileDate)
Internal copy file method.
static voidforceDelete(File file)
Deletes a file.
static voidforceDeleteOnExit(File file)
Schedules a file to be deleted when JVM exits.
static voidforceMkdir(File directory)
Makes a directory, including any necessary but nonexistent parent directories.
static voidinnerListFiles(Collection files, File directory, IOFileFilter filter)
Finds files within a given directory (and optionally its subdirectories).
static booleanisFileNewer(File file, File reference)
Tests if the specified File is newer than the reference File.
static booleanisFileNewer(File file, Date date)
Tests if the specified File is newer than the specified Date.
static booleanisFileNewer(File file, long timeMillis)
Tests if the specified File is newer than the specified time reference.
static booleanisFileOlder(File file, File reference)
Tests if the specified File is older than the reference File.
static booleanisFileOlder(File file, Date date)
Tests if the specified File is older than the specified Date.
static booleanisFileOlder(File file, long timeMillis)
Tests if the specified File is older than the specified time reference.
static IteratoriterateFiles(File directory, IOFileFilter fileFilter, IOFileFilter dirFilter)
Allows iteration over the files in given directory (and optionally its subdirectories).
static IteratoriterateFiles(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 LineIteratorlineIterator(File file, String encoding)
Returns an Iterator for the lines in a File.
static LineIteratorlineIterator(File file)
Returns an Iterator for the lines in a File using the default encoding for the VM.
static CollectionlistFiles(File directory, IOFileFilter fileFilter, IOFileFilter dirFilter)
Finds files within a given directory (and optionally its subdirectories).
static CollectionlistFiles(File directory, String[] extensions, boolean recursive)
Finds files within a given directory (and optionally its subdirectories) which match an array of extensions.
static voidmoveDirectory(File srcDir, File destDir)
Moves a directory.
static voidmoveDirectoryToDirectory(File src, File destDir, boolean createDestDir)
Moves a directory to another directory.
static voidmoveFile(File srcFile, File destFile)
Moves a file.
static voidmoveFileToDirectory(File srcFile, File destDir, boolean createDestDir)
Moves a file to a directory.
static voidmoveToDirectory(File src, File destDir, boolean createDestDir)
Moves a file or directory to the destination directory.
static FileInputStreamopenInputStream(File file)
Opens a FileInputStream for the specified file, providing better error messages than simply calling new FileInputStream(file).
static FileOutputStreamopenOutputStream(File file)
Opens a FileOutputStream for the specified file, checking and creating the parent directory if it does not exist.
static byte[]readFileToByteArray(File file)
Reads the contents of a file into a byte array.
static StringreadFileToString(File file, String encoding)
Reads the contents of a file into a String.
static StringreadFileToString(File file)
Reads the contents of a file into a String using the default encoding for the VM.
static ListreadLines(File file, String encoding)
Reads the contents of a file line by line to a List of Strings.
static ListreadLines(File file)
Reads the contents of a file line by line to a List of Strings using the default encoding for the VM.
static longsizeOfDirectory(File directory)
Counts the size of a directory recursively (sum of the length of all files).
static FiletoFile(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 String[]toSuffixes(String[] extensions)
Converts an array of file extensions to suffixes for use with IOFileFilters.
static voidtouch(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 booleanwaitFor(File file, int seconds)
Waits for NFS to propagate a file creation, imposing a timeout.
static voidwriteByteArrayToFile(File file, byte[] data)
Writes a byte array to a file creating the file if it does not exist.
static voidwriteLines(File file, String encoding, Collection lines)
Writes the toString() value of each item in a collection to the specified File line by line.
static voidwriteLines(File file, Collection lines)
Writes the toString() value of each item in a collection to the specified File line by line.
static voidwriteLines(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 voidwriteLines(File file, Collection lines, String lineEnding)
Writes the toString() value of each item in a collection to the specified File line by line.
static voidwriteStringToFile(File file, String data, String encoding)
Writes a String to a file creating the file if it does not exist.
static voidwriteStringToFile(File file, String data)
Writes a String to a file creating the file if it does not exist using the default encoding for the VM.

Field Detail

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.

ONE_MB

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

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)

checksum

public static Checksum checksum(File file, Checksum checksum)
Computes the checksum of a file using the specified checksum object. Multiple files may be checked using one Checksum instance if desired simply by reusing the same checksum object. For example:
   long csum = FileUtils.checksum(file, new CRC32()).getValue();
 

Parameters: file the file to checksum, must not be null checksum the checksum object to be used, must not be null

Returns: the checksum specified, updated with the content of the file

Throws: NullPointerException if the file or checksum is null IllegalArgumentException if the file is a directory IOException if an IO error occurs reading the file

Since: Commons IO 1.3

checksumCRC32

public static long checksumCRC32(File file)
Computes the checksum of a file using the CRC32 checksum routine. The value of the checksum is returned.

Parameters: file the file to checksum, must not be null

Returns: the checksum value

Throws: NullPointerException if the file or checksum is null IllegalArgumentException if the file is a directory IOException if an IO error occurs reading the file

Since: Commons IO 1.3

cleanDirectory

public static void cleanDirectory(File directory)
Cleans a directory without deleting it.

Parameters: directory directory to clean

Throws: IOException in case cleaning is unsuccessful

cleanDirectoryOnExit

private static void cleanDirectoryOnExit(File directory)
Cleans a directory without deleting it.

Parameters: directory directory to clean, must not be null

Throws: NullPointerException if the directory is null IOException in case cleaning is unsuccessful

contentEquals

public static boolean contentEquals(File file1, File file2)
Compares 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

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

copyDirectory

public static void copyDirectory(File srcDir, File destDir, FileFilter filter)
Copies a filtered directory to a new location preserving the file dates.

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.

Example: Copy directories only

  // only copy the directory structure
  FileUtils.copyDirectory(srcDir, destDir, DirectoryFileFilter.DIRECTORY);
  

Example: Copy directories and txt files

  // Create a filter for ".txt" files
  IOFileFilter txtSuffixFilter = FileFilterUtils.suffixFileFilter(".txt");
  IOFileFilter txtFiles = FileFilterUtils.andFileFilter(FileFileFilter.FILE, txtSuffixFilter);

  // Create a filter for either directories or ".txt" files
  FileFilter filter = FileFilterUtils.orFileFilter(DirectoryFileFilter.DIRECTORY, txtFiles);

  // Copy using the filter
  FileUtils.copyDirectory(srcDir, destDir, filter);
  

Parameters: srcDir an existing directory to copy, must not be null destDir the new directory, must not be null filter the filter to apply, null means copy all directories and files 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.4

copyDirectory

public static void copyDirectory(File srcDir, File destDir, FileFilter filter, boolean preserveFileDate)
Copies a filtered 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.

Example: Copy directories only

  // only copy the directory structure
  FileUtils.copyDirectory(srcDir, destDir, DirectoryFileFilter.DIRECTORY, false);
  

Example: Copy directories and txt files

  // Create a filter for ".txt" files
  IOFileFilter txtSuffixFilter = FileFilterUtils.suffixFileFilter(".txt");
  IOFileFilter txtFiles = FileFilterUtils.andFileFilter(FileFileFilter.FILE, txtSuffixFilter);

  // Create a filter for either directories or ".txt" files
  FileFilter filter = FileFilterUtils.orFileFilter(DirectoryFileFilter.DIRECTORY, txtFiles);

  // Copy using the filter
  FileUtils.copyDirectory(srcDir, destDir, filter, false);
  

Parameters: srcDir an existing directory to copy, must not be null destDir the new directory, must not be null filter the filter to apply, null means copy all directories and files 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.4

copyDirectoryToDirectory

public static void copyDirectoryToDirectory(File srcDir, File destDir)
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

copyFile

public static void copyFile(File srcFile, File destFile)
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: FileUtils

copyFile

public static void copyFile(File srcFile, File destFile, boolean preserveFileDate)
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: FileUtils

copyFileToDirectory

public static void copyFileToDirectory(File srcFile, File destDir)
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: FileUtils

copyFileToDirectory

public static void copyFileToDirectory(File srcFile, File destDir, boolean preserveFileDate)
Copies a file to a directory optionally 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 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.3

See Also: FileUtils

copyURLToFile

public static void copyURLToFile(URL source, File destination)
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 the URL to copy bytes from, must not be null destination the non-directory File to write bytes to (possibly overwriting), must not be null

Throws: IOException if source URL cannot be opened IOException if destination is a directory IOException if destination cannot be written IOException if destination needs creating but can't be IOException if an IO error occurs during copying

deleteDirectory

public static void deleteDirectory(File directory)
Deletes a directory recursively.

Parameters: directory directory to delete

Throws: IOException in case deletion is unsuccessful

deleteDirectoryOnExit

private static void deleteDirectoryOnExit(File directory)
Schedules a directory recursively for deletion on JVM exit.

Parameters: directory directory to delete, must not be null

Throws: NullPointerException if the directory is null IOException in case deletion is unsuccessful

deleteQuietly

public static boolean deleteQuietly(File file)
Deletes a file, never throwing an exception. If file is a directory, delete it and all sub-directories.

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

Parameters: file file or directory to delete, can be null

Returns: true if the file or directory was deleted, otherwise false

Since: Commons IO 1.4

doCopyDirectory

private static void doCopyDirectory(File srcDir, File destDir, FileFilter filter, boolean preserveFileDate, List exclusionList)
Internal copy directory method.

Parameters: srcDir the validated source directory, must not be null destDir the validated destination directory, must not be null filter the filter to apply, null means copy all directories and files preserveFileDate whether to preserve the file date exclusionList List of files and directories to exclude from the copy, may be null

Throws: IOException if an error occurs

Since: Commons IO 1.1

doCopyFile

private static void doCopyFile(File srcFile, File destFile, boolean preserveFileDate)
Internal copy file method.

Parameters: srcFile the validated source file, must not be null destFile the validated destination file, must not be null preserveFileDate whether to preserve the file date

Throws: IOException if an error occurs

forceDelete

public static void forceDelete(File file)
Deletes a file. If file is a directory, delete it and all sub-directories.

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

Parameters: file file or directory to delete, must not be null

Throws: NullPointerException if the directory is null FileNotFoundException if the file was not found IOException in case deletion is unsuccessful

forceDeleteOnExit

public static void forceDeleteOnExit(File file)
Schedules 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, must not be null

Throws: NullPointerException if the file is null IOException in case deletion is unsuccessful

forceMkdir

public static void forceMkdir(File directory)
Makes 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, must not be null

Throws: NullPointerException if the directory is null IOException if the directory cannot be created

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, 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, must not be null reference the File of which the modification date is used, must not be 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, must not be null date the date reference, must not be 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, must not be 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

isFileOlder

public static boolean isFileOlder(File file, File reference)
Tests if the specified File is older than the reference File.

Parameters: file the File of which the modification date must be compared, must not be null reference the File of which the modification date is used, must not be null

Returns: true if the File exists and has been modified before the reference File

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

isFileOlder

public static boolean isFileOlder(File file, Date date)
Tests if the specified File is older than the specified Date.

Parameters: file the File of which the modification date must be compared, must not be null date the date reference, must not be null

Returns: true if the File exists and has been modified before the given Date.

Throws: IllegalArgumentException if the file is null IllegalArgumentException if the date is null

isFileOlder

public static boolean isFileOlder(File file, long timeMillis)
Tests if the specified File is older than the specified time reference.

Parameters: file the File of which the modification date must be compared, must not be 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 before the given time reference.

Throws: IllegalArgumentException if the file is null

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

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

See Also: FileFilterUtils NameFileFilter

iterateFiles

public 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. This method is based on (File, String[], boolean).

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

lineIterator

public static LineIterator lineIterator(File file, String encoding)
Returns 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 close or closeQuietly 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.

Parameters: file the file to open for input, must not be null encoding the encoding to use, null means platform default

Returns: an Iterator of the lines in the file, never null

Throws: IOException in case of an I/O error (file closed)

Since: Commons IO 1.2

lineIterator

public static LineIterator lineIterator(File file)
Returns an Iterator for the lines in a File using the default encoding for the VM.

Parameters: file the file to open for input, must not be null

Returns: an Iterator of the lines in the file, never null

Throws: IOException in case of an I/O error (file closed)

Since: Commons IO 1.3

See Also: FileUtils

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

See Also: FileFilterUtils NameFileFilter

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

moveDirectory

public static void moveDirectory(File srcDir, File destDir)
Moves a directory.

When the destination directory is on another file system, do a "copy and delete".

Parameters: srcDir the directory to be moved destDir the destination directory

Throws: NullPointerException if source or destination is null IOException if source or destination is invalid IOException if an IO error occurs moving the file

Since: Commons IO 1.4

moveDirectoryToDirectory

public static void moveDirectoryToDirectory(File src, File destDir, boolean createDestDir)
Moves a directory to another directory.

Parameters: src the file to be moved destDir the destination file createDestDir If true create the destination directory, otherwise if false throw an IOException

Throws: NullPointerException if source or destination is null IOException if source or destination is invalid IOException if an IO error occurs moving the file

Since: Commons IO 1.4

moveFile

public static void moveFile(File srcFile, File destFile)
Moves a file.

When the destination file is on another file system, do a "copy and delete".

Parameters: srcFile the file to be moved destFile the destination file

Throws: NullPointerException if source or destination is null IOException if source or destination is invalid IOException if an IO error occurs moving the file

Since: Commons IO 1.4

moveFileToDirectory

public static void moveFileToDirectory(File srcFile, File destDir, boolean createDestDir)
Moves a file to a directory.

Parameters: srcFile the file to be moved destDir the destination file createDestDir If true create the destination directory, otherwise if false throw an IOException

Throws: NullPointerException if source or destination is null IOException if source or destination is invalid IOException if an IO error occurs moving the file

Since: Commons IO 1.4

moveToDirectory

public static void moveToDirectory(File src, File destDir, boolean createDestDir)
Moves a file or directory to the destination directory.

When the destination is on another file system, do a "copy and delete".

Parameters: src the file or directory to be moved destDir the destination directory createDestDir If true create the destination directory, otherwise if false throw an IOException

Throws: NullPointerException if source or destination is null IOException if source or destination is invalid IOException if an IO error occurs moving the file

Since: Commons IO 1.4

openInputStream

public static FileInputStream openInputStream(File file)
Opens a FileInputStream for the specified file, providing better error messages than simply calling new FileInputStream(file).

At the end of the method either the stream will be successfully opened, or an exception will have been thrown.

An exception is thrown if the file does not exist. An exception is thrown if the file object exists but is a directory. An exception is thrown if the file exists but cannot be read.

Parameters: file the file to open for input, must not be null

Returns: a new FileInputStream for the specified file

Throws: FileNotFoundException if the file does not exist IOException if the file object is a directory IOException if the file cannot be read

Since: Commons IO 1.3

openOutputStream

public static FileOutputStream openOutputStream(File file)
Opens a FileOutputStream for the specified file, checking and creating the parent directory if it does not exist.

At the end of the method either the stream will be successfully opened, or an exception will have been thrown.

The parent directory will be created if it does not exist. The file will be created if it does not exist. An exception is thrown if the file object exists but is a directory. An exception is thrown if the file exists but cannot be written to. An exception is thrown if the parent directory cannot be created.

Parameters: file the file to open for output, must not be null

Returns: a new FileOutputStream for the specified file

Throws: IOException if the file object is a directory IOException if the file cannot be written to IOException if a parent directory needs creating but that fails

Since: Commons IO 1.3

readFileToByteArray

public static byte[] readFileToByteArray(File file)
Reads the contents of a file into a byte array. The file is always closed.

Parameters: file the file to read, must not be null

Returns: the file contents, never null

Throws: IOException in case of an I/O error

Since: Commons IO 1.1

readFileToString

public static String readFileToString(File file, String encoding)
Reads the contents of a file into a String. The file is always closed.

Parameters: file the file to read, must not be null encoding the encoding to use, null means platform default

Returns: the file contents, never null

Throws: IOException in case of an I/O error java.io.UnsupportedEncodingException if the encoding is not supported by the VM

readFileToString

public static String readFileToString(File file)
Reads the contents of a file into a String using the default encoding for the VM. The file is always closed.

Parameters: file the file to read, must not be null

Returns: the file contents, never null

Throws: IOException in case of an I/O error

Since: Commons IO 1.3.1

readLines

public static List readLines(File file, String encoding)
Reads the contents of a file line by line to a List of Strings. The file is always closed.

Parameters: file the file to read, must not be null encoding the encoding to use, null means platform default

Returns: the list of Strings representing each line in the file, never null

Throws: IOException in case of an I/O error java.io.UnsupportedEncodingException if the encoding is not supported by the VM

Since: Commons IO 1.1

readLines

public static List readLines(File file)
Reads the contents of a file line by line to a List of Strings using the default encoding for the VM. The file is always closed.

Parameters: file the file to read, must not be null

Returns: the list of Strings representing each line in the file, never null

Throws: IOException in case of an I/O error

Since: Commons IO 1.3

sizeOfDirectory

public static long sizeOfDirectory(File directory)
Counts the size of a directory recursively (sum of the length of all files).

Parameters: directory directory to inspect, must not be null

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

Throws: NullPointerException if the directory is null

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

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

touch

public static void touch(File file)
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.

NOTE: As from v1.3, this method throws an IOException if the last modified date of the file cannot be set. Also, as from v1.3 this method creates parent directories if they do not exist.

Parameters: file the File to touch

Throws: IOException If an I/O problem occurs

toURLs

public static URL[] toURLs(File[] files)
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

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, must not be null seconds the maximum time in seconds to wait

Returns: true if file exists

Throws: NullPointerException if the file is null

writeByteArrayToFile

public static void writeByteArrayToFile(File file, byte[] data)
Writes a byte array to a file creating the file if it does not exist.

NOTE: As from v1.3, the parent directories of the file will be created if they do 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)
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.

NOTE: As from v1.3, the parent directories of the file will be created if they do not exist.

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 java.io.UnsupportedEncodingException if the encoding is not supported by the VM

Since: Commons IO 1.1

writeLines

public static void writeLines(File file, Collection lines)
Writes the toString() value of each item in a collection to the specified File line by line. The default VM encoding and the default line ending will be used.

Parameters: file the file to write to lines the lines to write, null entries produce blank lines

Throws: IOException in case of an I/O error

Since: Commons IO 1.3

writeLines

public 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. The specified character encoding and the line ending will be used.

NOTE: As from v1.3, the parent directories of the file will be created if they do not exist.

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 java.io.UnsupportedEncodingException if the encoding is not supported by the VM

Since: Commons IO 1.1

writeLines

public static void writeLines(File file, Collection lines, String lineEnding)
Writes the toString() value of each item in a collection to the specified File line by line. The default VM encoding and the specified line ending will be used.

Parameters: file the file to write to 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

Since: Commons IO 1.3

writeStringToFile

public static void writeStringToFile(File file, String data, String encoding)
Writes a String to a file creating the file if it does not exist. NOTE: As from v1.3, the parent directories of the file will be created if they do not exist.

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 java.io.UnsupportedEncodingException if the encoding is not supported by the VM

writeStringToFile

public static void writeStringToFile(File file, String data)
Writes a String to a file creating the file if it does not exist using the default encoding for the VM.

Parameters: file the file to write data the content to write to the file

Throws: IOException in case of an I/O error

Copyright (c) 2002-2011 Apache Software Foundation