Java Doc for FileUtils.java in  » Library » apache-common-IO » org » apache » commons » io » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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
• calculating a checksum

Origin of code: Excalibur, Alexandria, Commons-Utils
author:
   Kevin A. Burton
author:
   Scott Sanders
author:
   Daniel Rall
author:
   Christoph.Reck
author:
   Peter Donald
author:
   Jeff Turner
author:
   Matthew Hawthorne
author:
   Jeremias Maerki
author:
   Stephen Colebourne
author:
   Ian Springer
author:
   Chris Eldredge
author:
   Jim Harrington
author:
   Niall Pemberton
author:
   Sandy McArthur
version:
   $Id: FileUtils.java 507684 2007-02-14 20:38:25Z bayard $

This method copies the contents of the specified source file to the specified destination file.

All files found are filtered by an IOFileFilter.

This method opens an InputStream for the file. When you have finished with the iterator you should close the stream to free internal resources.

 long csum = FileUtils.checksum(file, new CRC32()).getValue();
 

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
Parameters:
  file2 - the second file true if the content of the files are equal or they both don'texist, false otherwise
throws:
  IOException - in case of an I/O error

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
Parameters:
  destDir - the new directory, must not be null
throws:
  NullPointerException - if source or destination is null
throws:
  IOException - if source or destination is invalid
throws:
  IOException - if an IO error occurs during copying
since:
   Commons IO 1.1

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
Parameters:
  destDir - the new directory, must not be null
Parameters:
  preserveFileDate - true if the file date of the copyshould be the same as the original
throws:
  NullPointerException - if source or destination is null
throws:
  IOException - if source or destination is invalid
throws:
  IOException - if an IO error occurs during copying
since:
   Commons IO 1.1

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
Parameters:
  destDir - the directory to place the copy in, must not be null
throws:
  NullPointerException - if source or destination is null
throws:
  IOException - if source or destination is invalid
throws:
  IOException - if an IO error occurs during copying
since:
   Commons IO 1.2

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
Parameters:
  destFile - the new file, must not be null
throws:
  NullPointerException - if source or destination is null
throws:
  IOException - if source or destination is invalid
throws:
  IOException - if an IO error occurs during copying
See Also:   FileUtils.copyFileToDirectory(File,File)

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
Parameters:
  destFile - the new file, must not be null
Parameters:
  preserveFileDate - true if the file date of the copyshould be the same as the original
throws:
  NullPointerException - if source or destination is null
throws:
  IOException - if source or destination is invalid
throws:
  IOException - if an IO error occurs during copying
See Also:   FileUtils.copyFileToDirectory(File,File,boolean)

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
Parameters:
  destDir - the directory to place the copy in, must not be null
throws:
  NullPointerException - if source or destination is null
throws:
  IOException - if source or destination is invalid
throws:
  IOException - if an IO error occurs during copying
See Also:   FileUtils.copyFile(File,File,boolean)

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
Parameters:
  destDir - the directory to place the copy in, must not be null
Parameters:
  preserveFileDate - true if the file date of the copyshould be the same as the original
throws:
  NullPointerException - if source or destination is null
throws:
  IOException - if source or destination is invalid
throws:
  IOException - if an IO error occurs during copying
See Also:   FileUtils.copyFile(File,File,boolean)
since:
   Commons IO 1.3

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)

All files found are filtered by an IOFileFilter. This method is based on FileUtils.listFiles(File,IOFileFilter,IOFileFilter) .
Parameters:
  directory - the directory to search in
Parameters:
  fileFilter - filter to apply when finding files.
Parameters:
  dirFilter - optional filter to apply when finding subdirectories.If this parameter is null, subdirectories will not be included in thesearch. Use TrueFileFilter.INSTANCE to match all directories. an iterator of java.io.File for the matching files
See Also:   org.apache.commons.io.filefilter.FileFilterUtils
See Also:   org.apache.commons.io.filefilter.NameFileFilter
since:
   Commons IO 1.2

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.
Parameters:
  file - the file to open for input, must not be null
Parameters:
  encoding - the encoding to use, null means platform default 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

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
Parameters:
  fileFilter - filter to apply when finding files.
Parameters:
  dirFilter - optional filter to apply when finding subdirectories.If this parameter is null, subdirectories will not be included in thesearch. Use TrueFileFilter.INSTANCE to match all directories. an collection of java.io.File with the matching files
See Also:   org.apache.commons.io.filefilter.FileFilterUtils
See Also:   org.apache.commons.io.filefilter.NameFileFilter

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 a new FileInputStream for the specified file
throws:
  FileNotFoundException - if the file does not exist
throws:
  IOException - if the file object is a directory
throws:
  IOException - if the file cannot be read
since:
   Commons IO 1.3

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 a new FileOutputStream for the specified file
throws:
  IOException - if the file object is a directory
throws:
  IOException - if the file cannot be written to
throws:
  IOException - if a parent directory needs creating but that fails
since:
   Commons IO 1.3

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 the equivalent File object, or nullif the URL's protocol is not file
throws:
  IllegalArgumentException - if the file is incorrectly encoded

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 a non-null array of Files matching the input, with a null itemif there was a null at that index in the input array
throws:
  IllegalArgumentException - if any file is not a URL file
throws:
  IllegalArgumentException - if any file is incorrectly encoded
since:
   Commons IO 1.1

Returns an array of the same size as the input.
Parameters:
  files - the files to convert an array of URLs matching the input
throws:
  IOException - if a file cannot be converted

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

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
Parameters:
  seconds - the maximum time in seconds to wait true if file exists
throws:
  NullPointerException - if the file is null

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
Parameters:
  data - the content to write to the file
throws:
  IOException - in case of an I/O error
since:
   Commons IO 1.1

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
Parameters:
  encoding - the encoding to use, null means platform default
Parameters:
  lines - the lines to write, null entries produce blank lines
throws:
  IOException - in case of an I/O error
throws:
  java.io.UnsupportedEncodingException - if the encoding is not supported by the VM
since:
   Commons IO 1.1

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
Parameters:
  encoding - the encoding to use, null means platform default
Parameters:
  lines - the lines to write, null entries produce blank lines
Parameters:
  lineEnding - the line separator to use, null is system default
throws:
  IOException - in case of an I/O error
throws:
  java.io.UnsupportedEncodingException - if the encoding is not supported by the VM
since:
   Commons IO 1.1