Class FileUtils


  • public class FileUtils
    extends java.lang.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.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected FileUtils()
      Empty constructor.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      boolean areSame​(java.io.File f1, java.io.File f2)
      Are the two File instances pointing to the same object on the file system?
      static void close​(java.io.InputStream device)
      Close a stream without throwing any exception if something went wrong.
      static void close​(java.io.OutputStream device)
      Close a stream without throwing any exception if something went wrong.
      static void close​(java.io.Reader device)
      Close a Reader without throwing any exception if something went wrong.
      static void close​(java.io.Writer device)
      Close a Writer without throwing any exception if something went wrong.
      static void close​(java.lang.AutoCloseable ac)
      Close an AutoCloseable without throwing any exception if something went wrong.
      static void close​(java.net.URLConnection conn)
      Closes an URLConnection if its concrete implementation provides a way to close it that Ant knows of.
      static void close​(java.nio.channels.Channel device)
      Close a Channel without throwing any exception if something went wrong.
      boolean contentEquals​(java.io.File f1, java.io.File f2)
      Compares the contents of two files.
      boolean contentEquals​(java.io.File f1, java.io.File f2, boolean textfile)
      Compares the contents of two files.
      void copyFile​(java.io.File sourceFile, java.io.File destFile)
      Convenience method to copy a file from a source to a destination.
      void copyFile​(java.io.File sourceFile, java.io.File destFile, FilterSetCollection filters)
      Convenience method to copy a file from a source to a destination specifying if token filtering must be used.
      void copyFile​(java.io.File sourceFile, java.io.File destFile, 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.
      void copyFile​(java.io.File sourceFile, java.io.File destFile, 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.
      void copyFile​(java.io.File sourceFile, java.io.File destFile, 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.
      void copyFile​(java.io.File sourceFile, java.io.File destFile, FilterSetCollection filters, java.util.Vector<FilterChain> filterChains, boolean overwrite, boolean preserveLastModified, boolean append, java.lang.String inputEncoding, java.lang.String outputEncoding, 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.
      void copyFile​(java.io.File sourceFile, java.io.File destFile, FilterSetCollection filters, java.util.Vector<FilterChain> filterChains, boolean overwrite, boolean preserveLastModified, boolean append, java.lang.String inputEncoding, java.lang.String outputEncoding, Project project, boolean force)
      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.
      void copyFile​(java.io.File sourceFile, java.io.File destFile, FilterSetCollection filters, java.util.Vector<FilterChain> filterChains, boolean overwrite, boolean preserveLastModified, java.lang.String inputEncoding, java.lang.String outputEncoding, 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.
      void copyFile​(java.io.File sourceFile, java.io.File destFile, FilterSetCollection filters, java.util.Vector<FilterChain> filterChains, boolean overwrite, boolean preserveLastModified, java.lang.String encoding, 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.
      void copyFile​(java.lang.String sourceFile, java.lang.String destFile)
      Convenience method to copy a file from a source to a destination.
      void copyFile​(java.lang.String sourceFile, java.lang.String destFile, FilterSetCollection filters)
      Convenience method to copy a file from a source to a destination specifying if token filtering must be used.
      void copyFile​(java.lang.String sourceFile, java.lang.String destFile, 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.
      void copyFile​(java.lang.String sourceFile, java.lang.String destFile, 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.
      void copyFile​(java.lang.String sourceFile, java.lang.String destFile, 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.
      void copyFile​(java.lang.String sourceFile, java.lang.String destFile, FilterSetCollection filters, java.util.Vector<FilterChain> filterChains, boolean overwrite, boolean preserveLastModified, java.lang.String inputEncoding, java.lang.String outputEncoding, 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.
      void copyFile​(java.lang.String sourceFile, java.lang.String destFile, FilterSetCollection filters, java.util.Vector<FilterChain> filterChains, boolean overwrite, boolean preserveLastModified, java.lang.String encoding, 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.
      boolean createNewFile​(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).
      boolean createNewFile​(java.io.File f, boolean mkdirs)
      Create a new file, optionally creating parent directories.
      java.io.File createTempFile​(java.lang.String prefix, java.lang.String suffix, java.io.File parentDir)
      Deprecated.
      since ant 1.7.1 use createTempFile(Project, String, String, File, boolean, boolean) instead.
      java.io.File createTempFile​(java.lang.String prefix, java.lang.String suffix, java.io.File parentDir, boolean deleteOnExit)
      Deprecated.
      since ant 1.7.1 use createTempFile(Project, String, String, File, boolean, boolean) instead.
      java.io.File createTempFile​(java.lang.String prefix, java.lang.String suffix, java.io.File parentDir, boolean deleteOnExit, boolean createFile)
      Deprecated.
      since Ant 1.10.8 use createTempFile(Project, String, String, File, boolean, boolean) instead.
      java.io.File createTempFile​(Project project, java.lang.String prefix, java.lang.String suffix, java.io.File parentDir, boolean deleteOnExit, boolean createFile)
      Create a temporary file in a given directory.
      static void delete​(java.io.File file)
      Delete the file with File.delete() if the argument is not null.
      java.lang.String[] dissect​(java.lang.String path)
      Dissect the specified absolute path.
      boolean fileNameEquals​(java.io.File f1, java.io.File f2)
      Compares two filenames.
      java.lang.String fromURI​(java.lang.String uri)
      Constructs a file path from a file: URI.
      java.lang.String getDefaultEncoding()
      Get the default encoding.
      long getFileTimestampGranularity()
      Get the granularity of file timestamps.
      java.net.URL getFileURL​(java.io.File file)
      Get the URL for a file taking into account # characters.
      static FileUtils getFileUtils()
      Method to retrieve The FileUtils, which is shared by all users of this method.
      java.io.File getParentFile​(java.io.File f)
      Deprecated.
      since 1.7.
      static java.lang.String getPath​(java.util.List<java.lang.String> pathStack)
      Gets path from a List of Strings.
      static java.lang.String getPath​(java.util.List<java.lang.String> pathStack, char separatorChar)
      Gets path from a List of Strings.
      static java.lang.String[] getPathStack​(java.lang.String path)
      Gets all names of the path as an array of Strings.
      static java.lang.String getRelativePath​(java.io.File fromFile, java.io.File toFile)
      Calculates the relative path between two files.
      boolean hasErrorInCase​(java.io.File localFile)
      test whether a file or directory exists, with an error in the upper/lower case spelling of the name.
      static boolean isAbsolutePath​(java.lang.String filename)
      Verifies that the specified filename represents an absolute path.
      static java.util.Optional<java.lang.Boolean> isCaseSensitiveFileSystem​(java.nio.file.Path path)
      Tries to determine the case sensitivity of the filesystem corresponding to the path.
      static boolean isContextRelativePath​(java.lang.String filename)
      On DOS and NetWare, the evaluation of certain file specifications is context-dependent.
      boolean isLeadingPath​(java.io.File leading, java.io.File path)
      Learn whether one path "leads" another.
      boolean isLeadingPath​(java.io.File leading, java.io.File path, boolean resolveSymlinks)
      Learn whether one path "leads" another.
      boolean isSymbolicLink​(java.io.File parent, java.lang.String name)
      Deprecated.
      use Files.isSymbolicLink(Path) instead
      boolean isUpToDate​(long sourceTime, long destTime)
      Compare two timestamps for being up to date using the current granularity.
      boolean isUpToDate​(long sourceTime, long destTime, long granularity)
      Compare two timestamps for being up to date using the specified granularity.
      boolean isUpToDate​(java.io.File source, java.io.File dest)
      Returns true if the source is older than the dest.
      boolean isUpToDate​(java.io.File source, java.io.File dest, long granularity)
      Returns true if the source is older than the dest.
      static FileUtils newFileUtils()
      Deprecated.
      since 1.7.
      static java.io.OutputStream newOutputStream​(java.nio.file.Path path, boolean append)
      Opens a new OutputStream for the given Path.
      java.io.File normalize​(java.lang.String path)
      "Normalize" the given absolute path.
      static java.lang.String readFully​(java.io.Reader rdr)
      Read from reader till EOF.
      static java.lang.String readFully​(java.io.Reader rdr, int bufferSize)
      Read from reader till EOF.
      java.lang.String removeLeadingPath​(java.io.File leading, java.io.File path)
      Removes a leading path from a second path.
      void rename​(java.io.File from, java.io.File to)
      Renames a file, even if that involves crossing file system boundaries.
      java.io.File resolveFile​(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.
      static java.lang.String safeReadFully​(java.io.Reader reader)
      Safe read fully - do not return a null for an empty reader.
      void setFileLastModified​(java.io.File file, long time)
      Calls File.setLastModified(long time).
      java.lang.String toURI​(java.lang.String path)
      Constructs a file: URI that represents the external form of the given pathname.
      java.lang.String toVMSPath​(java.io.File f)
      Returns a VMS String representation of a File object.
      static java.lang.String translatePath​(java.lang.String toProcess)
      Translate a path into its native (platform specific) format.
      boolean tryHardToDelete​(java.io.File f)
      Accommodate Windows bug encountered in both Sun and IBM JDKs.
      boolean tryHardToDelete​(java.io.File f, boolean runGC)
      If delete does not work, call System.gc() if asked to, wait a little and try again.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • FAT_FILE_TIMESTAMP_GRANULARITY

        public static final long FAT_FILE_TIMESTAMP_GRANULARITY
        The granularity of timestamps under FAT.
        See Also:
        Constant Field Values
      • UNIX_FILE_TIMESTAMP_GRANULARITY

        public static final long UNIX_FILE_TIMESTAMP_GRANULARITY
        The granularity of timestamps under Unix.
        See Also:
        Constant Field Values
      • NTFS_FILE_TIMESTAMP_GRANULARITY

        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.
        See Also:
        Constant Field Values
    • Constructor Detail

      • FileUtils

        protected FileUtils()
        Empty constructor.
    • Method Detail

      • newFileUtils

        @Deprecated
        public static FileUtils newFileUtils()
        Deprecated.
        since 1.7. Use getFileUtils instead, FileUtils do not have state.
        Factory method.
        Returns:
        a new instance of FileUtils.
      • getFileUtils

        public static FileUtils getFileUtils()
        Method to retrieve The FileUtils, which is shared by all users of this method.
        Returns:
        an instance of FileUtils.
        Since:
        Ant 1.6.3
      • getFileURL

        public java.net.URL getFileURL​(java.io.File file)
                                throws java.net.MalformedURLException
        Get the URL for a file taking into account # characters.
        Parameters:
        file - the file whose URL representation is required.
        Returns:
        The FileURL value.
        Throws:
        java.net.MalformedURLException - if the URL representation cannot be formed.
      • copyFile

        public void copyFile​(java.lang.String sourceFile,
                             java.lang.String destFile)
                      throws java.io.IOException
        Convenience 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.
        Throws:
        java.io.IOException - if the copying fails.
      • copyFile

        public void copyFile​(java.lang.String sourceFile,
                             java.lang.String destFile,
                             FilterSetCollection filters)
                      throws java.io.IOException
        Convenience 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.
        Throws:
        java.io.IOException - if the copying fails.
      • copyFile

        public void copyFile​(java.lang.String sourceFile,
                             java.lang.String destFile,
                             FilterSetCollection filters,
                             boolean overwrite)
                      throws java.io.IOException
        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.
        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.
        Throws:
        java.io.IOException - if the copying fails.
      • copyFile

        public void copyFile​(java.lang.String sourceFile,
                             java.lang.String destFile,
                             FilterSetCollection filters,
                             boolean overwrite,
                             boolean preserveLastModified)
                      throws java.io.IOException
        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.
        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.
        Throws:
        java.io.IOException - if the copying fails.
      • copyFile

        public void copyFile​(java.lang.String sourceFile,
                             java.lang.String destFile,
                             FilterSetCollection filters,
                             boolean overwrite,
                             boolean preserveLastModified,
                             java.lang.String encoding)
                      throws java.io.IOException
        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.
        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.
        Throws:
        java.io.IOException - if the copying fails.
        Since:
        Ant 1.5
      • copyFile

        public void copyFile​(java.lang.String sourceFile,
                             java.lang.String destFile,
                             FilterSetCollection filters,
                             java.util.Vector<FilterChain> filterChains,
                             boolean overwrite,
                             boolean preserveLastModified,
                             java.lang.String encoding,
                             Project project)
                      throws java.io.IOException
        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.
        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.
        Throws:
        java.io.IOException - if the copying fails.
        Since:
        Ant 1.5
      • copyFile

        public void copyFile​(java.lang.String sourceFile,
                             java.lang.String destFile,
                             FilterSetCollection filters,
                             java.util.Vector<FilterChain> filterChains,
                             boolean overwrite,
                             boolean preserveLastModified,
                             java.lang.String inputEncoding,
                             java.lang.String outputEncoding,
                             Project project)
                      throws java.io.IOException
        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.
        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.
        Throws:
        java.io.IOException - if the copying fails.
        Since:
        Ant 1.6
      • copyFile

        public void copyFile​(java.io.File sourceFile,
                             java.io.File destFile)
                      throws java.io.IOException
        Convenience 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.
        Throws:
        java.io.IOException - if the copying fails.
      • copyFile

        public void copyFile​(java.io.File sourceFile,
                             java.io.File destFile,
                             FilterSetCollection filters)
                      throws java.io.IOException
        Convenience 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.
        Throws:
        java.io.IOException - if the copying fails.
      • copyFile

        public void copyFile​(java.io.File sourceFile,
                             java.io.File destFile,
                             FilterSetCollection filters,
                             boolean overwrite)
                      throws java.io.IOException
        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.
        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.
        Throws:
        java.io.IOException - if the copying fails.
      • copyFile

        public void copyFile​(java.io.File sourceFile,
                             java.io.File destFile,
                             FilterSetCollection filters,
                             boolean overwrite,
                             boolean preserveLastModified)
                      throws java.io.IOException
        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.
        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.
        Throws:
        java.io.IOException - if the copying fails.
      • copyFile

        public void copyFile​(java.io.File sourceFile,
                             java.io.File destFile,
                             FilterSetCollection filters,
                             boolean overwrite,
                             boolean preserveLastModified,
                             java.lang.String encoding)
                      throws java.io.IOException
        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.
        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.
        Throws:
        java.io.IOException - if the copying fails.
        Since:
        Ant 1.5
      • copyFile

        public void copyFile​(java.io.File sourceFile,
                             java.io.File destFile,
                             FilterSetCollection filters,
                             java.util.Vector<FilterChain> filterChains,
                             boolean overwrite,
                             boolean preserveLastModified,
                             java.lang.String encoding,
                             Project project)
                      throws java.io.IOException
        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.
        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.
        Throws:
        java.io.IOException - if the copying fails.
        Since:
        Ant 1.5
      • copyFile

        public void copyFile​(java.io.File sourceFile,
                             java.io.File destFile,
                             FilterSetCollection filters,
                             java.util.Vector<FilterChain> filterChains,
                             boolean overwrite,
                             boolean preserveLastModified,
                             java.lang.String inputEncoding,
                             java.lang.String outputEncoding,
                             Project project)
                      throws java.io.IOException
        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.
        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.
        Throws:
        java.io.IOException - if the copying fails.
        Since:
        Ant 1.6
      • copyFile

        public void copyFile​(java.io.File sourceFile,
                             java.io.File destFile,
                             FilterSetCollection filters,
                             java.util.Vector<FilterChain> filterChains,
                             boolean overwrite,
                             boolean preserveLastModified,
                             boolean append,
                             java.lang.String inputEncoding,
                             java.lang.String outputEncoding,
                             Project project)
                      throws java.io.IOException
        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.
        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.
        append - whether to append to the destination file.
        inputEncoding - the encoding used to read the files.
        outputEncoding - the encoding used to write the files.
        project - the project instance.
        Throws:
        java.io.IOException - if the copying fails.
        Since:
        Ant 1.8
      • copyFile

        public void copyFile​(java.io.File sourceFile,
                             java.io.File destFile,
                             FilterSetCollection filters,
                             java.util.Vector<FilterChain> filterChains,
                             boolean overwrite,
                             boolean preserveLastModified,
                             boolean append,
                             java.lang.String inputEncoding,
                             java.lang.String outputEncoding,
                             Project project,
                             boolean force)
                      throws java.io.IOException
        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.
        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.
        append - whether to append to the destination file.
        inputEncoding - the encoding used to read the files.
        outputEncoding - the encoding used to write the files.
        project - the project instance.
        force - whether to overwrite read-only destination files.
        Throws:
        java.io.IOException - if the copying fails.
        Since:
        Ant 1.8.2
      • setFileLastModified

        public void setFileLastModified​(java.io.File file,
                                        long time)
        Calls File.setLastModified(long time). Originally written to to dynamically bind to that call on Java1.2+.
        Parameters:
        file - the file whose modified time is to be set
        time - the time to which the last modified time is to be set. if this is -1, the current time is used.
      • resolveFile

        public java.io.File resolveFile​(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.
        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).getAbsoluteFile().
        filename - a file name.
        Returns:
        an absolute file.
        Throws:
        java.lang.NullPointerException - if filename is null.
      • isContextRelativePath

        public static boolean isContextRelativePath​(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).
        Parameters:
        filename - the filename to evaluate.
        Returns:
        true if the filename is relative to system context.
        Throws:
        java.lang.NullPointerException - if filename is null.
        Since:
        Ant 1.7
      • isAbsolutePath

        public static boolean isAbsolutePath​(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.
        Parameters:
        filename - the filename to be checked.
        Returns:
        true if the filename represents an absolute path.
        Throws:
        java.lang.NullPointerException - if filename is null.
        Since:
        Ant 1.6.3
      • translatePath

        public static java.lang.String translatePath​(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.

        Parameters:
        toProcess - The path to be translated. May be null.
        Returns:
        the native version of the specified path or an empty string if the path is null or empty.
        Since:
        ant 1.7
        See Also:
        PathTokenizer
      • normalize

        public java.io.File normalize​(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 File.getCanonicalPath() this method specifically does not resolve symbolic links.

        If the path tries to go beyond the file system root (i.e. it contains more ".." segments than can be travelled up) the method will return the original path unchanged.

        Parameters:
        path - the path to be normalized.
        Returns:
        the normalized version of the path.
        Throws:
        java.lang.NullPointerException - if path is null.
      • dissect

        public java.lang.String[] dissect​(java.lang.String path)
        Dissect the specified absolute path.
        Parameters:
        path - the path to dissect.
        Returns:
        String[] {root, remaining path}.
        Throws:
        java.lang.NullPointerException - if path is null.
        Since:
        Ant 1.7
      • toVMSPath

        public java.lang.String toVMSPath​(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.
        Parameters:
        f - The File to get the VMS path for.
        Returns:
        The absolute VMS path to f.
      • createTempFile

        @Deprecated
        public java.io.File createTempFile​(java.lang.String prefix,
                                           java.lang.String suffix,
                                           java.io.File parentDir)
        Deprecated.
        since ant 1.7.1 use createTempFile(Project, String, String, File, boolean, boolean) instead.
        Create a File object for a temporary file in a given directory. Without actually creating the file.

        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.

        If the filesystem where the temporary file is created supports POSIX permissions, the file will only be readable and writable by the current user.

        Parameters:
        prefix - file name prefix.
        suffix - file extension; include the '.'.
        parentDir - Directory to create the temporary file in; java.io.tmpdir used if not specified.
        Returns:
        a File reference to the new, nonexistent temporary file.
      • createTempFile

        @Deprecated
        public java.io.File createTempFile​(java.lang.String prefix,
                                           java.lang.String suffix,
                                           java.io.File parentDir,
                                           boolean deleteOnExit,
                                           boolean createFile)
        Deprecated.
        since Ant 1.10.8 use createTempFile(Project, String, String, File, boolean, boolean) instead.
        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.

        If the filesystem where the temporary file is created supports POSIX permissions, the file will only be readable and writable by the current user.

        Parameters:
        prefix - file name prefix.
        suffix - file extension; include the '.'.
        parentDir - Directory to create the temporary file in; java.io.tmpdir used if not specified.
        deleteOnExit - whether to set the tempfile for deletion on normal VM exit.
        createFile - true if the file must actually be created. If false chances exist that a file with the same name is created in the time between invoking this method and the moment the file is actually created. If possible set to true.
        Returns:
        a File reference to the new temporary file.
        Since:
        Ant 1.7.1
      • createTempFile

        public java.io.File createTempFile​(Project project,
                                           java.lang.String prefix,
                                           java.lang.String suffix,
                                           java.io.File parentDir,
                                           boolean deleteOnExit,
                                           boolean createFile)
        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.

        If the filesystem where the temporary file is created supports POSIX permissions, the file will only be readable and writable by the current user.

        Parameters:
        project - reference to the current Ant project.
        prefix - file name prefix.
        suffix - file extension; include the '.'.
        parentDir - Directory to create the temporary file in; if not specified and project is not null then the value of the property ant.tmpdir is used if set; otherwise java.io.tmpdir is used.
        deleteOnExit - whether to set the tempfile for deletion on normal VM exit.
        createFile - true if the file must actually be created. If false chances exist that a file with the same name is created in the time between invoking this method and the moment the file is actually created. If possible set to true.
        Returns:
        a File reference to the new temporary file.
        Since:
        Ant 1.9.15
      • createTempFile

        @Deprecated
        public java.io.File createTempFile​(java.lang.String prefix,
                                           java.lang.String suffix,
                                           java.io.File parentDir,
                                           boolean deleteOnExit)
        Deprecated.
        since ant 1.7.1 use createTempFile(Project, String, String, File, boolean, boolean) instead.
        Create a File object for a temporary file in a given directory. Without actually creating the file.

        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.

        If the filesystem where the temporary file is created supports POSIX permissions, the file will only be readable and writable by the current user.

        Parameters:
        prefix - file name prefix.
        suffix - file extension; include the '.'.
        parentDir - Directory to create the temporary file in; java.io.tmpdir used if not specified.
        deleteOnExit - whether to set the tempfile for deletion on normal VM exit.
        Returns:
        a File reference to the new, nonexistent temporary file.
      • contentEquals

        public boolean contentEquals​(java.io.File f1,
                                     java.io.File f2)
                              throws java.io.IOException
        Compares the contents of two files.
        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.
        Throws:
        java.io.IOException - if the files cannot be read.
      • contentEquals

        public boolean contentEquals​(java.io.File f1,
                                     java.io.File f2,
                                     boolean textfile)
                              throws java.io.IOException
        Compares the contents of two files.
        Parameters:
        f1 - the file whose content is to be compared.
        f2 - the other file whose content is to be compared.
        textfile - true if the file is to be treated as a text file and differences in kind of line break are to be ignored.
        Returns:
        true if the content of the files is the same.
        Throws:
        java.io.IOException - if the files cannot be read.
        Since:
        Ant 1.6.3
      • getParentFile

        @Deprecated
        public java.io.File getParentFile​(java.io.File f)
        Deprecated.
        since 1.7. Just use File.getParentFile() directly.
        This was originally an emulation of File.getParentFile() for JDK 1.1, but it is now implemented using that method (Ant 1.6.3 onwards).
        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
      • readFully

        public static java.lang.String readFully​(java.io.Reader rdr)
                                          throws java.io.IOException
        Read from reader till EOF.
        Parameters:
        rdr - the reader from which to read.
        Returns:
        the contents read out of the given reader.
        Throws:
        java.io.IOException - if the contents could not be read out from the reader.
      • readFully

        public static java.lang.String readFully​(java.io.Reader rdr,
                                                 int bufferSize)
                                          throws java.io.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.
        Throws:
        java.io.IOException - if the contents could not be read out from the reader.
      • safeReadFully

        public static java.lang.String safeReadFully​(java.io.Reader reader)
                                              throws java.io.IOException
        Safe read fully - do not return a null for an empty reader.
        Parameters:
        reader - the input to read from.
        Returns:
        the string.
        Throws:
        java.io.IOException - if unable to read from reader.
        Since:
        Ant 1.7.1
      • createNewFile

        public boolean createNewFile​(java.io.File f)
                              throws java.io.IOException
        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.

        Parameters:
        f - the file to be created.
        Returns:
        true if the file did not exist already.
        Throws:
        java.io.IOException - on error.
        Since:
        Ant 1.5
      • createNewFile

        public boolean createNewFile​(java.io.File f,
                                     boolean mkdirs)
                              throws java.io.IOException
        Create a new file, optionally creating parent directories.
        Parameters:
        f - the file to be created.
        mkdirs - boolean whether to create parent directories.
        Returns:
        true if the file did not exist already.
        Throws:
        java.io.IOException - on error.
        Since:
        Ant 1.6.3
      • isSymbolicLink

        @Deprecated
        public boolean isSymbolicLink​(java.io.File parent,
                                      java.lang.String name)
                               throws java.io.IOException
        Deprecated.
        use Files.isSymbolicLink(Path) instead
        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.
        Throws:
        java.io.IOException - on error.
        Since:
        Ant 1.5
      • removeLeadingPath

        public java.lang.String removeLeadingPath​(java.io.File leading,
                                                  java.io.File path)
        Removes a leading path from a second path.

        This method uses normalize(java.lang.String) under the covers and does not resolve symbolic links.

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

        public boolean isLeadingPath​(java.io.File leading,
                                     java.io.File path)
        Learn whether one path "leads" another.

        This method uses normalize(java.lang.String) under the covers and does not resolve symbolic links.

        If either path tries to go beyond the file system root (i.e. it contains more ".." segments than can be travelled up) the method will return false.

        Parameters:
        leading - The leading path, must not be null, must be absolute.
        path - The path to check, must not be null, must be absolute.
        Returns:
        true if path starts with leading; false otherwise.
        Since:
        Ant 1.7
      • isLeadingPath

        public boolean isLeadingPath​(java.io.File leading,
                                     java.io.File path,
                                     boolean resolveSymlinks)
                              throws java.io.IOException
        Learn whether one path "leads" another.
        Parameters:
        leading - The leading path, must not be null, must be absolute.
        path - The path to check, must not be null, must be absolute.
        resolveSymlinks - whether symbolic links shall be resolved prior to comparing the paths.
        Returns:
        true if path starts with leading; false otherwise.
        Throws:
        java.io.IOException - if resolveSymlinks is true and invoking getCanonicaPath on either argument throws an exception
        Since:
        Ant 1.10.5
      • toURI

        public java.lang.String toURI​(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.
        Parameters:
        path - the path in the local file system.
        Returns:
        the URI version of the local path.
        Since:
        Ant 1.6
      • fromURI

        public java.lang.String fromURI​(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.

        Parameters:
        uri - the URI designating a file in the local filesystem.
        Returns:
        the local file system path for the file.
        Since:
        Ant 1.6
      • fileNameEquals

        public boolean fileNameEquals​(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.

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

        public boolean areSame​(java.io.File f1,
                               java.io.File f2)
                        throws java.io.IOException
        Are the two File instances pointing to the same object on the file system?
        Parameters:
        f1 - File
        f2 - File
        Returns:
        boolean
        Throws:
        java.io.IOException - if file name canonicalization fails
        Since:
        Ant 1.8.2
      • rename

        public void rename​(java.io.File from,
                           java.io.File to)
                    throws java.io.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.
        Throws:
        java.io.IOException - if anything bad happens during this process. Note that to may have been deleted already when this happens.
        Since:
        Ant 1.6
      • getFileTimestampGranularity

        public long getFileTimestampGranularity()
        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.
        Returns:
        the difference, in milliseconds, which two file timestamps must have in order for the two files to be considered to have different timestamps.
      • hasErrorInCase

        public boolean hasErrorInCase​(java.io.File localFile)
        test whether a file or directory exists, with an error in the upper/lower case spelling of the name. Using this method is only interesting on case insensitive file systems (Windows).

        It will return true only if 3 conditions are met:

        • operating system is case insensitive
        • file exists
        • actual name from directory reading is different from the supplied argument

        The purpose is to identify files or directories on case-insensitive filesystems whose case is not what is expected.

        Possibly to rename them afterwards to the desired upper/lowercase combination.
        Parameters:
        localFile - file to test
        Returns:
        true if the file exists and the case of the actual file is not the case of the parameter
        Since:
        Ant 1.7.1
      • isUpToDate

        public boolean isUpToDate​(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.
        Parameters:
        source - source file (should be the older).
        dest - dest file (should be the newer).
        granularity - an offset added to the source time.
        Returns:
        true if the source is older than the dest after accounting for granularity.
        Since:
        Ant 1.6.3
      • isUpToDate

        public boolean isUpToDate​(java.io.File source,
                                  java.io.File dest)
        Returns true if the source is older than the dest.
        Parameters:
        source - source file (should be the older).
        dest - dest file (should be the newer).
        Returns:
        true if the source is older than the dest, taking the granularity into account.
        Since:
        Ant 1.6.3
      • isUpToDate

        public boolean isUpToDate​(long sourceTime,
                                  long destTime,
                                  long granularity)
        Compare two timestamps for being up to date using the specified granularity.
        Parameters:
        sourceTime - timestamp of source file.
        destTime - timestamp of dest file.
        granularity - os/filesys granularity.
        Returns:
        true if the dest file is considered up to date.
      • isUpToDate

        public boolean isUpToDate​(long sourceTime,
                                  long destTime)
        Compare two timestamps for being up to date using the current granularity.
        Parameters:
        sourceTime - timestamp of source file.
        destTime - timestamp of dest file.
        Returns:
        true if the dest file is considered up to date.
      • close

        public static void close​(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.
        Parameters:
        device - output writer, can be null.
      • close

        public static void close​(java.io.Reader device)
        Close a Reader without throwing any exception if something went wrong. Do not attempt to close it if the argument is null.
        Parameters:
        device - Reader, can be null.
      • close

        public static void close​(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.
        Parameters:
        device - stream, can be null.
      • close

        public static void close​(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.
        Parameters:
        device - stream, can be null.
      • close

        public static void close​(java.nio.channels.Channel device)
        Close a Channel without throwing any exception if something went wrong. Do not attempt to close it if the argument is null.
        Parameters:
        device - channel, can be null.
        Since:
        Ant 1.8.0
      • close

        public static void close​(java.net.URLConnection conn)
        Closes an URLConnection if its concrete implementation provides a way to close it that Ant knows of.
        Parameters:
        conn - connection, can be null
        Since:
        Ant 1.8.0
      • close

        public static void close​(java.lang.AutoCloseable ac)
        Close an AutoCloseable without throwing any exception if something went wrong. Do not attempt to close it if the argument is null.
        Parameters:
        ac - AutoCloseable, can be null.
        Since:
        Ant 1.10.0
      • delete

        public static void delete​(java.io.File file)
        Delete the file with File.delete() if the argument is not null. Do nothing on a null argument.
        Parameters:
        file - file to delete.
      • tryHardToDelete

        public boolean tryHardToDelete​(java.io.File f)
        Accommodate Windows bug encountered in both Sun and IBM JDKs. Others possible. If the delete does not work, call System.gc(), wait a little and try again.
        Parameters:
        f - File
        Returns:
        whether deletion was successful
        Since:
        Ant 1.8.0
      • tryHardToDelete

        public boolean tryHardToDelete​(java.io.File f,
                                       boolean runGC)
        If delete does not work, call System.gc() if asked to, wait a little and try again.
        Parameters:
        f - File
        runGC - boolean
        Returns:
        whether deletion was successful
        Since:
        Ant 1.8.3
      • getRelativePath

        public static java.lang.String getRelativePath​(java.io.File fromFile,
                                                       java.io.File toFile)
                                                throws java.lang.Exception
        Calculates the relative path between two files.

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

        Parameters:
        fromFile - the File to calculate the path from
        toFile - the File to calculate the path to
        Returns:
        the relative path between the files
        Throws:
        java.lang.Exception - for undocumented reasons
        Since:
        Ant 1.7
        See Also:
        File.getCanonicalPath()
      • getPathStack

        public static java.lang.String[] getPathStack​(java.lang.String path)
        Gets all names of the path as an array of Strings.
        Parameters:
        path - to get names from
        Returns:
        Strings, never null
        Since:
        Ant 1.7
      • getPath

        public static java.lang.String getPath​(java.util.List<java.lang.String> pathStack)
        Gets path from a List of Strings.
        Parameters:
        pathStack - List of Strings to be concatenated as a path.
        Returns:
        String, never null
        Since:
        Ant 1.7
      • getPath

        public static java.lang.String getPath​(java.util.List<java.lang.String> pathStack,
                                               char separatorChar)
        Gets path from a List of Strings.
        Parameters:
        pathStack - List of Strings to be concatenated as a path.
        separatorChar - char to be used as separator between names in path
        Returns:
        String, never null
        Since:
        Ant 1.7
      • getDefaultEncoding

        public java.lang.String getDefaultEncoding()
        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.
        Returns:
        the default file encoding.
      • newOutputStream

        public static java.io.OutputStream newOutputStream​(java.nio.file.Path path,
                                                           boolean append)
                                                    throws java.io.IOException
        Opens a new OutputStream for the given Path.
        Parameters:
        path - the path of the file
        append - whether to append to or a replace an existing file
        Returns:
        a stream ready to write to the file
        Throws:
        java.io.IOException - if stream creation fails
        Since:
        Ant 1.10.2
      • isCaseSensitiveFileSystem

        public static java.util.Optional<java.lang.Boolean> isCaseSensitiveFileSystem​(java.nio.file.Path path)
        Tries to determine the case sensitivity of the filesystem corresponding to the path. While doing so, this method might create a temporary file under the directory represented by the path, if it's a directory or in the parent directory of the path, if it's a file.

        This method works on a best effort basis and will return an Optional.empty() if it cannot determine the case sensitivity, either due to exception or for any other reason.

        Parameters:
        path - The path whose filesystem case sensitivity needs to be checked
        Returns:
        Returns true if the filesystem corresponding to the passed path is case sensitive. Else returns false. If the case sensitivity cannot be determined for whatever reason, this method returns an Optional.empty()
        Throws:
        java.lang.IllegalArgumentException - If the passed path is null
        Since:
        Ant 1.10.6