Package com.globalmentor.io

Class Files

  • public class Files
extends java.lang.Object
    Various constants and utilities for examining files.

    For file URIs Java incorrectly uses the form file:/mnt/sdcard/... instead of file:///mnt/sdcard/..., but these utilities use the former for consistency.

    Author:
    Garret Wilson
    See Also:
    File URIs in Windows

    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static java.io.File addExtension​(java.io.File file, java.lang.String extension)
      Adds the given extension to a file and returns the new file with the new extension.
      static java.nio.file.Path backupFile​(java.nio.file.Path path)
      Backs up a given file without a rolling policy.
      static java.nio.file.Path backupFile​(java.nio.file.Path path, long maxBackupCount)
      Backs up a given file using a rolling, numbered backup file determined by getBackupPath(Path, long).
      static java.io.File changeExtension​(java.io.File file, java.lang.String extension)
      Changes the extension of a file and returns a new file with the new extension.
      static java.io.File changeName​(java.io.File file, java.lang.String name)
      Changes the name of a file and returns a new file with the new name.
      static java.io.File checkDirectoryExists​(java.io.File directory)
      Checks to see if a given file exists as a directory, throwing an exception if not.
      static java.io.File checkFileExists​(java.io.File file)
      Checks to see if a given file exists, throwing an exception if not.
      static void copy​(java.io.File sourceFile, java.io.File destinationFile)
      Copies the given source file or directory to the given destination file or directory.
      static void copy​(java.io.File sourceFile, java.io.File destinationFile, boolean deep)
      Copies the given source file or directory to the given destination file or directory.
      static void copy​(java.io.File sourceFile, java.io.File destinationFile, boolean deep, boolean overwrite)
      Copies the given source file or directory to the given destination file or directory.
      static void copy​(java.io.File sourceFile, java.io.File destinationFile, boolean deep, boolean overwrite, ProgressListener progressListener)
      Copies the given source file or directory to the given destination file or directory.
      static void copy​(java.io.File sourceFile, java.io.File destinationFile, boolean deep, ProgressListener progressListener)
      Copies the given source file or directory to the given destination file or directory.
      static void copy​(java.io.File sourceFile, java.io.File destinationFile, boolean deep, java.io.FileFilter fileFilter)
      Copies the given source file or directory to the given destination file or directory.
      static void copy​(java.io.File sourceFile, java.io.File destinationFile, boolean deep, java.io.FileFilter fileFilter, boolean overwrite)
      Copies the given source file or directory to the given destination file or directory.
      static void copy​(java.io.File sourceFile, java.io.File destinationFile, boolean deep, java.io.FileFilter fileFilter, boolean overwrite, ProgressListener progressListener)
      Copies the given source file or directory to the given destination file or directory.
      static void copy​(java.io.File sourceFile, java.io.File destinationFile, boolean deep, java.io.FileFilter fileFilter, ProgressListener progressListener)
      Copies the given source file or directory to the given destination file or directory.
      static void copy​(java.io.File sourceFile, java.io.File destinationFile, ProgressListener progressListener)
      Copies the given source file or directory to the given destination file or directory.
      static void copy​(java.io.File file, java.io.OutputStream outputStream)
      Stores the contents of a file in an output stream.
      static void copy​(java.io.File file, java.io.OutputStream outputStream, ProgressListener progressListener)
      Stores the contents of a file in an output stream.
      static void copy​(java.io.InputStream inputStream, java.io.File file)
      Stores the contents of an input stream in a file.
      static void copy​(java.io.InputStream inputStream, java.io.File file, ProgressListener progressListener)
      Stores the contents of an input stream in a file.
      static void createNewFile​(java.io.File file)
      Creates a new file, throwing an exception if unsuccessful.
      static java.io.File createTempFile()
      Creates a temporary file in the standard temporary directory with no automatic deletion on JVM exit, using a "temp-" prefix and a "tmp" extension.
      static java.io.File createTempFile​(java.io.File file)
      Creates a temporary file for another file, with no automatic deletion on JVM exit.
      static java.io.File createTempFile​(java.lang.String baseName)
      Creates a temporary file in the standard temporary directory with no automatic deletion on JVM exit, using a "tmp" extension.
      static java.io.File createTempFile​(java.lang.String baseName, boolean deleteOnExit)
      Creates a temporary file in the standard temporary directory with optional automatic deletion, using a "tmp" extension.
      static java.io.File createTempFile​(java.lang.String baseName, java.io.File directory)
      Creates a temporary file in a given directory, using a "tmp" extension.
      static java.io.File createTempFile​(java.lang.String baseName, java.io.File directory, boolean deleteOnExit)
      Creates a temporary file in a given directory with optional automatic deletion, using a "tmp" extension.
      static java.io.File createTempFile​(java.lang.String baseName, java.lang.String extension)
      Creates a temporary file in the standard temporary directory with no automatic deletion on JVM exit.
      static java.io.File createTempFile​(java.lang.String baseName, java.lang.String extension, boolean deleteOnExit)
      Creates a temporary file in the standard temporary directory with optional automatic deletion.
      static java.io.File createTempFile​(java.lang.String baseName, java.lang.String extension, java.io.File directory, boolean deleteOnExit)
      Creates a temporary file in a given directory with optional automatic deletion.
      static void delete​(java.io.File file)
      Deletes a directory or file, throwing an exception if unsuccessful.
      static void delete​(java.io.File file, boolean recursive)
      Deprecated.
      in favor of of deleteFileTree(Path).
      static java.nio.file.Path deleteFileTree​(java.nio.file.Path fileTreeRoot)
      Recursively deletes an entire file tree.
      static java.io.File ensureDirectoryExists​(java.io.File directory)
      If the directory does not exist, creates the directory named by this abstract pathname, including any necessary but nonexistent parent directories, throwing an exception if unsuccessful.
      static boolean ensureExistsFromBackup​(java.io.File file)
      Checks to see if a particular file exists.
      static boolean ensureExistsFromBackup​(java.io.File file, java.io.File backupFile)
      Checks to see if a particular file exists.
      static java.io.File getBackupFile​(java.io.File file)
      Returns a file suitable for backup, based on the specified filename, by adding an extension for a backup file.
      static java.nio.file.Path getBackupPath​(java.nio.file.Path path)
      Determines the backup file path to use for the file at the given path without a rolling policy.
      static java.nio.file.Path getBackupPath​(java.nio.file.Path path, long maxBackupCount)
      Determines the rolling, numbered backup file path to use for the file at the given path.
      static ContentType getContentType​(java.io.File file)
      Returns the media type for the specified file based on its extension.
      static java.lang.String getExtension​(java.io.File file)
      Extracts the extension from a file.
      static ContentType getExtensionContentType​(java.lang.String fileExtension)
      Returns the media type for the specified file extension.
      static ContentType getMediaType​(java.lang.String filename)
      Returns the media type for the specified filename based on its extension.
      static java.io.File getTempFile​(java.io.File file)
      Returns a file suitable for a temporary file, based on the specified filename, by adding an extension for a temporary file.
      static java.io.File getUserDirectory()  
      static boolean isChild​(java.io.File parentFile, java.io.File file)
      Determines whether the given child file is a child of the parent file in the file system hierarchy.
      static java.io.File[] listWildcards​(java.io.File wildcardFile)
      Deprecated.
      static java.io.File[] listWildcards​(java.io.File directory, java.lang.String wildcardFilename)
      Deprecated.
      static void mkdir​(java.io.File directory)
      Creates the directory named by this abstract pathname, throwing an exception if unsuccessful.
      static void mkdirs​(java.io.File directory)
      Creates the directory named by this abstract pathname, including any necessary but nonexistent parent directories, throwing an exception if unsuccessful.
      static void move​(java.io.File sourceFile, java.io.File destinationFile)
      Moves a file to a different location, overwriting the destination file if it exists.
      static void move​(java.io.File sourceFile, java.io.File destinationFile, boolean overwrite)
      Moves a file to a different location, overwriting the destination file if it exists.
      static void move​(java.io.File sourceFile, java.io.File destinationFile, java.io.File backupFile)
      Moves a file to a different location, overwriting the destination file if it exists.
      static java.io.OutputStream newOutputStreamWithBackup​(java.nio.file.Path path, long maxBackupCount, java.nio.file.OpenOption... options)
      Opens or creates a file after first creating a backup of the file if it exists, returning an output stream that may be used to write bytes to the file.
      static java.io.OutputStream newOutputStreamWithBackup​(java.nio.file.Path path, java.nio.file.OpenOption... options)
      Opens or creates a file after first creating a backup without a rolling policy of the file if it exists, returning an output stream that may be used to write bytes to the file.
      static void read​(java.io.File file, InputStreamReadable inputStreamReadable)
      Reads the contents of the given file.
      static <T> T read​(java.io.File file, IO<T> io)
      Reads an object from a file using the given I/O support.
      static byte[] readBytes​(java.io.File file)
      Loads the contents of a file into an array of bytes.
      static java.io.File removeExtension​(java.io.File file)
      Removes the extension of a filename, if any, and returns a new file with no extension.
      static void renameTo​(java.io.File source, java.io.File destination)
      Renames the file, throwing an exception if unsuccessful.
      static <T> void sortLastModified​(java.util.List<? extends java.io.File> fileList)
      Sorts a list of files in ascending order by modified time and secondly by file name.
      static java.net.URI toURI​(java.io.File file)
      Constructs a URIs.FILE_SCHEME scheme URI that represents this abstract pathname.
      static java.net.URI toURI​(java.io.File file, boolean forceDirectoryURI)
      Constructs a URIs.FILE_SCHEME scheme URI that represents this abstract pathname.
      static void write​(java.io.File file, OutputStreamWritable outputStreamWritable)
      Writes to the given file.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • CGI_EXTENSION

        public static final java.lang.String CGI_EXTENSION
        The extension for Common Gateway Interface (CGI) files.
        See Also:
        Constant Field Values

      • DOC_EXTENSION

        public static final java.lang.String DOC_EXTENSION
        The extension for Microsoft Word files.
        See Also:
        Constant Field Values

      • ICAL_EXTENSION

        public static final java.lang.String ICAL_EXTENSION
        The extension for iCalendar files.
        See Also:
        Constant Field Values

      • JSP_EXTENSION

        public static final java.lang.String JSP_EXTENSION
        An extension for Java Server Page (JSP) files.
        See Also:
        Constant Field Values

      • PDF_EXTENSION

        public static final java.lang.String PDF_EXTENSION
        The extension for Adobe PDF files.
        See Also:
        Constant Field Values

      • VCF_EXTENSION

        public static final java.lang.String VCF_EXTENSION
        The extension for vCard files.
        See Also:
        Constant Field Values

      • WILDCARD_FILE_FILTER

        public static final java.io.FileFilter WILDCARD_FILE_FILTER
        The shared file filter that accepts all files.

      • FILE_EXTENSION_CONTENT_TYPE_MAP

        @Deprecated
public static final java.util.Map<java.lang.String,​ContentType> FILE_EXTENSION_CONTENT_TYPE_MAP
        Deprecated.
        There are many reasons why this isn't a good idea. These things change, and more may be added. This is something better managed by some larger entity or container.
        A singleton read-only map of lowercase file extensions and the corresponding content types they represent.

      • FILENAME_WILDCARD_CHARACTERS

        @Deprecated
public static final Characters FILENAME_WILDCARD_CHARACTERS
        Deprecated.
        The characters recognized as wildcards in filenames.

    • Method Detail

      • addExtension

        public static java.io.File addExtension​(java.io.File file,
                                        java.lang.String extension)
        Adds the given extension to a file and returns the new file with the new extension. The filename is not checked to see if it currently has an extension.

        This implementation requires the given file to have a parent.

        Parameters:
        file - The file to which to add an extension.
        extension - The extension to add.
        Returns:
        The file with the new extension.

      • listWildcards

        @Deprecated
public static java.io.File[] listWildcards​(java.io.File wildcardFile)
        Deprecated.
        Lists files in the given file, the filename of which which may contain wildcards.

        This implementation only recognizes the wildcard characters '*' and '?'. If these characters appear outside the filename, they will not be considered wildcards.

        Parameters:
        wildcardFile - The file, the filename of which may contain wildcards.
        Returns:
        A list of files in the given path matching the given wildcard filename.
        See Also:
        FILENAME_WILDCARD_CHARACTERS

      • listWildcards

        @Deprecated
public static java.io.File[] listWildcards​(java.io.File directory,
                                           java.lang.String wildcardFilename)
        Deprecated.
        Lists files in the given directory with the given filename, which may contain wildcards.

        This implementation only recognizes the wildcard characters '*' and '?'.

        Parameters:
        directory - The directory in which to list the files.
        wildcardFilename - The filename, which can contain wildcard characters.
        Returns:
        A list of files in the given directory with names matching the given wildcard filename.
        See Also:
        FILENAME_WILDCARD_CHARACTERS

      • createTempFile

        public static java.io.File createTempFile()
                                   throws java.io.IOException
        Creates a temporary file in the standard temporary directory with no automatic deletion on JVM exit, using a "temp-" prefix and a "tmp" extension.
        Returns:
        A new temporary file.
        Throws:
        java.io.IOException - if there is a problem creating the temporary file.
        See Also:
        File.createTempFile(String, String), TEMP_EXTENSION

      • createTempFile

        public static java.io.File createTempFile​(java.lang.String baseName)
                                   throws java.io.IOException
        Creates a temporary file in the standard temporary directory with no automatic deletion on JVM exit, using a "tmp" extension.
        Parameters:
        baseName - The base filename to be used in generating the filename.
        Returns:
        A new temporary file.
        Throws:
        java.lang.NullPointerException - if the given base name is null.
        java.lang.IllegalArgumentException - if the base name is the empty string.
        java.io.IOException - if there is a problem creating the temporary file.
        See Also:
        File.createTempFile(String, String), TEMP_EXTENSION

      • createTempFile

        public static java.io.File createTempFile​(java.lang.String baseName,
                                          java.lang.String extension)
                                   throws java.io.IOException
        Creates a temporary file in the standard temporary directory with no automatic deletion on JVM exit. This convenience method provides more intuitive parameters than File.createTempFile(String, String).
        Parameters:
        baseName - The base filename to be used in generating the filename.
        extension - The extension to use for the temporary file, or null if a default extension should be used.
        Returns:
        A new temporary file.
        Throws:
        java.lang.NullPointerException - if the given base name and/or extension is null.
        java.lang.IllegalArgumentException - if the base name is the empty string.
        java.io.IOException - if there is a problem creating the temporary file.
        See Also:
        File.createTempFile(String, String)

      • createTempFile

        public static java.io.File createTempFile​(java.lang.String baseName,
                                          boolean deleteOnExit)
                                   throws java.io.IOException
        Creates a temporary file in the standard temporary directory with optional automatic deletion, using a "tmp" extension. This convenience method provides more intuitive parameters than File.createTempFile(String, String).
        Parameters:
        baseName - The base filename to be used in generating the filename.
        deleteOnExit - Whether the file should be deleted when the JVM exits.
        Returns:
        A new temporary file.
        Throws:
        java.lang.NullPointerException - if the given base name is null.
        java.lang.IllegalArgumentException - if the base name is the empty string.
        java.io.IOException - if there is a problem creating the temporary file.
        See Also:
        File.createTempFile(String, String), File.deleteOnExit(), TEMP_EXTENSION

      • createTempFile

        public static java.io.File createTempFile​(java.lang.String baseName,
                                          java.lang.String extension,
                                          boolean deleteOnExit)
                                   throws java.io.IOException
        Creates a temporary file in the standard temporary directory with optional automatic deletion. This convenience method provides more intuitive parameters than File.createTempFile(String, String).
        Parameters:
        baseName - The base filename to be used in generating the filename.
        extension - The extension to use for the temporary file, or null if a default extension should be used.
        deleteOnExit - Whether the file should be deleted when the JVM exits.
        Returns:
        A new temporary file.
        Throws:
        java.lang.NullPointerException - if the given base name and/or extension is null.
        java.lang.IllegalArgumentException - if the base name is the empty string.
        java.io.IOException - if there is a problem creating the temporary file.
        See Also:
        File.createTempFile(String, String), File.deleteOnExit()

      • createTempFile

        public static java.io.File createTempFile​(java.io.File file)
                                   throws java.io.IOException
        Creates a temporary file for another file, with no automatic deletion on JVM exit.

        This method can be used in two different ways, based upon the given file. If the given file is a directory, a temporary file will be created within the directory with the prefix "temp-". Otherwise, if the given file is a directory and filename, a temporary file will be created in the same directory, using the given filename as a prefix.

        Parameters:
        file - The file specifying the directory and optionally a filename to serve as a base name.
        Returns:
        A new temporary file.
        Throws:
        java.lang.NullPointerException - if the given file is null.
        java.lang.IllegalArgumentException - if the given file neither is a directory nor has a parent directory; or if the file is not a directory yet has no filename.
        java.io.IOException - if there is a problem creating the temporary file.
        See Also:
        File.createTempFile(String, String, File), TEMP_PREFIX, TEMP_EXTENSION

      • createTempFile

        public static java.io.File createTempFile​(java.lang.String baseName,
                                          java.io.File directory)
                                   throws java.io.IOException
        Creates a temporary file in a given directory, using a "tmp" extension. This convenience method provides more intuitive parameters than File.createTempFile(String, String, File).
        Parameters:
        baseName - The base filename to be used in generating the filename.
        directory - The directory in which the file is to be created, or null if the default temporary-file directory is to be used.
        Returns:
        A new temporary file.
        Throws:
        java.lang.NullPointerException - if the given base name is null.
        java.lang.IllegalArgumentException - if the base name is the empty string.
        java.io.IOException - if there is a problem creating the temporary file.
        See Also:
        File.createTempFile(String, String, File), TEMP_EXTENSION

      • createTempFile

        public static java.io.File createTempFile​(java.lang.String baseName,
                                          java.io.File directory,
                                          boolean deleteOnExit)
                                   throws java.io.IOException
        Creates a temporary file in a given directory with optional automatic deletion, using a "tmp" extension. This convenience method provides more intuitive parameters than File.createTempFile(String, String, File).
        Parameters:
        baseName - The base filename to be used in generating the filename.
        directory - The directory in which the file is to be created, or null if the default temporary-file directory is to be used.
        deleteOnExit - Whether the file should be deleted when the JVM exits.
        Returns:
        A new temporary file.
        Throws:
        java.lang.NullPointerException - if the given base name is null.
        java.lang.IllegalArgumentException - if the base name is the empty string.
        java.io.IOException - if there is a problem creating the temporary file.
        See Also:
        File.createTempFile(String, String, File), File.deleteOnExit(), TEMP_EXTENSION

      • createTempFile

        public static java.io.File createTempFile​(java.lang.String baseName,
                                          java.lang.String extension,
                                          java.io.File directory,
                                          boolean deleteOnExit)
                                   throws java.io.IOException
        Creates a temporary file in a given directory with optional automatic deletion. This convenience method provides more intuitive parameters than File.createTempFile(String, String, File).
        Parameters:
        baseName - The base filename to be used in generating the filename.
        extension - The extension to use for the temporary file, or null if a default extension should be used.
        directory - The directory in which the file is to be created, or null if the default temporary-file directory is to be used.
        deleteOnExit - Whether the file should be deleted when the JVM exits.
        Returns:
        A new temporary file.
        Throws:
        java.lang.NullPointerException - if the given base name and/or extension is null.
        java.lang.IllegalArgumentException - if the base name is the empty string.
        java.io.IOException - if there is a problem creating the temporary file.
        See Also:
        File.createTempFile(String, String, File), File.deleteOnExit()

      • createNewFile

        public static void createNewFile​(java.io.File file)
                          throws java.io.IOException
        Creates a new file, throwing an exception if unsuccessful.
        Parameters:
        file - The file to create.
        Throws:
        java.io.IOException - Thrown if there is an error creating the file.

      • delete

        public static void delete​(java.io.File file)
                   throws java.io.IOException
        Deletes a directory or file, throwing an exception if unsuccessful.

        If the file does not exist, no action occurs.

        Parameters:
        file - The directory or file to delete.
        Throws:
        java.io.IOException - Thrown if there is an problem deleting any directory or file.

      • delete

        @Deprecated
public static void delete​(java.io.File file,
                          boolean recursive)
                   throws java.io.IOException
        Deprecated.
        in favor of of deleteFileTree(Path).
        Deletes a directory or file, throwing an exception if unsuccessful. The operation will stop on the first error.

        If the file does not exist, no action occurs.

        Implementation Note:
        This implementation appears to follow symbolic links.
        Parameters:
        file - The directory or file to delete. If a directory is passed, all its child files and directories will recursively be deleted if recursive is true. If a file is passed, it will be deleted normally.
        recursive - true if all child directories and files of a directory should recursively be deleted.
        Throws:
        java.io.IOException - Thrown if there is an problem deleting any directory or file.

      • getExtension

        public static java.lang.String getExtension​(java.io.File file)
        Extracts the extension from a file. Anything after the last path character ('/' or '\\') is ignored.
        Parameters:
        file - The file to examine.
        Returns:
        The extension of the file (not including '.'), or null if no extension is present.

      • getExtensionContentType

        public static ContentType getExtensionContentType​(java.lang.String fileExtension)
        Returns the media type for the specified file extension. The file extension is first converted to lowercase before an attempt is made to look up a media type.
        Parameters:
        fileExtension - The file extension, without the '.', or null if there is no extension.
        Returns:
        The default media type for the file extension, or null if no known media type is associated with this file extension.

      • changeName

        public static java.io.File changeName​(java.io.File file,
                                      java.lang.String name)
        Changes the name of a file and returns a new file with the new name.
        Parameters:
        file - The file to examine.
        name - The new name of the file.
        Returns:
        The file with the new name.
        Throws:
        java.lang.NullPointerException - if the given file and/or name is null.

      • changeExtension

        public static java.io.File changeExtension​(java.io.File file,
                                           java.lang.String extension)
        Changes the extension of a file and returns a new file with the new extension. If the file does not currently have an extension, one will be added.
        Parameters:
        file - The file to examine.
        extension - The extension to set, or null if the extension should be removed.
        Returns:
        The file with the new extension.

      • checkDirectoryExists

        public static java.io.File checkDirectoryExists​(java.io.File directory)
                                         throws java.io.FileNotFoundException
        Checks to see if a given file exists as a directory, throwing an exception if not.
        Parameters:
        directory - The file to check for existence as a directory.
        Returns:
        The given file.
        Throws:
        java.io.FileNotFoundException - if the given file does not exist or is not a directory.
        See Also:
        File.isDirectory()

      • checkFileExists

        public static java.io.File checkFileExists​(java.io.File file)
                                    throws java.io.FileNotFoundException
        Checks to see if a given file exists, throwing an exception if not.
        Parameters:
        file - The file to check for existence.
        Returns:
        The given file.
        Throws:
        java.io.FileNotFoundException - if the given file does not exist.
        See Also:
        File.exists()

      • removeExtension

        public static java.io.File removeExtension​(java.io.File file)
        Removes the extension of a filename, if any, and returns a new file with no extension. This is a convenience method that delegates to changeExtension(File, String).
        Parameters:
        file - The file to examine.
        Returns:
        The file with no extension.

      • getContentType

        public static ContentType getContentType​(java.io.File file)
        Returns the media type for the specified file based on its extension.
        Parameters:
        file - The file for which to return a media type.
        Returns:
        The default media type for the file's extension, or null if no known media type is associated with this file's extension.
        See Also:
        getExtensionContentType(String)

      • getMediaType

        public static ContentType getMediaType​(java.lang.String filename)
        Returns the media type for the specified filename based on its extension.
        Parameters:
        filename - The filename to examine.
        Returns:
        The default media type for the filename's extension, or null if no known media type is associated with this file's extension or if the filename has no extension.
        See Also:
        getExtensionContentType(String)

      • getTempFile

        public static java.io.File getTempFile​(java.io.File file)
        Returns a file suitable for a temporary file, based on the specified filename, by adding an extension for a temporary file.

        This implementation requires the given file to have a parent.

        Parameters:
        file - The file for which a temporary file should be returned.
        Returns:
        The file suitable for temporary access.
        See Also:
        TEMP_EXTENSION

      • getBackupFile

        public static java.io.File getBackupFile​(java.io.File file)
        Returns a file suitable for backup, based on the specified filename, by adding an extension for a backup file.

        This implementation requires the given file to have a parent.

        Parameters:
        file - The file for which a backup file should be returned.
        Returns:
        The file suitable for backup.
        See Also:
        BACKUP_EXTENSION

      • getUserDirectory

        public static java.io.File getUserDirectory()
                                     throws java.lang.SecurityException
        Returns:
        The user's current directory.
        Throws:
        java.lang.SecurityException - Thrown if we don't have permission to access the user's directory.
        See Also:
        System, OperatingSystem.USER_DIR_PROPERTY

      • ensureExistsFromBackup

        public static boolean ensureExistsFromBackup​(java.io.File file,
                                             java.io.File backupFile)
                                      throws java.io.IOException
        Checks to see if a particular file exists. If the file does not exist, yet a backup file exists, the backup file will be moved to the original file location. If this method returns true, there will be a file located at file.
        Parameters:
        file - The file to check for existence.
        backupFile - The file to use as a backup if the original does not exist.
        Returns:
        true if the file existed or exists now after moving the backup file, else false if neither file exists.
        Throws:
        java.io.IOException - Thrown if the backup file cannot be moved.

      • ensureExistsFromBackup

        public static boolean ensureExistsFromBackup​(java.io.File file)
                                      throws java.io.IOException
        Checks to see if a particular file exists. If the file does not exist, yet a backup file exists, the backup file will be moved to the original file location. If this method returns true, there will be a file located at file. This method automatically determines the name of the backup file.
        Parameters:
        file - The file to check for existence.
        Returns:
        true if the file existed or exists now after moving the backup file, else false if neither file exists.
        Throws:
        java.io.IOException - Thrown if the backup file cannot be moved.
        See Also:
        getBackupFile(java.io.File)

      • toURI

        public static java.net.URI toURI​(java.io.File file)
        Constructs a URIs.FILE_SCHEME scheme URI that represents this abstract pathname.

        This functions similarly to File.toURI(), except that this method always returns a true URI in which the characters all are within ranges allowed by RFC 3986, notably that non-ASCII characters are all encoded.

        In addition, the character ';' is encoded, as expected by HTTP servers such as Apache when part of the path.

        Following the examples in RFC 3986, this is guaranteed to produce only lowercase hexadecimal escape codes.

        This method may not return a URI with a trailing slash for directories that don't exist. If it is known whether the file represents a directory, toURI(File, boolean) should be used instead.

        Parameters:
        file - The file which should be converted to a URI.
        Returns:
        An absolute, hierarchical URI with non-ASCII characters encoded, with a URIs.FILE_SCHEME scheme, a path representing this abstract pathname, and undefined authority, query, and fragment components.
        Throws:
        java.lang.NullPointerException - if the given file is null.
        java.lang.SecurityException - If a required system property value cannot be accessed.
        See Also:
        File.toURI(), URIs.canonicalize(URI), URIs.PATH_CHARACTERS

      • toURI

        public static java.net.URI toURI​(java.io.File file,
                                 boolean forceDirectoryURI)
        Constructs a URIs.FILE_SCHEME scheme URI that represents this abstract pathname.

        This functions similarly to File.toURI(), except that this method always returns a true URI in which the characters all are within ranges allowed by RFC 3986, notably that non-ASCII characters are all encoded.

        In addition, the character ';' is encoded, as expected by HTTP servers such as Apache when part of the path.

        Following the examples in RFC 3986, this is guaranteed to produce only lowercase hexadecimal escape codes.

        If a directory URI is requested, the appropriate URI for a directory is returned, whether or not the directory exists. Contrast this behavior with File.toURI(), which will return a file URI without a trailing slash if the directory does not exist.

        Parameters:
        file - The file which should be converted to a URI.
        forceDirectoryURI - Whether the URI should be returned with a trailing slash, even if the file does not exist as a directory.
        Returns:
        An absolute, hierarchical URI with non-ASCII characters encoded, with a URIs.FILE_SCHEME scheme, a path representing this abstract pathname, and undefined authority, query, and fragment components.
        Throws:
        java.lang.NullPointerException - if the given file is null.
        java.lang.SecurityException - If a required system property value cannot be accessed.
        See Also:
        File.toURI(), URIs.canonicalize(URI), URIs.PATH_CHARACTERS

      • isChild

        public static boolean isChild​(java.io.File parentFile,
                              java.io.File file)
        Determines whether the given child file is a child of the parent file in the file system hierarchy. This method returns false if the files refer to the same file.

        This implementation correctly recognizes parent/child relationships on case-insensitive file systems such as that used in Windows.

        Parameters:
        parentFile - The supposed parent file.
        file - The supposed child file.
        Returns:
        true if the files share a parent/child relationship in the file system hierarchy.
        Throws:
        java.lang.NullPointerException - if the given parent file and/or child file is null.

      • mkdir

        public static void mkdir​(java.io.File directory)
                  throws java.io.IOException
        Creates the directory named by this abstract pathname, throwing an exception if unsuccessful.
        Parameters:
        directory - The directory to create.
        Throws:
        java.io.IOException - Thrown if there is an error creating the directory.

      • mkdirs

        public static void mkdirs​(java.io.File directory)
                   throws java.io.IOException
        Creates the directory named by this abstract pathname, including any necessary but nonexistent parent directories, throwing an exception if unsuccessful.
        Parameters:
        directory - The directory to create.
        Throws:
        java.io.IOException - Thrown if there is an error creating the directory.

      • ensureDirectoryExists

        public static java.io.File ensureDirectoryExists​(java.io.File directory)
                                          throws java.io.IOException
        If the directory does not exist, creates the directory named by this abstract pathname, including any necessary but nonexistent parent directories, throwing an exception if unsuccessful.
        Parameters:
        directory - The directory to create if necessary.
        Returns:
        The directory, which has been verified to exist.
        Throws:
        java.io.IOException - Thrown if there is an error creating the directory.
        See Also:
        mkdirs(File)

      • read

        public static <T> T read​(java.io.File file,
                         IO<T> io)
                  throws java.io.IOException
        Reads an object from a file using the given I/O support.
        Type Parameters:
        T - //TODO write this
        Parameters:
        file - The file from which to read.
        io - The I/O support for reading the object.
        Returns:
        The object read from the file.
        Throws:
        java.io.IOException - if there is an error reading the data.

      • read

        public static void read​(java.io.File file,
                        InputStreamReadable inputStreamReadable)
                 throws java.io.IOException
        Reads the contents of the given file.

        This is a convenience that obviates the need for boilerplate for getting an InputStream from a File.

        Parameters:
        file - The file from which the information will be read.
        inputStreamReadable - The object to read the information from the file.
        Throws:
        java.io.IOException - if there is an error loading the contents of the file.

      • write

        public static void write​(java.io.File file,
                         OutputStreamWritable outputStreamWritable)
                  throws java.io.IOException
        Writes to the given file.

        This is a convenience that obviates the need for boilerplate for getting an OutputStream to a File.

        Parameters:
        file - The file to which the information will be written.
        outputStreamWritable - The object to write the information to the file.
        Throws:
        java.io.IOException - if there is an error writing the contents to the file.

      • renameTo

        public static void renameTo​(java.io.File source,
                            java.io.File destination)
                     throws java.io.IOException
        Renames the file, throwing an exception if unsuccessful.

        This method is a direct delegation to File.renameTo(File) with added exception handling. If overwriting of a destination file is desired, use move(File, File) or a related method.

        Parameters:
        source - The file to rename.
        destination - The new name of the file
        Throws:
        java.io.IOException - Thrown if there is an error renaming the file.
        See Also:
        move(File, File)

      • move

        public static void move​(java.io.File sourceFile,
                        java.io.File destinationFile)
                 throws java.io.IOException
        Moves a file to a different location, overwriting the destination file if it exists.
        Parameters:
        sourceFile - The file to be moved.
        destinationFile - The location to where the source files should be be moved.
        Throws:
        java.io.IOException - Thrown if there is an error moving the file.

      • move

        public static void move​(java.io.File sourceFile,
                        java.io.File destinationFile,
                        boolean overwrite)
                 throws java.io.IOException
        Moves a file to a different location, overwriting the destination file if it exists.
        Parameters:
        sourceFile - The file to be moved.
        destinationFile - The location to where the source files should be be moved.
        overwrite - true if any existing file or directory at the destination should be overwritten, or false if an existing file or directory at the destination should cause an exception to be thrown.
        Throws:
        java.lang.IllegalStateException - if overwrite is turned off and a destination file exists.
        java.io.IOException - Thrown if there is an error moving the file.

      • move

        public static void move​(java.io.File sourceFile,
                        java.io.File destinationFile,
                        java.io.File backupFile)
                 throws java.io.IOException
        Moves a file to a different location, overwriting the destination file if it exists. If a backup file is specified, it is first deleted and the destination file is moved to the backup file location before the source file is moved.
        Parameters:
        sourceFile - The file to be moved.
        destinationFile - The location to where the source files should be be moved.
        backupFile - The backup file to where the destination file, if any, will first be moved, or null if no backup file is necessary.
        Throws:
        java.io.IOException - Thrown if there is an error renaming the file.

      • sortLastModified

        public static <T> void sortLastModified​(java.util.List<? extends java.io.File> fileList)
                                 throws java.io.IOException
        Sorts a list of files in ascending order by modified time and secondly by file name. This method caches file information so that each file is accessed only once.
        Type Parameters:
        T - //TODO write this
        Parameters:
        fileList - The list to be sorted.
        Throws:
        java.io.IOException - if there is an error accessing the file.
        java.lang.SecurityException - if file access is not allowed.
        java.lang.UnsupportedOperationException - if the specified list's list-iterator does not support the set operation.

      • copy

        public static void copy​(java.io.InputStream inputStream,
                        java.io.File file)
                 throws java.io.IOException
        Stores the contents of an input stream in a file.
        Parameters:
        inputStream - The source of the file contents.
        file - The destination of the file contents.
        Throws:
        java.io.IOException - Thrown if there is an error copying the information.

      • copy

        public static void copy​(java.io.InputStream inputStream,
                        java.io.File file,
                        ProgressListener progressListener)
                 throws java.io.IOException
        Stores the contents of an input stream in a file.
        Parameters:
        inputStream - The source of the file contents.
        file - The destination of the file contents.
        progressListener - A listener to be notified of progress, or null if no progress notifications is requested.
        Throws:
        java.io.IOException - Thrown if there is an error copying the information.

      • copy

        public static void copy​(java.io.File file,
                        java.io.OutputStream outputStream)
                 throws java.io.IOException
        Stores the contents of a file in an output stream.
        Parameters:
        file - The file to copy.
        outputStream - The destination of the file contents.
        Throws:
        java.io.IOException - Thrown if there is an error copying the file.

      • copy

        public static void copy​(java.io.File sourceFile,
                        java.io.File destinationFile)
                 throws java.io.IOException
        Copies the given source file or directory to the given destination file or directory. Destination files are overwritten. The last modified date of the destination file or directory is updated to match that of the source.
        Parameters:
        sourceFile - The source file or directory to copy.
        destinationFile - The destination of the copied file or directory.
        Throws:
        java.lang.NullPointerException - if the given source file and/or destination file is null.
        java.lang.IllegalArgumentException - if the given destination file is a child of the given source file, representing a circular copy.
        java.io.FileNotFoundException - if the given source file is null.
        java.lang.IllegalStateException - if a directory copy is performed and the destination file's parent directory doesn't exist.
        java.io.IOException

      • copy

        public static void copy​(java.io.File sourceFile,
                        java.io.File destinationFile,
                        ProgressListener progressListener)
                 throws java.io.IOException
        Copies the given source file or directory to the given destination file or directory. Destination files are overwritten. The last modified date of the destination file or directory is updated to match that of the source.
        Parameters:
        sourceFile - The source file or directory to copy.
        destinationFile - The destination of the copied file or directory.
        progressListener - A listener to be notified of progress, or null if no progress notifications is requested.
        Throws:
        java.lang.NullPointerException - if the given source file and/or destination file is null.
        java.lang.IllegalArgumentException - if the given destination file is a child of the given source file, representing a circular copy.
        java.io.FileNotFoundException - if the given source file is null.
        java.lang.IllegalStateException - if a directory copy is performed and the destination file's parent directory doesn't exist.
        java.io.IOException

      • copy

        public static void copy​(java.io.File sourceFile,
                        java.io.File destinationFile,
                        boolean deep)
                 throws java.io.IOException
        Copies the given source file or directory to the given destination file or directory. Destination files are overwritten. The last modified date of the destination file or directory is updated to match that of the source.
        Parameters:
        sourceFile - The source file or directory to copy.
        destinationFile - The destination of the copied file or directory.
        deep - true if child files and directories of source directories should be recursively copied.
        Throws:
        java.lang.NullPointerException - if the given source file and/or destination file is null.
        java.lang.IllegalArgumentException - if the given destination file is a child of the given source file, representing a circular copy.
        java.io.FileNotFoundException - if the given source file is null.
        java.lang.IllegalStateException - if a directory copy is performed and the destination file's parent directory doesn't exist.
        java.io.IOException

      • copy

        public static void copy​(java.io.File sourceFile,
                        java.io.File destinationFile,
                        boolean deep,
                        ProgressListener progressListener)
                 throws java.io.IOException
        Copies the given source file or directory to the given destination file or directory. Destination files are overwritten. The last modified date of the destination file or directory is updated to match that of the source.
        Parameters:
        sourceFile - The source file or directory to copy.
        destinationFile - The destination of the copied file or directory.
        deep - true if child files and directories of source directories should be recursively copied.
        progressListener - A listener to be notified of progress, or null if no progress notifications is requested.
        Throws:
        java.lang.NullPointerException - if the given source file and/or destination file is null.
        java.lang.IllegalArgumentException - if the given destination file is a child of the given source file, representing a circular copy.
        java.io.FileNotFoundException - if the given source file is null.
        java.lang.IllegalStateException - if a directory copy is performed and the destination file's parent directory doesn't exist.
        java.io.IOException

      • copy

        public static void copy​(java.io.File sourceFile,
                        java.io.File destinationFile,
                        boolean deep,
                        boolean overwrite)
                 throws java.io.IOException
        Copies the given source file or directory to the given destination file or directory. The last modified date of the destination file or directory is updated to match that of the source.
        Parameters:
        sourceFile - The source file or directory to copy.
        destinationFile - The destination of the copied file or directory.
        deep - true if child files and directories of source directories should be recursively copied.
        overwrite - true if any existing file or directory at the destination should be overwritten.
        Throws:
        java.lang.NullPointerException - if the given source file and/or destination file is null.
        java.lang.IllegalArgumentException - if the given destination file is a child of the given source file, representing a circular copy.
        java.io.FileNotFoundException - if the given source file is null.
        java.lang.IllegalStateException - if a directory copy is performed and the destination file's parent directory doesn't exist.
        java.lang.IllegalStateException - if overwrite is turned off and a destination file exists.
        java.io.IOException

      • copy

        public static void copy​(java.io.File sourceFile,
                        java.io.File destinationFile,
                        boolean deep,
                        boolean overwrite,
                        ProgressListener progressListener)
                 throws java.io.IOException
        Copies the given source file or directory to the given destination file or directory. The last modified date of the destination file or directory is updated to match that of the source.
        Parameters:
        sourceFile - The source file or directory to copy.
        destinationFile - The destination of the copied file or directory.
        deep - true if child files and directories of source directories should be recursively copied.
        overwrite - true if any existing file or directory at the destination should be overwritten, or false if an existing file or directory at the destination should cause an exception to be thrown.
        progressListener - A listener to be notified of progress, or null if no progress notifications is requested.
        Throws:
        java.lang.NullPointerException - if the given source file and/or destination file is null.
        java.lang.IllegalArgumentException - if the given destination file is a child of the given source file, representing a circular copy.
        java.io.FileNotFoundException - if the given source file is null.
        java.lang.IllegalStateException - if a directory copy is performed and the destination file's parent directory doesn't exist.
        java.lang.IllegalStateException - if overwrite is turned off and a destination file exists.
        java.io.IOException

      • copy

        public static void copy​(java.io.File file,
                        java.io.OutputStream outputStream,
                        ProgressListener progressListener)
                 throws java.io.IOException
        Stores the contents of a file in an output stream.
        Parameters:
        file - The file to copy.
        outputStream - The destination of the file contents.
        progressListener - A listener to be notified of progress, or null if no progress notifications is requested.
        Throws:
        java.io.IOException - Thrown if there is an error copying the file.

      • copy

        public static void copy​(java.io.File sourceFile,
                        java.io.File destinationFile,
                        boolean deep,
                        java.io.FileFilter fileFilter)
                 throws java.io.IOException
        Copies the given source file or directory to the given destination file or directory. Destination files are overwritten. The last modified date of the destination file or directory is updated to match that of the source.
        Parameters:
        sourceFile - The source file or directory to copy.
        destinationFile - The destination of the copied file or directory.
        deep - true if child files and directories of source directories should be recursively copied.
        fileFilter - The file filter for copying children files if applicable.
        Throws:
        java.lang.NullPointerException - if the given source file and/or destination file is null, or if deep copying of a directory is requested and the given file filter is null.
        java.lang.IllegalArgumentException - if the given destination file is a child of the given source file, representing a circular copy.
        java.io.FileNotFoundException - if the given source file is null.
        java.lang.IllegalStateException - if a directory copy is performed and the destination file's parent directory doesn't exist.
        java.io.IOException

      • copy

        public static void copy​(java.io.File sourceFile,
                        java.io.File destinationFile,
                        boolean deep,
                        java.io.FileFilter fileFilter,
                        ProgressListener progressListener)
                 throws java.io.IOException
        Copies the given source file or directory to the given destination file or directory. Destination files are overwritten. The last modified date of the destination file or directory is updated to match that of the source.
        Parameters:
        sourceFile - The source file or directory to copy.
        destinationFile - The destination of the copied file or directory.
        deep - true if child files and directories of source directories should be recursively copied.
        fileFilter - The file filter for copying children files if applicable.
        progressListener - A listener to be notified of progress, or null if no progress notifications is requested.
        Throws:
        java.lang.NullPointerException - if the given source file and/or destination file is null, or if deep copying of a directory is requested and the given file filter is null.
        java.lang.IllegalArgumentException - if the given destination file is a child of the given source file, representing a circular copy.
        java.io.FileNotFoundException - if the given source file is null.
        java.lang.IllegalStateException - if a directory copy is performed and the destination file's parent directory doesn't exist.
        java.io.IOException

      • copy

        public static void copy​(java.io.File sourceFile,
                        java.io.File destinationFile,
                        boolean deep,
                        java.io.FileFilter fileFilter,
                        boolean overwrite)
                 throws java.io.IOException
        Copies the given source file or directory to the given destination file or directory. The last modified date of the destination file or directory is updated to match that of the source.
        Parameters:
        sourceFile - The source file or directory to copy.
        destinationFile - The destination of the copied file or directory.
        deep - true if child files and directories of source directories should be recursively copied.
        fileFilter - The file filter for copying children files if applicable.
        overwrite - true if any existing file or directory at the destination should be overwritten, or false if an existing file or directory at the destination should cause an exception to be thrown.
        Throws:
        java.lang.NullPointerException - if the given source file and/or destination file is null, or if deep copying of a directory is requested and the given file filter is null.
        java.lang.IllegalArgumentException - if the given destination file is a child of the given source file, representing a circular copy.
        java.io.FileNotFoundException - if the given source file is null.
        java.lang.IllegalStateException - if a directory copy is performed and the destination file's parent directory doesn't exist.
        java.lang.IllegalStateException - if overwrite is turned off and a destination file exists.
        java.io.IOException

      • copy

        public static void copy​(java.io.File sourceFile,
                        java.io.File destinationFile,
                        boolean deep,
                        java.io.FileFilter fileFilter,
                        boolean overwrite,
                        ProgressListener progressListener)
                 throws java.io.IOException
        Copies the given source file or directory to the given destination file or directory. The last modified date of the destination file or directory is updated to match that of the source.
        Parameters:
        sourceFile - The source file or directory to copy.
        destinationFile - The destination of the copied file or directory.
        deep - true if child files and directories of source directories should be recursively copied.
        fileFilter - The file filter for copying children files if applicable.
        overwrite - true if any existing file or directory at the destination should be overwritten, or false if an existing file or directory at the destination should cause an exception to be thrown.
        progressListener - A listener to be notified of progress, or null if no progress notifications is requested.
        Throws:
        java.lang.NullPointerException - if the given source file and/or destination file is null, or if deep copying of a directory is requested and the given file filter is null.
        java.lang.IllegalArgumentException - if the given destination file is a child of the given source file, representing a circular copy.
        java.io.FileNotFoundException - if the given source file is null.
        java.lang.IllegalStateException - if a directory copy is performed and the destination file's parent directory doesn't exist.
        java.lang.IllegalStateException - if overwrite is turned off and a destination file exists.
        java.io.IOException

      • deleteFileTree

        public static java.nio.file.Path deleteFileTree​(@Nonnull
                                                java.nio.file.Path fileTreeRoot)
                                         throws java.io.IOException
        Recursively deletes an entire file tree. Symbolic links are deleted, not followed.
        Implementation Specification:
        This implementation uses Files.walkFileTree(Path, FileVisitor).
        Implementation Note:
        This implementation was inspired by Java 7: Deleting a Directory by Walking the File Tree.
        Parameters:
        fileTreeRoot - The root of the file tree to delete.
        Returns:
        The given file tree root, which will have been deleted.
        Throws:
        java.lang.SecurityException - if the security manager denies access to the starting file.
        java.io.IOException - if an I/O error is thrown while deleting the tree.

      • getBackupPath

        public static java.nio.file.Path getBackupPath​(@Nonnull
                                               java.nio.file.Path path)
        Determines the backup file path to use for the file at the given path without a rolling policy. The backup file will be in the same directory as the given path; and the filename will be in the form filename.ext.bak, i.e. with a bak extension added. This is a convenience method that delegates to getBackupPath(Path, long) with the value 1 for maxBackupCount.
        Parameters:
        path - The path of the file to back up.
        Returns:
        The path to the backup file to use.

      • getBackupPath

        public static java.nio.file.Path getBackupPath​(@Nonnull
                                               java.nio.file.Path path,
                                               @Nonnegative
                                               long maxBackupCount)
        Determines the rolling, numbered backup file path to use for the file at the given path. The backup file will be in the same directory as the given path; and the filename is determined in the following manner:
        1. If maxBackupCount is 1, the backup filename will be in the form filename.ext.bak, i.e. with a bak extension added.
        2. If maxBackupCount is greater than 1, the backup filename will be in the form filename.ext.1.bak, i.e. with a 1.bak extension added.
        Parameters:
        path - The path of the file to back up.
        maxBackupCount - The maximum number of rolling backup files to use.
        Returns:
        The path to the backup file to use.
        Throws:
        java.lang.IllegalArgumentException - if maxBackupCount is zero or negative.

      • backupFile

        public static java.nio.file.Path backupFile​(@Nonnull
                                            java.nio.file.Path path)
                                     throws java.io.IOException
        Backs up a given file without a rolling policy. If the backup filename does not exist, the indicated file will simply be copied to the backup file destination. If the backup file destination exists, it will be overwritten. This is a convenience method that delegates to backupFile(Path, long) with the value 1 for maxBackupCount.
        Parameters:
        path - The path of the file to back up.
        Returns:
        The path to the backup file used.
        Throws:
        java.lang.IllegalArgumentException - if maxBackupCount is zero or negative.
        java.io.IOException - If an error occurs while rolling the backup files.
        See Also:
        backupFile(Path, long)

      • backupFile

        public static java.nio.file.Path backupFile​(@Nonnull
                                            java.nio.file.Path path,
                                            @Nonnegative
                                            long maxBackupCount)
                                     throws java.io.IOException
        Backs up a given file using a rolling, numbered backup file determined by getBackupPath(Path, long). If the backup filename does not exist, the indicated file will simply be copied to the backup file destination. If maxBackupCount is 1 and the backup file destination exists, it will be overwritten. If maxBackupCount is greater than 1 and the backup file destination exists, filename.ext.maxBackupCount.bak will be deleted (if it exists) and each backup file filename.ext.number.bak in the sequence will be renamed to filename.ext.number+1.bak (if it exists) down to and including 1, and then the indicated file will be copied to the backup filename, which is filename.ext.1.bak.

        If it's a rolling backup and one of the backup files are manually erased, the blank space that will be left between them will be rolled aswell, until the blank space take the place of number maxBackupCount and then disappears.

        Parameters:
        path - The path of the file to back up.
        maxBackupCount - The maximum number of rolling backup files to use.
        Returns:
        The path to the backup file used.
        Throws:
        java.lang.IllegalArgumentException - if maxBackupCount is zero or negative.
        java.io.IOException - If an error occurs while rolling the backup files.

      • newOutputStreamWithBackup

        public static java.io.OutputStream newOutputStreamWithBackup​(@Nonnull
                                                             java.nio.file.Path path,
                                                             java.nio.file.OpenOption... options)
                                                      throws java.io.IOException
        Opens or creates a file after first creating a backup without a rolling policy of the file if it exists, returning an output stream that may be used to write bytes to the file. The maximum number of backups used on this method will be 1. This is a convenience method that delegates to newOutputStreamWithBackup(Path, long, OpenOption...) with the value 1 for maxBackupCount.
        Parameters:
        path - The path of the file to back up.
        options - The options specifying how the file is opened.
        Returns:
        The new OutputStream after the creation of a backup for the given file.
        Throws:
        java.lang.IllegalArgumentException - if maxBackupCount is negative.
        java.io.IOException - If an error occurs while creating the backup file.
        See Also:
        newOutputStreamWithBackup(Path, long, OpenOption...)

      • newOutputStreamWithBackup

        public static java.io.OutputStream newOutputStreamWithBackup​(@Nonnull
                                                             java.nio.file.Path path,
                                                             @Nonnegative
                                                             long maxBackupCount,
                                                             java.nio.file.OpenOption... options)
                                                      throws java.io.IOException
        Opens or creates a file after first creating a backup of the file if it exists, returning an output stream that may be used to write bytes to the file. If maxBackupCount is greater than zero, a backup will first be created using backupFile(Path, long).
        Parameters:
        path - The path of the file to back up.
        maxBackupCount - The maximum number of rolling backup files to use.
        options - The options specifying how the file is opened.
        Returns:
        The new OutputStream after the creation of a backup for the given file.
        Throws:
        java.lang.IllegalArgumentException - if maxBackupCount is negative.
        java.io.IOException - If an error occurs while creating the backup file.