org.apache.tools.ant.util

Class FileUtils


public class FileUtils
extends java.lang.Object

This class also encapsulates methods which allow Files to be refered to using abstract path names which are translated to native system file paths at runtime as well as copying files or setting there last modification time.

Version:
$Revision: 1.56.2.7 $

Field Summary

static long
FAT_FILE_TIMESTAMP_GRANULARITY
the granularity of timestamps under FAT

Constructor Summary

FileUtils()
Empty constructor.

Method Summary

boolean
contentEquals(File f1, File f2)
Compares the contents of two files.
void
copyFile(File sourceFile, File destFile)
Convienence method to copy a file from a source to a destination.
void
copyFile(File sourceFile, File destFile, FilterSetCollection filters)
Convienence method to copy a file from a source to a destination specifying if token filtering must be used.
void
copyFile(File sourceFile, File destFile, FilterSetCollection filters, Vector filterChains, boolean overwrite, boolean preserveLastModified, String inputEncoding, String outputEncoding, Project project)
Convienence method to copy a file from a source to a destination specifying if token filtering must be used, if filter chains must be used, if source files may overwrite newer destination files and the last modified time of destFile file should be made equal to the last modified time of sourceFile.
void
copyFile(File sourceFile, File destFile, FilterSetCollection filters, Vector filterChains, boolean overwrite, boolean preserveLastModified, String encoding, Project project)
Convienence method to copy a file from a source to a destination specifying if token filtering must be used, if filter chains must be used, if source files may overwrite newer destination files and the last modified time of destFile file should be made equal to the last modified time of sourceFile.
void
copyFile(File sourceFile, File destFile, FilterSetCollection filters, boolean overwrite)
Convienence method to copy a file from a source to a destination specifying if token filtering must be used and if source files may overwrite newer destination files.
void
copyFile(File sourceFile, File destFile, FilterSetCollection filters, boolean overwrite, boolean preserveLastModified)
Convienence method to copy a file from a source to a destination specifying if token filtering must be used, if source files may overwrite newer destination files and the last modified time of destFile file should be made equal to the last modified time of sourceFile.
void
copyFile(File sourceFile, File destFile, FilterSetCollection filters, boolean overwrite, boolean preserveLastModified, String encoding)
Convienence method to copy a file from a source to a destination specifying if token filtering must be used, if source files may overwrite newer destination files, the last modified time of destFile file should be made equal to the last modified time of sourceFile and which character encoding to assume.
void
copyFile(String sourceFile, String destFile)
Convienence method to copy a file from a source to a destination.
void
copyFile(String sourceFile, String destFile, FilterSetCollection filters)
Convienence method to copy a file from a source to a destination specifying if token filtering must be used.
void
copyFile(String sourceFile, String destFile, FilterSetCollection filters, Vector filterChains, boolean overwrite, boolean preserveLastModified, String inputEncoding, String outputEncoding, Project project)
Convienence method to copy a file from a source to a destination specifying if token filtering must be used, if filter chains must be used, if source files may overwrite newer destination files and the last modified time of destFile file should be made equal to the last modified time of sourceFile.
void
copyFile(String sourceFile, String destFile, FilterSetCollection filters, Vector filterChains, boolean overwrite, boolean preserveLastModified, String encoding, Project project)
Convienence method to copy a file from a source to a destination specifying if token filtering must be used, if filter chains must be used, if source files may overwrite newer destination files and the last modified time of destFile file should be made equal to the last modified time of sourceFile.
void
copyFile(String sourceFile, String destFile, FilterSetCollection filters, boolean overwrite)
Convienence method to copy a file from a source to a destination specifying if token filtering must be used and if source files may overwrite newer destination files.
void
copyFile(String sourceFile, String destFile, FilterSetCollection filters, boolean overwrite, boolean preserveLastModified)
Convienence method to copy a file from a source to a destination specifying if token filtering must be used, if source files may overwrite newer destination files and the last modified time of destFile file should be made equal to the last modified time of sourceFile.
void
copyFile(String sourceFile, String destFile, FilterSetCollection filters, boolean overwrite, boolean preserveLastModified, String encoding)
Convienence method to copy a file from a source to a destination specifying if token filtering must be used, if source files may overwrite newer destination files and the last modified time of destFile file should be made equal to the last modified time of sourceFile.
boolean
createNewFile(File f)
Emulation of File.createNewFile for JDK 1.1.
File
createTempFile(String prefix, String suffix, File parentDir)
Create a temporary file in a given directory.
boolean
fileNameEquals(File f1, File f2)
Compares two filenames.
String
fromURI(String uri)
Constructs a file path from a file: URI.
long
getFileTimestampGranularity()
URL
getFileURL(File file)
Get the URL for a file taking into account # characters
File
getParentFile(File f)
Emulation of File.getParentFile for JDK 1.1
protected Method
getSetLastModified()
see whether we have a setLastModified method in File and return it.
boolean
isSymbolicLink(File parent, String name)
Checks whether a given file is a symbolic link.
static FileUtils
newFileUtils()
Factory method.
File
normalize(String path)
"normalize" the given absolute path.
static String
readFully(Reader rdr)
Read from reader till EOF
static String
readFully(Reader rdr, int bufferSize)
Read from reader till EOF
String
removeLeadingPath(File leading, File path)
Removes a leading path from a second path.
void
rename(File from, File to)
Renames a file, even if that involves crossing file system boundaries.
File
resolveFile(File file, String filename)
Interpret the filename as a file relative to the given file - unless the filename already represents an absolute filename.
void
setFileLastModified(File file, long time)
Calls File.setLastModified(long time) in a Java 1.1 compatible way.
String
toURI(String path)
Constructs a file: URI that represents the external form of the given pathname.
String
toVMSPath(File f)
Returns a VMS String representation of a File object.

Field Details

FAT_FILE_TIMESTAMP_GRANULARITY

public static final long FAT_FILE_TIMESTAMP_GRANULARITY
the granularity of timestamps under FAT

Field Value:
2000L

Constructor Details

FileUtils

protected FileUtils()
Empty constructor.

Method Details

contentEquals

public boolean contentEquals(File f1,
                             File f2)
            throws IOException
Compares the contents of two files.

simple but sub-optimal comparision algorithm. written for working rather than fast. Better would be a block read into buffers followed by long comparisions apart from the final 1-7 bytes.

Parameters:
f1 - the file whose content is to be compared.
f2 - the other file whose content is to be compared.

Returns:
true if the content of the files is the same.

Since:
1.9


copyFile

public void copyFile(File sourceFile,
                     File destFile)
            throws IOException
Convienence method to copy a file from a source to a destination. No filtering is performed.

Parameters:
sourceFile - the file to copy from. Must not be null.
destFile - the file to copy to. Must not be null.


copyFile

public void copyFile(File sourceFile,
                     File destFile,
                     FilterSetCollection filters)
            throws IOException
Convienence method to copy a file from a source to a destination specifying if token filtering must be used.

Parameters:
sourceFile - the file to copy from. Must not be null.
destFile - the file to copy to. Must not be null.
filters - the collection of filters to apply to this copy


copyFile

public void copyFile(File sourceFile,
                     File destFile,
                     FilterSetCollection filters,
                     Vector filterChains,
                     boolean overwrite,
                     boolean preserveLastModified,
                     String inputEncoding,
                     String outputEncoding,
                     Project project)
            throws IOException
Convienence method to copy a file from a source to a destination specifying if token filtering must be used, if filter chains must be used, if source files may overwrite newer destination files and the last modified time of destFile file should be made equal to the last modified time of sourceFile.

Parameters:
sourceFile - the file to copy from. Must not be null.
destFile - the file to copy to. Must not be null.
filters - the collection of filters to apply to this copy
filterChains - filterChains to apply during the copy.
overwrite - Whether or not the destination file should be overwritten if it already exists.
preserveLastModified - Whether or not the last modified time of the resulting file should be set to that of the source file.
inputEncoding - the encoding used to read the files.
outputEncoding - the encoding used to write the files.
project - the project instance

Since:
Ant 1.6


copyFile

public void copyFile(File sourceFile,
                     File destFile,
                     FilterSetCollection filters,
                     Vector filterChains,
                     boolean overwrite,
                     boolean preserveLastModified,
                     String encoding,
                     Project project)
            throws IOException
Convienence method to copy a file from a source to a destination specifying if token filtering must be used, if filter chains must be used, if source files may overwrite newer destination files and the last modified time of destFile file should be made equal to the last modified time of sourceFile.

Parameters:
sourceFile - the file to copy from. Must not be null.
destFile - the file to copy to. Must not be null.
filters - the collection of filters to apply to this copy
filterChains - filterChains to apply during the copy.
overwrite - Whether or not the destination file should be overwritten if it already exists.
preserveLastModified - Whether or not the last modified time of the resulting file should be set to that of the source file.
encoding - the encoding used to read and write the files.
project - the project instance

Since:
Ant 1.5


copyFile

public void copyFile(File sourceFile,
                     File destFile,
                     FilterSetCollection filters,
                     boolean overwrite)
            throws IOException
Convienence method to copy a file from a source to a destination specifying if token filtering must be used and if source files may overwrite newer destination files.

Parameters:
sourceFile - the file to copy from. Must not be null.
destFile - the file to copy to. Must not be null.
filters - the collection of filters to apply to this copy
overwrite - Whether or not the destination file should be overwritten if it already exists.


copyFile

public void copyFile(File sourceFile,
                     File destFile,
                     FilterSetCollection filters,
                     boolean overwrite,
                     boolean preserveLastModified)
            throws IOException
Convienence method to copy a file from a source to a destination specifying if token filtering must be used, if source files may overwrite newer destination files and the last modified time of destFile file should be made equal to the last modified time of sourceFile.

Parameters:
sourceFile - the file to copy from. Must not be null.
destFile - the file to copy to. Must not be null.
filters - the collection of filters to apply to this copy
overwrite - Whether or not the destination file should be overwritten if it already exists.
preserveLastModified - Whether or not the last modified time of the resulting file should be set to that of the source file.


copyFile

public void copyFile(File sourceFile,
                     File destFile,
                     FilterSetCollection filters,
                     boolean overwrite,
                     boolean preserveLastModified,
                     String encoding)
            throws IOException
Convienence method to copy a file from a source to a destination specifying if token filtering must be used, if source files may overwrite newer destination files, the last modified time of destFile file should be made equal to the last modified time of sourceFile and which character encoding to assume.

Parameters:
sourceFile - the file to copy from. Must not be null.
destFile - the file to copy to. Must not be null.
filters - the collection of filters to apply to this copy
overwrite - Whether or not the destination file should be overwritten if it already exists.
preserveLastModified - Whether or not the last modified time of the resulting file should be set to that of the source file.
encoding - the encoding used to read and write the files.

Since:
Ant 1.5


copyFile

public void copyFile(String sourceFile,
                     String destFile)
            throws IOException
Convienence method to copy a file from a source to a destination. No filtering is performed.

Parameters:
sourceFile - Name of file to copy from. Must not be null.
destFile - Name of file to copy to. Must not be null.


copyFile

public void copyFile(String sourceFile,
                     String destFile,
                     FilterSetCollection filters)
            throws IOException
Convienence method to copy a file from a source to a destination specifying if token filtering must be used.

Parameters:
sourceFile - Name of file to copy from. Must not be null.
destFile - Name of file to copy to. Must not be null.
filters - the collection of filters to apply to this copy


copyFile

public void copyFile(String sourceFile,
                     String destFile,
                     FilterSetCollection filters,
                     Vector filterChains,
                     boolean overwrite,
                     boolean preserveLastModified,
                     String inputEncoding,
                     String outputEncoding,
                     Project project)
            throws IOException
Convienence method to copy a file from a source to a destination specifying if token filtering must be used, if filter chains must be used, if source files may overwrite newer destination files and the last modified time of destFile file should be made equal to the last modified time of sourceFile.

Parameters:
sourceFile - Name of file to copy from. Must not be null.
destFile - Name of file to copy to. Must not be null.
filters - the collection of filters to apply to this copy
filterChains - filterChains to apply during the copy.
overwrite - Whether or not the destination file should be overwritten if it already exists.
preserveLastModified - Whether or not the last modified time of the resulting file should be set to that of the source file.
inputEncoding - the encoding used to read the files.
outputEncoding - the encoding used to write the files.
project - the project instance

Since:
Ant 1.6


copyFile

public void copyFile(String sourceFile,
                     String destFile,
                     FilterSetCollection filters,
                     Vector filterChains,
                     boolean overwrite,
                     boolean preserveLastModified,
                     String encoding,
                     Project project)
            throws IOException
Convienence method to copy a file from a source to a destination specifying if token filtering must be used, if filter chains must be used, if source files may overwrite newer destination files and the last modified time of destFile file should be made equal to the last modified time of sourceFile.

Parameters:
sourceFile - Name of file to copy from. Must not be null.
destFile - Name of file to copy to. Must not be null.
filters - the collection of filters to apply to this copy
filterChains - filterChains to apply during the copy.
overwrite - Whether or not the destination file should be overwritten if it already exists.
preserveLastModified - Whether or not the last modified time of the resulting file should be set to that of the source file.
encoding - the encoding used to read and write the files.
project - the project instance

Since:
Ant 1.5


copyFile

public void copyFile(String sourceFile,
                     String destFile,
                     FilterSetCollection filters,
                     boolean overwrite)
            throws IOException
Convienence method to copy a file from a source to a destination specifying if token filtering must be used and if source files may overwrite newer destination files.

Parameters:
sourceFile - Name of file to copy from. Must not be null.
destFile - Name of file to copy to. Must not be null.
filters - the collection of filters to apply to this copy
overwrite - Whether or not the destination file should be overwritten if it already exists.


copyFile

public void copyFile(String sourceFile,
                     String destFile,
                     FilterSetCollection filters,
                     boolean overwrite,
                     boolean preserveLastModified)
            throws IOException
Convienence method to copy a file from a source to a destination specifying if token filtering must be used, if source files may overwrite newer destination files and the last modified time of destFile file should be made equal to the last modified time of sourceFile.

Parameters:
sourceFile - Name of file to copy from. Must not be null.
destFile - Name of file to copy to. Must not be null.
filters - the collection of filters to apply to this copy
overwrite - Whether or not the destination file should be overwritten if it already exists.
preserveLastModified - Whether or not the last modified time of the resulting file should be set to that of the source file.


copyFile

public void copyFile(String sourceFile,
                     String destFile,
                     FilterSetCollection filters,
                     boolean overwrite,
                     boolean preserveLastModified,
                     String encoding)
            throws IOException
Convienence method to copy a file from a source to a destination specifying if token filtering must be used, if source files may overwrite newer destination files and the last modified time of destFile file should be made equal to the last modified time of sourceFile.

Parameters:
sourceFile - Name of file to copy from. Must not be null.
destFile - Name of file to copy to. Must not be null.
filters - the collection of filters to apply to this copy
overwrite - Whether or not the destination file should be overwritten if it already exists.
preserveLastModified - Whether or not the last modified time of the resulting file should be set to that of the source file.
encoding - the encoding used to read and write the files.

Since:
Ant 1.5


createNewFile

public boolean createNewFile(File f)
            throws IOException
Emulation of File.createNewFile for JDK 1.1.

This method does not guarantee that the operation is atomic.

Parameters:
f - the file to be created

Returns:
true if the file did not exist already.

Since:
Ant 1.5


createTempFile

public File createTempFile(String prefix,
                           String suffix,
                           File parentDir)
Create a temporary file in a given directory.

The file denoted by the returned abstract pathname did not exist before this method was invoked, any subsequent invocation of this method will yield a different file name.

This method is different to File.createTempFile of JDK 1.2 as it doesn't create the file itself. It uses the location pointed to by java.io.tmpdir when the parentDir attribute is null.

Parameters:
parentDir - Directory to create the temporary file in - current working directory will be assumed if this parameter is null.

Returns:
a File reference to the new temporary file.

Since:
ant 1.5


fileNameEquals

public boolean fileNameEquals(File f1,
                              File f2)
Compares two filenames.

Unlike java.io.File#equals this method will try to compare the absolute paths and "normalize" the filenames before comparing them.

Parameters:
f1 - the file whose name is to be compared.
f2 - the other file whose name is to be compared.

Returns:
true if the file are for the same file.

Since:
Ant 1.5.3


fromURI

public String fromURI(String uri)
Constructs a file path from a file: URI.

Will be an absolute path if the given URI is absolute.

Swallows '%' that are not followed by two characters, doesn't deal with non-ASCII characters.

Parameters:
uri - the URI designating a file in the local filesystem.

Returns:
the local file system path for the file.

Since:
Ant 1.6


getFileTimestampGranularity

public long getFileTimestampGranularity()


getFileURL

public URL getFileURL(File file)
            throws MalformedURLException
Get the URL for a file taking into account # characters

Parameters:
file - the file whose URL representation is required.

Returns:
The FileURL value


getParentFile

public File getParentFile(File f)
Emulation of File.getParentFile for JDK 1.1

Parameters:
f - the file whose parent is required.

Returns:
the given file's parent, or null if the file does not have a parent.

Since:
1.10


getSetLastModified

protected final Method getSetLastModified()
see whether we have a setLastModified method in File and return it.

Returns:
a method to setLastModified.


isSymbolicLink

public boolean isSymbolicLink(File parent,
                              String name)
            throws IOException
Checks whether a given file is a symbolic link.

It doesn't really test for symbolic links but whether the canonical and absolute paths of the file are identical - this may lead to false positives on some platforms.

Parameters:
parent - the parent directory of the file to test
name - the name of the file to test.

Returns:
true if the file is a symbolic link.

Since:
Ant 1.5


newFileUtils

public static FileUtils newFileUtils()
Factory method.

Returns:
a new instance of FileUtils.


normalize

public File normalize(String path)
"normalize" the given absolute path.

This includes:

  • Uppercase the drive letter if there is one.
  • Remove redundant slashes after the drive spec.
  • resolve all ./, .\, ../ and ..\ sequences.
  • DOS style paths that start with a drive letter will have \ as the separator.
Unlike File#getCanonicalPath() it specifically doesn't resolve symbolic links.

Parameters:
path - the path to be normalized

Returns:
the normalized version of the path.


readFully

public static final String readFully(Reader rdr)
            throws IOException
Read from reader till EOF

Parameters:
rdr - the reader from which to read.

Returns:
the contents read out of the given reader


readFully

public static final String readFully(Reader rdr,
                                     int bufferSize)
            throws IOException
Read from reader till EOF

Parameters:
rdr - the reader from which to read.
bufferSize - the buffer size to use when reading

Returns:
the contents read out of the given reader


removeLeadingPath

public String removeLeadingPath(File leading,
                                File path)
Removes a leading path from a second path.

Parameters:
leading - The leading path, must not be null, must be absolute.
path - The path to remove from, must not be null, must be absolute.

Returns:
path's normalized absolute if it doesn't start with leading, path's path with leading's path removed otherwise.

Since:
Ant 1.5


rename

public void rename(File from,
                   File to)
            throws IOException
Renames a file, even if that involves crossing file system boundaries.

This will remove to (if it exists), ensure that to's parent directory exists and move from, which involves deleting from as well.

Parameters:
from - the file to move
to - the new file name

Since:
Ant 1.6


resolveFile

public File resolveFile(File file,
                        String filename)
Interpret the filename as a file relative to the given file - unless the filename already represents an absolute filename.

Parameters:
file - the "reference" file for relative paths. This instance must be an absolute file and must not contain "./" or "../" sequences (same for \ instead of /). If it is null, this call is equivalent to new java.io.File(filename).
filename - a file name

Returns:
an absolute file that doesn't contain "./" or "../" sequences and uses the correct separator for the current platform.


setFileLastModified

public void setFileLastModified(File file,
                                long time)
            throws BuildException
Calls File.setLastModified(long time) in a Java 1.1 compatible way.

Parameters:
file - the file whose modified time is to be set
time - the time to which the last modified time is to be set.

Throws:
BuildException - if the time cannot be set.


toURI

public String toURI(String path)
Constructs a file: URI that represents the external form of the given pathname.

Will be an absolute URI if the given path is absolute.

This code doesn't handle non-ASCII characters properly.

Parameters:
path - the path in the local file system

Returns:
the URI version of the local path.

Since:
Ant 1.6


toVMSPath

public String toVMSPath(File f)
Returns a VMS String representation of a File object. This is useful since the JVM by default internally converts VMS paths to Unix style. The returned String is always an absolute path.

Parameters:
f - The File to get the VMS path for.

Returns:
The absolute VMS path to f.


Copyright B) 2000-2005 Apache Software Foundation. All Rights Reserved.