FileDocCategorySizeDatePackage
FileUtils.javaAPI DocApache Ant 1.7058621Wed Dec 13 06:16:20 GMT 2006org.apache.tools.ant.util

FileUtils

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

Fields Summary
private static final FileUtils
PRIMARY_INSTANCE
private static Random
rand
private static boolean
onNetWare
private static boolean
onDos
private static boolean
onWin9x
private static boolean
onWindows
static final int
BUF_SIZE
public static final long
FAT_FILE_TIMESTAMP_GRANULARITY
The granularity of timestamps under FAT.
public static final long
UNIX_FILE_TIMESTAMP_GRANULARITY
The granularity of timestamps under Unix.
public static final long
NTFS_FILE_TIMESTAMP_GRANULARITY
The granularity of timestamps under the NT File System. NTFS has a granularity of 100 nanoseconds, which is less than 1 millisecond, so we round this up to 1 millisecond.
private Object
cacheFromUriLock
A one item cache for fromUri. fromUri is called for each element when parseing ant build files. It is a costly operation. This just caches the result of the last call.
private String
cacheFromUriRequest
private String
cacheFromUriResponse
Constructors Summary
protected FileUtils()
Empty constructor.

    
Methods Summary
public static voidclose(java.io.Writer device)
Close a Writer without throwing any exception if something went wrong. Do not attempt to close it if the argument is null.

param
device output writer, can be null.

        if (device != null) {
            try {
                device.close();
            } catch (IOException ioex) {
                //ignore
            }
        }
    
public static voidclose(java.io.Reader device)
Close a stream without throwing any exception if something went wrong. Do not attempt to close it if the argument is null.

param
device Reader, can be null.

        if (device != null) {
            try {
                device.close();
            } catch (IOException ioex) {
                //ignore
            }
        }
    
public static voidclose(java.io.OutputStream device)
Close a stream without throwing any exception if something went wrong. Do not attempt to close it if the argument is null.

param
device stream, can be null.

        if (device != null) {
            try {
                device.close();
            } catch (IOException ioex) {
                //ignore
            }
        }
    
public static voidclose(java.io.InputStream device)
Close a stream without throwing any exception if something went wrong. Do not attempt to close it if the argument is null.

param
device stream, can be null.

        if (device != null) {
            try {
                device.close();
            } catch (IOException ioex) {
                //ignore
            }
        }
    
public booleancontentEquals(java.io.File f1, java.io.File f2)
Compares the contents of two files.

param
f1 the file whose content is to be compared.
param
f2 the other file whose content is to be compared.
return
true if the content of the files is the same.
throws
IOException if the files cannot be read.

        return contentEquals(f1, f2, false);
    
public booleancontentEquals(java.io.File f1, java.io.File f2, boolean textfile)
Compares the contents of two files.

param
f1 the file whose content is to be compared.
param
f2 the other file whose content is to be compared.
param
textfile true if the file is to be treated as a text file and differences in kind of line break are to be ignored.
return
true if the content of the files is the same.
throws
IOException if the files cannot be read.
since
Ant 1.6.3

        return ResourceUtils.contentEquals(
            new FileResource(f1), new FileResource(f2), textfile);
    
public voidcopyFile(java.lang.String sourceFile, java.lang.String destFile, org.apache.tools.ant.types.FilterSetCollection filters, java.util.Vector filterChains, boolean overwrite, boolean preserveLastModified, java.lang.String encoding, org.apache.tools.ant.Project project)
Convenience 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.

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

        copyFile(new File(sourceFile), new File(destFile), filters,
                 filterChains, overwrite, preserveLastModified,
                 encoding, project);
    
public voidcopyFile(java.lang.String sourceFile, java.lang.String destFile, org.apache.tools.ant.types.FilterSetCollection filters, java.util.Vector filterChains, boolean overwrite, boolean preserveLastModified, java.lang.String inputEncoding, java.lang.String outputEncoding, org.apache.tools.ant.Project project)
Convenience 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.

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

        copyFile(new File(sourceFile), new File(destFile), filters,
                 filterChains, overwrite, preserveLastModified,
                 inputEncoding, outputEncoding, project);
    
public voidcopyFile(java.io.File sourceFile, java.io.File destFile)
Convenience method to copy a file from a source to a destination. No filtering is performed.

param
sourceFile the file to copy from. Must not be null.
param
destFile the file to copy to. Must not be null.
throws
IOException if the copying fails.

        copyFile(sourceFile, destFile, null, false, false);
    
public voidcopyFile(java.io.File sourceFile, java.io.File destFile, org.apache.tools.ant.types.FilterSetCollection filters)
Convenience method to copy a file from a source to a destination specifying if token filtering must be used.

param
sourceFile the file to copy from. Must not be null.
param
destFile the file to copy to. Must not be null.
param
filters the collection of filters to apply to this copy.
throws
IOException if the copying fails.

        copyFile(sourceFile, destFile, filters, false, false);
    
public voidcopyFile(java.io.File sourceFile, java.io.File destFile, org.apache.tools.ant.types.FilterSetCollection filters, boolean overwrite)
Convenience 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.

param
sourceFile the file to copy from. Must not be null.
param
destFile the file to copy to. Must not be null.
param
filters the collection of filters to apply to this copy.
param
overwrite Whether or not the destination file should be overwritten if it already exists.
throws
IOException if the copying fails.

        copyFile(sourceFile, destFile, filters, overwrite, false);
    
public voidcopyFile(java.io.File sourceFile, java.io.File destFile, org.apache.tools.ant.types.FilterSetCollection filters, boolean overwrite, boolean preserveLastModified)
Convenience 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.

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

        copyFile(sourceFile, destFile, filters, overwrite,
                 preserveLastModified, null);
    
public voidcopyFile(java.io.File sourceFile, java.io.File destFile, org.apache.tools.ant.types.FilterSetCollection filters, boolean overwrite, boolean preserveLastModified, java.lang.String encoding)
Convenience 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.

param
sourceFile the file to copy from. Must not be null.
param
destFile the file to copy to. Must not be null.
param
filters the collection of filters to apply to this copy.
param
overwrite Whether or not the destination file should be overwritten if it already exists.
param
preserveLastModified Whether or not the last modified time of the resulting file should be set to that of the source file.
param
encoding the encoding used to read and write the files.
throws
IOException if the copying fails.
since
Ant 1.5

        copyFile(sourceFile, destFile, filters, null, overwrite,
                 preserveLastModified, encoding, null);
    
public voidcopyFile(java.io.File sourceFile, java.io.File destFile, org.apache.tools.ant.types.FilterSetCollection filters, java.util.Vector filterChains, boolean overwrite, boolean preserveLastModified, java.lang.String encoding, org.apache.tools.ant.Project project)
Convenience 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.

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

        copyFile(sourceFile, destFile, filters, filterChains,
                 overwrite, preserveLastModified, encoding, encoding, project);
    
public voidcopyFile(java.io.File sourceFile, java.io.File destFile, org.apache.tools.ant.types.FilterSetCollection filters, java.util.Vector filterChains, boolean overwrite, boolean preserveLastModified, java.lang.String inputEncoding, java.lang.String outputEncoding, org.apache.tools.ant.Project project)
Convenience 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.

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

        ResourceUtils.copyResource(
            new FileResource(sourceFile), new FileResource(destFile),
            filters, filterChains, overwrite, preserveLastModified,
            inputEncoding, outputEncoding, project);
    
public voidcopyFile(java.lang.String sourceFile, java.lang.String destFile)
Convenience method to copy a file from a source to a destination. No filtering is performed.

param
sourceFile Name of file to copy from. Must not be null.
param
destFile Name of file to copy to. Must not be null.
throws
IOException if the copying fails.

        copyFile(new File(sourceFile), new File(destFile), null, false, false);
    
public voidcopyFile(java.lang.String sourceFile, java.lang.String destFile, org.apache.tools.ant.types.FilterSetCollection filters)
Convenience method to copy a file from a source to a destination specifying if token filtering must be used.

param
sourceFile Name of file to copy from. Must not be null.
param
destFile Name of file to copy to. Must not be null.
param
filters the collection of filters to apply to this copy.
throws
IOException if the copying fails.

        copyFile(new File(sourceFile), new File(destFile), filters,
                 false, false);
    
public voidcopyFile(java.lang.String sourceFile, java.lang.String destFile, org.apache.tools.ant.types.FilterSetCollection filters, boolean overwrite)
Convenience 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.

param
sourceFile Name of file to copy from. Must not be null.
param
destFile Name of file to copy to. Must not be null.
param
filters the collection of filters to apply to this copy.
param
overwrite Whether or not the destination file should be overwritten if it already exists.
throws
IOException if the copying fails.

        copyFile(new File(sourceFile), new File(destFile), filters,
                 overwrite, false);
    
public voidcopyFile(java.lang.String sourceFile, java.lang.String destFile, org.apache.tools.ant.types.FilterSetCollection filters, boolean overwrite, boolean preserveLastModified)
Convenience 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.

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

        copyFile(new File(sourceFile), new File(destFile), filters,
                 overwrite, preserveLastModified);
    
public voidcopyFile(java.lang.String sourceFile, java.lang.String destFile, org.apache.tools.ant.types.FilterSetCollection filters, boolean overwrite, boolean preserveLastModified, java.lang.String encoding)
Convenience 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.

param
sourceFile Name of file to copy from. Must not be null.
param
destFile Name of file to copy to. Must not be null.
param
filters the collection of filters to apply to this copy.
param
overwrite Whether or not the destination file should be overwritten if it already exists.
param
preserveLastModified Whether or not the last modified time of the resulting file should be set to that of the source file.
param
encoding the encoding used to read and write the files.
throws
IOException if the copying fails.
since
Ant 1.5

        copyFile(new File(sourceFile), new File(destFile), filters,
                 overwrite, preserveLastModified, encoding);
    
public booleancreateNewFile(java.io.File f)
This was originally an emulation of File.createNewFile for JDK 1.1, but it is now implemented using that method (Ant 1.6.3 onwards).

This method has historically not guaranteed that the operation was atomic. In its current implementation it is.

param
f the file to be created.
return
true if the file did not exist already.
throws
IOException on error.
since
Ant 1.5

        return f.createNewFile();
    
public booleancreateNewFile(java.io.File f, boolean mkdirs)
Create a new file, optionally creating parent directories.

param
f the file to be created.
param
mkdirs boolean whether to create parent directories.
return
true if the file did not exist already.
throws
IOException on error.
since
Ant 1.6.3

        File parent = f.getParentFile();
        if (mkdirs && !(parent.exists())) {
            parent.mkdirs();
        }
        return f.createNewFile();
    
public java.io.FilecreateTempFile(java.lang.String prefix, java.lang.String suffix, java.io.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.

The filename is prefixNNNNNsuffix where NNNN is a random number.

This method is different from 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.

param
prefix prefix before the random number.
param
suffix file extension; include the '.'.
param
parentDir Directory to create the temporary file in; java.io.tmpdir used if not specified.
return
a File reference to the new temporary file.
since
Ant 1.5

        return createTempFile(prefix, suffix, parentDir, false);
    
public java.io.FilecreateTempFile(java.lang.String prefix, java.lang.String suffix, java.io.File parentDir, boolean deleteOnExit)
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.

The filename is prefixNNNNNsuffix where NNNN is a random number.

This method is different from 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.

param
prefix prefix before the random number.
param
suffix file extension; include the '.'.
param
parentDir Directory to create the temporary file in;
param
deleteOnExit whether to set the tempfile for deletion on normal VM exit. java.io.tmpdir used if not specified.
return
a File reference to the new temporary file.
since
Ant 1.7

        File result = null;
        String parent = (parentDir == null)
            ? System.getProperty("java.io.tmpdir")
            : parentDir.getPath();

        DecimalFormat fmt = new DecimalFormat("#####");
        synchronized (rand) {
            do {
                result = new File(parent,
                                  prefix + fmt.format(Math.abs(rand.nextInt()))
                                  + suffix);
            } while (result.exists());
        }
        if (deleteOnExit) {
            result.deleteOnExit();
        }
        return result;
    
public static voiddelete(java.io.File file)
Delete the file with {@link File#delete()} if the argument is not null. Do nothing on a null argument.

param
file file to delete.

        if (file != null) {
            file.delete();
        }
    
public java.lang.String[]dissect(java.lang.String path)
Dissect the specified absolute path.

param
path the path to dissect.
return
String[] {root, remaining path}.
throws
java.lang.NullPointerException if path is null.
since
Ant 1.7

        char sep = File.separatorChar;
        path = path.replace('/", sep).replace('\\", sep);

        // make sure we are dealing with an absolute path
        if (!isAbsolutePath(path)) {
            throw new BuildException(path + " is not an absolute path");
        }
        String root = null;
        int colon = path.indexOf(':");
        if (colon > 0 && (onDos || onNetWare)) {

            int next = colon + 1;
            root = path.substring(0, next);
            char[] ca = path.toCharArray();
            root += sep;
            //remove the initial separator; the root has it.
            next = (ca[next] == sep) ? next + 1 : next;

            StringBuffer sbPath = new StringBuffer();
            // Eliminate consecutive slashes after the drive spec:
            for (int i = next; i < ca.length; i++) {
                if (ca[i] != sep || ca[i - 1] != sep) {
                    sbPath.append(ca[i]);
                }
            }
            path = sbPath.toString();
        } else if (path.length() > 1 && path.charAt(1) == sep) {
            // UNC drive
            int nextsep = path.indexOf(sep, 2);
            nextsep = path.indexOf(sep, nextsep + 1);
            root = (nextsep > 2) ? path.substring(0, nextsep + 1) : path;
            path = path.substring(root.length());
        } else {
            root = File.separator;
            path = path.substring(1);
        }
        return new String[] {root, path};
    
public booleanfileNameEquals(java.io.File f1, java.io.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.

param
f1 the file whose name is to be compared.
param
f2 the other file whose name is to be compared.
return
true if the file are for the same file.
since
Ant 1.5.3

        return normalize(f1.getAbsolutePath())
            .equals(normalize(f2.getAbsolutePath()));
    
public java.lang.StringfromURI(java.lang.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.

param
uri the URI designating a file in the local filesystem.
return
the local file system path for the file.
since
Ant 1.6

        synchronized (cacheFromUriLock) {
            if (uri.equals(cacheFromUriRequest)) {
                return cacheFromUriResponse;
            }
            String path = Locator.fromURI(uri);
            String ret = isAbsolutePath(path)
                ? normalize(path).getAbsolutePath() : path;
            cacheFromUriRequest = uri;
            cacheFromUriResponse = ret;
            return ret;
        }
    
public java.lang.StringgetDefaultEncoding()
Get the default encoding. This is done by opening an InputStreamReader on a dummy InputStream and getting the encoding. Could use System.getProperty("file.encoding"), but cannot see where this is documented.

return
the default file encoding.

        InputStreamReader is = new InputStreamReader(
            new InputStream() {
                public int read() {
                    return -1;
                }
            });
        try {
            return is.getEncoding();
        } finally {
            close(is);
        }
    
public longgetFileTimestampGranularity()
Get the granularity of file timestamps. The choice is made based on OS, which is incorrect--it should really be by filesystem. We do not have an easy way to probe for file systems, however, so this heuristic gives us a decent default.

return
the difference, in milliseconds, which two file timestamps must have in order for the two files to be considered to have different timestamps.

        if (onWin9x) {
            return FAT_FILE_TIMESTAMP_GRANULARITY;
        } else if (onWindows) {
            return NTFS_FILE_TIMESTAMP_GRANULARITY;
        } else if (onDos) {
            return FAT_FILE_TIMESTAMP_GRANULARITY;
        }
        return UNIX_FILE_TIMESTAMP_GRANULARITY;
    
public java.net.URLgetFileURL(java.io.File file)
Get the URL for a file taking into account # characters.

param
file the file whose URL representation is required.
return
The FileURL value.
throws
MalformedURLException if the URL representation cannot be formed.

        return new URL(toURI(file.getAbsolutePath()));
    
public static org.apache.tools.ant.util.FileUtilsgetFileUtils()
Method to retrieve The FileUtils, which is shared by all users of this method.

return
an instance of FileUtils.
since
Ant 1.6.3

        return PRIMARY_INSTANCE;
    
public java.io.FilegetParentFile(java.io.File f)
This was originally an emulation of {@link File#getParentFile} for JDK 1.1, but it is now implemented using that method (Ant 1.6.3 onwards).

param
f the file whose parent is required.
return
the given file's parent, or null if the file does not have a parent.
since
1.10
deprecated
since 1.7. Just use {@link File#getParentFile} directly.

        return (f == null) ? null : f.getParentFile();
    
public static java.lang.StringgetPath(java.util.List pathStack)
Gets path from a List of Strings.

param
pathStack List of Strings to be concated as a path.
return
String, never null
since
Ant 1.7

        // can safely use '/' because Windows understands '/' as separator
        return getPath(pathStack, '/");
    
public static java.lang.StringgetPath(java.util.List pathStack, char separatorChar)
Gets path from a List of Strings.

param
pathStack List of Strings to be concated as a path.
param
separatorChar char to be used as separator between names in path
return
String, never null
since
Ant 1.7

        final StringBuffer buffer = new StringBuffer();

        final Iterator iter = pathStack.iterator();
        if (iter.hasNext()) {
            buffer.append(iter.next());
        }

        while (iter.hasNext()) {
            buffer.append(separatorChar);
            buffer.append(iter.next());
        }

        return buffer.toString();
    
public static java.lang.String[]getPathStack(java.lang.String path)
Gets all names of the path as an array of Strings.

param
path to get names from
return
Strings, never null
since
Ant 1.7

        String normalizedPath = path.replace(File.separatorChar, '/");

        // since Java 1.4
        //return normalizedPath.split("/");
        // workaround for Java 1.2-1.3
        Object[] tokens = StringUtils.split(normalizedPath, '/").toArray();
        String[] rv = new String[tokens.length];
        System.arraycopy(tokens, 0, rv, 0, tokens.length);

        return rv;
    
public static java.lang.StringgetRelativePath(java.io.File fromFile, java.io.File toFile)
Calculates the relative path between two files.

Implementation note:
This function my throw an IOException if an I/O error occurs because its use of the canonical pathname may require filesystem queries.

param
fromFile the File to calculate the path from
param
toFile the File to calculate the path to
return
the relative path between the files
throws
Exception for undocumented reasons
see
File#getCanonicalPath()
since
Ant 1.7

        String fromPath = fromFile.getCanonicalPath();
        String toPath = toFile.getCanonicalPath();

        // build the path stack info to compare
        String[] fromPathStack = getPathStack(fromPath);
        String[] toPathStack = getPathStack(toPath);

        if (0 < toPathStack.length && 0 < fromPathStack.length) {
            if (!fromPathStack[0].equals(toPathStack[0])) {
                // not the same device (would be "" on Linux/Unix)

                return getPath(Arrays.asList(toPathStack));
            }
        } else {
            // no comparison possible
            return getPath(Arrays.asList(toPathStack));
        }

        int minLength = Math
                .min(fromPathStack.length, toPathStack.length);

        int same = 1;

        // get index of parts which are equal
        for (; same < minLength; same++) {
            if (!fromPathStack[same].equals(toPathStack[same])) {
                break;
            }
        }

        List relativePathStack = new ArrayList();

        // if "from" part is longer, fill it up with ".."
        // to reach path which is equal to both paths
        for (int i = same; i < fromPathStack.length; i++) {
            relativePathStack.add("..");
        }

        // fill it up path with parts which were not equal
        for (int i = same; i < toPathStack.length; i++) {
            relativePathStack.add(toPathStack[i]);
        }

        return getPath(relativePathStack);
    
public static booleanisAbsolutePath(java.lang.String filename)
Verifies that the specified filename represents an absolute path. Differs from new java.io.File("filename").isAbsolute() in that a path beginning with a double file separator--signifying a Windows UNC--must at minimum match "\\a\b" to be considered an absolute path.

param
filename the filename to be checked.
return
true if the filename represents an absolute path.
throws
java.lang.NullPointerException if filename is null.
since
Ant 1.6.3

        int len = filename.length();
        if (len == 0) {
            return false;
        }
        char sep = File.separatorChar;
        filename = filename.replace('/", sep).replace('\\", sep);
        char c = filename.charAt(0);
        if (!(onDos || onNetWare)) {
            return (c == sep);
        }
        if (c == sep) {
            if (!(onDos && len > 4 && filename.charAt(1) == sep)) {
                return false;
            }
            int nextsep = filename.indexOf(sep, 2);
            return nextsep > 2 && nextsep + 1 < len;
        }
        int colon = filename.indexOf(':");
        return (Character.isLetter(c) && colon == 1
            && filename.length() > 2 && filename.charAt(2) == sep)
            || (onNetWare && colon > 0);
    
public static booleanisContextRelativePath(java.lang.String filename)
On DOS and NetWare, the evaluation of certain file specifications is context-dependent. These are filenames beginning with a single separator (relative to current root directory) and filenames with a drive specification and no intervening separator (relative to current directory of the specified root).

param
filename the filename to evaluate.
return
true if the filename is relative to system context.
throws
java.lang.NullPointerException if filename is null.
since
Ant 1.7

        if (!(onDos || onNetWare) || filename.length() == 0) {
            return false;
        }
        char sep = File.separatorChar;
        filename = filename.replace('/", sep).replace('\\", sep);
        char c = filename.charAt(0);
        int len = filename.length();
        return (c == sep && (len == 1 || filename.charAt(1) != sep))
            || (Character.isLetter(c) && len > 1
            && filename.indexOf(':") == 1
            && (len == 2 || filename.charAt(2) != sep));
    
public booleanisLeadingPath(java.io.File leading, java.io.File path)
Learn whether one path "leads" another.

param
leading The leading path, must not be null, must be absolute.
param
path The path to remove from, must not be null, must be absolute.
return
true if path starts with leading; false otherwise.
since
Ant 1.7

        String l = normalize(leading.getAbsolutePath()).getAbsolutePath();
        String p = normalize(path.getAbsolutePath()).getAbsolutePath();
        if (l.equals(p)) {
            return true;
        }
        // ensure that l ends with a /
        // so we never think /foo was a parent directory of /foobar
        if (!l.endsWith(File.separator)) {
            l += File.separator;
        }
        return p.startsWith(l);
    
public booleanisSymbolicLink(java.io.File parent, java.lang.String name)
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.

param
parent the parent directory of the file to test
param
name the name of the file to test.
return
true if the file is a symbolic link.
throws
IOException on error.
since
Ant 1.5

        if (parent == null) {
            File f = new File(name);
            parent = f.getParentFile();
            name = f.getName();
        }
        File toTest = new File(parent.getCanonicalPath(), name);
        return !toTest.getAbsolutePath().equals(toTest.getCanonicalPath());
    
public booleanisUpToDate(java.io.File source, java.io.File dest, long granularity)
Returns true if the source is older than the dest. If the dest file does not exist, then the test returns false; it is implicitly not up do date.

param
source source file (should be the older).
param
dest dest file (should be the newer).
param
granularity an offset added to the source time.
return
true if the source is older than the dest after accounting for granularity.
since
Ant 1.6.3

        //do a check for the destination file existing
        if (!dest.exists()) {
            //if it does not, then the file is not up to date.
            return false;
        }
        long sourceTime = source.lastModified();
        long destTime = dest.lastModified();
        return isUpToDate(sourceTime, destTime, granularity);
    
public booleanisUpToDate(java.io.File source, java.io.File dest)
Returns true if the source is older than the dest.

param
source source file (should be the older).
param
dest dest file (should be the newer).
return
true if the source is older than the dest, taking the granularity into account.
since
Ant 1.6.3

        return isUpToDate(source, dest, getFileTimestampGranularity());
    
public booleanisUpToDate(long sourceTime, long destTime, long granularity)
Compare two timestamps for being up to date using the specified granularity.

param
sourceTime timestamp of source file.
param
destTime timestamp of dest file.
param
granularity os/filesys granularity.
return
true if the dest file is considered up to date.

        if (destTime == -1) {
            return false;
        }
        return destTime >= sourceTime + granularity;
    
public booleanisUpToDate(long sourceTime, long destTime)
Compare two timestamps for being up to date using the current granularity.

param
sourceTime timestamp of source file.
param
destTime timestamp of dest file.
return
true if the dest file is considered up to date.

        return isUpToDate(sourceTime, destTime, getFileTimestampGranularity());
    
public static org.apache.tools.ant.util.FileUtilsnewFileUtils()
Factory method.

return
a new instance of FileUtils.
deprecated
since 1.7. Use getFileUtils instead, FileUtils do not have state.


                                        
        
        return new FileUtils();
    
public java.io.Filenormalize(java.lang.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 {@link File#getCanonicalPath()} this method specifically does not resolve symbolic links.

param
path the path to be normalized.
return
the normalized version of the path.
throws
java.lang.NullPointerException if path is null.

        Stack s = new Stack();
        String[] dissect = dissect(path);
        s.push(dissect[0]);

        StringTokenizer tok = new StringTokenizer(dissect[1], File.separator);
        while (tok.hasMoreTokens()) {
            String thisToken = tok.nextToken();
            if (".".equals(thisToken)) {
                continue;
            } else if ("..".equals(thisToken)) {
                if (s.size() < 2) {
                    // Cannot resolve it, so skip it.
                    return new File(path);
                }
                s.pop();
            } else { // plain component
                s.push(thisToken);
            }
        }
        StringBuffer sb = new StringBuffer();
        for (int i = 0; i < s.size(); i++) {
            if (i > 1) {
                // not before the filesystem root and not after it, since root
                // already contains one
                sb.append(File.separatorChar);
            }
            sb.append(s.elementAt(i));
        }
        return new File(sb.toString());
    
public static final java.lang.StringreadFully(java.io.Reader rdr)
Read from reader till EOF.

param
rdr the reader from which to read.
return
the contents read out of the given reader.
throws
IOException if the contents could not be read out from the reader.

        return readFully(rdr, BUF_SIZE);
    
public static final java.lang.StringreadFully(java.io.Reader rdr, int bufferSize)
Read from reader till EOF.

param
rdr the reader from which to read.
param
bufferSize the buffer size to use when reading.
return
the contents read out of the given reader.
throws
IOException if the contents could not be read out from the reader.

        if (bufferSize <= 0) {
            throw new IllegalArgumentException("Buffer size must be greater "
                                               + "than 0");
        }
        final char[] buffer = new char[bufferSize];
        int bufferLength = 0;
        StringBuffer textBuffer = null;
        while (bufferLength != -1) {
            bufferLength = rdr.read(buffer);
            if (bufferLength > 0) {
                textBuffer = (textBuffer == null) ? new StringBuffer() : textBuffer;
                textBuffer.append(new String(buffer, 0, bufferLength));
            }
        }
        return (textBuffer == null) ? null : textBuffer.toString();
    
public java.lang.StringremoveLeadingPath(java.io.File leading, java.io.File path)
Removes a leading path from a second path.

param
leading The leading path, must not be null, must be absolute.
param
path The path to remove from, must not be null, must be absolute.
return
path's normalized absolute if it doesn't start with leading; path's path with leading's path removed otherwise.
since
Ant 1.5

        String l = normalize(leading.getAbsolutePath()).getAbsolutePath();
        String p = normalize(path.getAbsolutePath()).getAbsolutePath();
        if (l.equals(p)) {
            return "";
        }

        // ensure that l ends with a /
        // so we never think /foo was a parent directory of /foobar
        if (!l.endsWith(File.separator)) {
            l += File.separator;
        }
        return (p.startsWith(l)) ? p.substring(l.length()) : p;
    
public voidrename(java.io.File from, java.io.File to)
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.

param
from the file to move.
param
to the new file name.
throws
IOException if anything bad happens during this process. Note that to may have been deleted already when this happens.
since
Ant 1.6

        if (to.exists() && !to.delete()) {
            throw new IOException("Failed to delete " + to
                                  + " while trying to rename " + from);
        }
        File parent = to.getParentFile();
        if (parent != null && !parent.exists() && !parent.mkdirs()) {
            throw new IOException("Failed to create directory " + parent
                                  + " while trying to rename " + from);
        }
        if (!from.renameTo(to)) {
            copyFile(from, to);
            if (!from.delete()) {
                throw new IOException("Failed to delete " + from
                                      + " while trying to rename it.");
            }
        }
    
public java.io.FileresolveFile(java.io.File file, java.lang.String filename)
Interpret the filename as a file relative to the given file unless the filename already represents an absolute filename. Differs from new File(file, filename) in that the resulting File's path will always be a normalized, absolute pathname. Also, if it is determined that filename is context-relative, file will be discarded and the reference will be resolved using available context/state information about the filesystem.

param
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).getAbsoluteFile().
param
filename a file name.
return
an absolute file.
throws
java.lang.NullPointerException if filename is null.

        if (!isAbsolutePath(filename)) {
            char sep = File.separatorChar;
            filename = filename.replace('/", sep).replace('\\", sep);
            if (isContextRelativePath(filename)) {
                file = null;
                // on cygwin, our current directory can be a UNC;
                // assume user.dir is absolute or all hell breaks loose...
                String udir = System.getProperty("user.dir");
                if (filename.charAt(0) == sep && udir.charAt(0) == sep) {
                    filename = dissect(udir)[0] + filename.substring(1);
                }
            }
            filename = new File(file, filename).getAbsolutePath();
        }
        return normalize(filename);
    
public voidsetFileLastModified(java.io.File file, long time)
Calls File.setLastModified(long time). Originally written to to dynamically bind to that call on Java1.2+.

param
file the file whose modified time is to be set
param
time the time to which the last modified time is to be set. if this is -1, the current time is used.

        ResourceUtils.setLastModified(new FileResource(file), time);
    
public java.lang.StringtoURI(java.lang.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 encodes non ASCII characters too.

The coding of the output is the same as what File.toURI().toASCIIString() produces

See dt-sysid which makes some mention of how characters not supported by URI Reference syntax should be escaped.

param
path the path in the local file system.
return
the URI version of the local path.
since
Ant 1.6

        // #8031: first try Java 1.4.
        Class uriClazz = null;
        try {
            uriClazz = Class.forName("java.net.URI");
        } catch (ClassNotFoundException e) {
            // OK, Java 1.3.
        }
        if (uriClazz != null) {
            try {
                File f = new File(path).getAbsoluteFile();
                java.lang.reflect.Method toURIMethod = File.class.getMethod("toURI", new Class[0]);
                Object uriObj = toURIMethod.invoke(f, new Object[] {});
                java.lang.reflect.Method toASCIIStringMethod
                    = uriClazz.getMethod("toASCIIString", new Class[0]);
                return (String) toASCIIStringMethod.invoke(uriObj, new Object[] {});
            } catch (Exception e) {
                // Reflection problems? Should not happen, debug.
                e.printStackTrace();
            }
        }
        boolean isDir = new File(path).isDirectory();

        StringBuffer sb = new StringBuffer("file:");

        path = resolveFile(null, path).getPath();
        sb.append("//");
        // add an extra slash for filesystems with drive-specifiers
        if (!path.startsWith(File.separator)) {
            sb.append("/");
        }
        path = path.replace('\\", '/");
        try {
            sb.append(Locator.encodeURI(path));
        } catch (UnsupportedEncodingException exc) {
            throw new BuildException(exc);
        }
        if (isDir && !path.endsWith("/")) {
            sb.append('/");
        }
        return sb.toString();
    
public java.lang.StringtoVMSPath(java.io.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.

param
f The File to get the VMS path for.
return
The absolute VMS path to f.

        // format: "DEVICE:[DIR.SUBDIR]FILE"
        String osPath;
        String path = normalize(f.getAbsolutePath()).getPath();
        String name = f.getName();
        boolean isAbsolute = path.charAt(0) == File.separatorChar;
        // treat directories specified using .DIR syntax as files
        boolean isDirectory = f.isDirectory()
            && !name.regionMatches(true, name.length() - 4, ".DIR", 0, 4);

        String device = null;
        StringBuffer directory = null;
        String file = null;

        int index = 0;

        if (isAbsolute) {
            index = path.indexOf(File.separatorChar, 1);
            if (index == -1) {
                return path.substring(1) + ":[000000]";
            } else {
                device = path.substring(1, index++);
            }
        }
        if (isDirectory) {
            directory = new StringBuffer(path.substring(index).
                                         replace(File.separatorChar, '."));
        } else {
            int dirEnd =
                path.lastIndexOf(File.separatorChar, path.length());
            if (dirEnd == -1 || dirEnd < index) {
                file = path.substring(index);
            } else {
                directory = new StringBuffer(path.substring(index, dirEnd).
                                             replace(File.separatorChar, '."));
                index = dirEnd + 1;
                if (path.length() > index) {
                    file = path.substring(index);
                }
            }
        }
        if (!isAbsolute && directory != null) {
            directory.insert(0, '.");
        }
        osPath = ((device != null) ? device + ":" : "")
            + ((directory != null) ? "[" + directory + "]" : "")
            + ((file != null) ? file : "");
        return osPath;
    
public static java.lang.StringtranslatePath(java.lang.String toProcess)
Translate a path into its native (platform specific) format.

This method uses PathTokenizer to separate the input path into its components. This handles DOS style paths in a relatively sensible way. The file separators are then converted to their platform specific versions.

param
toProcess The path to be translated. May be null.
return
the native version of the specified path or an empty string if the path is null or empty.
since
ant 1.7
see
PathTokenizer

        if (toProcess == null || toProcess.length() == 0) {
            return "";
        }
        StringBuffer path = new StringBuffer(toProcess.length() + 50);
        PathTokenizer tokenizer = new PathTokenizer(toProcess);
        while (tokenizer.hasMoreTokens()) {
            String pathComponent = tokenizer.nextToken();
            pathComponent = pathComponent.replace('/", File.separatorChar);
            pathComponent = pathComponent.replace('\\", File.separatorChar);
            if (path.length() != 0) {
                path.append(File.pathSeparatorChar);
            }
            path.append(pathComponent);
        }
        return path.toString();