Class Files


  • @Beta
    public final class Files
    extends Object
    Provides utility methods for working with files.

    All method parameters must be non-null unless documented otherwise.

    Since:
    1.0
    • Method Detail

      • newReader

        public static BufferedReader newReader​(File file,
                                               Charset charset)
                                        throws FileNotFoundException
        Returns a buffered reader that reads from a file using the given character set.
        Parameters:
        file - the file to read from
        charset - the charset used to decode the input stream; see Charsets for helpful predefined constants
        Returns:
        the buffered reader
        Throws:
        FileNotFoundException
      • newWriter

        public static BufferedWriter newWriter​(File file,
                                               Charset charset)
                                        throws FileNotFoundException
        Returns a buffered writer that writes to a file using the given character set.
        Parameters:
        file - the file to write to
        charset - the charset used to encode the output stream; see Charsets for helpful predefined constants
        Returns:
        the buffered writer
        Throws:
        FileNotFoundException
      • asByteSource

        public static ByteSource asByteSource​(File file)
        Returns a new ByteSource for reading bytes from the given file.
        Since:
        14.0
      • asByteSink

        public static ByteSink asByteSink​(File file,
                                          FileWriteMode... modes)
        Returns a new ByteSink for writing bytes to the given file. The given modes control how the file is opened for writing. When no mode is provided, the file will be truncated before writing. When the APPEND mode is provided, writes will append to the end of the file without truncating it.
        Since:
        14.0
      • asCharSource

        public static CharSource asCharSource​(File file,
                                              Charset charset)
        Returns a new CharSource for reading character data from the given file using the given character set.
        Since:
        14.0
      • asCharSink

        public static CharSink asCharSink​(File file,
                                          Charset charset,
                                          FileWriteMode... modes)
        Returns a new CharSink for writing character data to the given file using the given character set. The given modes control how the file is opened for writing. When no mode is provided, the file will be truncated before writing. When the APPEND mode is provided, writes will append to the end of the file without truncating it.
        Since:
        14.0
      • newInputStreamSupplier

        public static InputSupplier<FileInputStream> newInputStreamSupplier​(File file)
        Returns a factory that will supply instances of FileInputStream that read from a file.
        Parameters:
        file - the file to read from
        Returns:
        the factory
      • newOutputStreamSupplier

        public static OutputSupplier<FileOutputStream> newOutputStreamSupplier​(File file)
        Returns a factory that will supply instances of FileOutputStream that write to a file.
        Parameters:
        file - the file to write to
        Returns:
        the factory
      • newOutputStreamSupplier

        public static OutputSupplier<FileOutputStream> newOutputStreamSupplier​(File file,
                                                                               boolean append)
        Returns a factory that will supply instances of FileOutputStream that write to or append to a file.
        Parameters:
        file - the file to write to
        append - if true, the encoded characters will be appended to the file; otherwise the file is overwritten
        Returns:
        the factory
      • newReaderSupplier

        public static InputSupplier<InputStreamReader> newReaderSupplier​(File file,
                                                                         Charset charset)
        Returns a factory that will supply instances of InputStreamReader that read a file using the given character set.
        Parameters:
        file - the file to read from
        charset - the charset used to decode the input stream; see Charsets for helpful predefined constants
        Returns:
        the factory
      • newWriterSupplier

        public static OutputSupplier<OutputStreamWriter> newWriterSupplier​(File file,
                                                                           Charset charset)
        Returns a factory that will supply instances of OutputStreamWriter that write to a file using the given character set.
        Parameters:
        file - the file to write to
        charset - the charset used to encode the output stream; see Charsets for helpful predefined constants
        Returns:
        the factory
      • newWriterSupplier

        public static OutputSupplier<OutputStreamWriter> newWriterSupplier​(File file,
                                                                           Charset charset,
                                                                           boolean append)
        Returns a factory that will supply instances of OutputStreamWriter that write to or append to a file using the given character set.
        Parameters:
        file - the file to write to
        charset - the charset used to encode the output stream; see Charsets for helpful predefined constants
        append - if true, the encoded characters will be appended to the file; otherwise the file is overwritten
        Returns:
        the factory
      • toByteArray

        public static byte[] toByteArray​(File file)
                                  throws IOException
        Reads all bytes from a file into a byte array.
        Parameters:
        file - the file to read from
        Returns:
        a byte array containing all the bytes from file
        Throws:
        IllegalArgumentException - if the file is bigger than the largest possible byte array (2^31 - 1)
        IOException - if an I/O error occurs
      • toString

        public static String toString​(File file,
                                      Charset charset)
                               throws IOException
        Reads all characters from a file into a String, using the given character set.
        Parameters:
        file - the file to read from
        charset - the charset used to decode the input stream; see Charsets for helpful predefined constants
        Returns:
        a string containing all the characters from the file
        Throws:
        IOException - if an I/O error occurs
      • write

        public static void write​(byte[] from,
                                 File to)
                          throws IOException
        Overwrites a file with the contents of a byte array.
        Parameters:
        from - the bytes to write
        to - the destination file
        Throws:
        IOException - if an I/O error occurs
      • copy

        public static void copy​(File from,
                                OutputStream to)
                         throws IOException
        Copies all bytes from a file to an output stream.
        Parameters:
        from - the source file
        to - the output stream
        Throws:
        IOException - if an I/O error occurs
      • copy

        public static void copy​(File from,
                                File to)
                         throws IOException
        Copies all the bytes from one file to another.

        Warning: If to represents an existing file, that file will be overwritten with the contents of from. If to and from refer to the same file, the contents of that file will be deleted.

        Parameters:
        from - the source file
        to - the destination file
        Throws:
        IOException - if an I/O error occurs
        IllegalArgumentException - if from.equals(to)
      • copy

        public static <R extends Readable & Closeable> void copy​(InputSupplier<R> from,
                                                                 File to,
                                                                 Charset charset)
                                                          throws IOException
        Copies to a file all characters from a Readable and Closeable object supplied by a factory, using the given character set.
        Parameters:
        from - the readable supplier
        to - the destination file
        charset - the charset used to encode the output stream; see Charsets for helpful predefined constants
        Throws:
        IOException - if an I/O error occurs
      • write

        public static void write​(CharSequence from,
                                 File to,
                                 Charset charset)
                          throws IOException
        Writes a character sequence (such as a string) to a file using the given character set.
        Parameters:
        from - the character sequence to write
        to - the destination file
        charset - the charset used to encode the output stream; see Charsets for helpful predefined constants
        Throws:
        IOException - if an I/O error occurs
      • append

        public static void append​(CharSequence from,
                                  File to,
                                  Charset charset)
                           throws IOException
        Appends a character sequence (such as a string) to a file using the given character set.
        Parameters:
        from - the character sequence to append
        to - the destination file
        charset - the charset used to encode the output stream; see Charsets for helpful predefined constants
        Throws:
        IOException - if an I/O error occurs
      • copy

        public static <W extends Appendable & Closeable> void copy​(File from,
                                                                   Charset charset,
                                                                   OutputSupplier<W> to)
                                                            throws IOException
        Copies all characters from a file to a Appendable & Closeable object supplied by a factory, using the given character set.
        Parameters:
        from - the source file
        charset - the charset used to decode the input stream; see Charsets for helpful predefined constants
        to - the appendable supplier
        Throws:
        IOException - if an I/O error occurs
      • copy

        public static void copy​(File from,
                                Charset charset,
                                Appendable to)
                         throws IOException
        Copies all characters from a file to an appendable object, using the given character set.
        Parameters:
        from - the source file
        charset - the charset used to decode the input stream; see Charsets for helpful predefined constants
        to - the appendable object
        Throws:
        IOException - if an I/O error occurs
      • equal

        public static boolean equal​(File file1,
                                    File file2)
                             throws IOException
        Returns true if the files contains the same bytes.
        Throws:
        IOException - if an I/O error occurs
      • createTempDir

        public static File createTempDir()
        Atomically creates a new directory somewhere beneath the system's temporary directory (as defined by the java.io.tmpdir system property), and returns its name.

        Use this method instead of File.createTempFile(String, String) when you wish to create a directory, not a regular file. A common pitfall is to call createTempFile, delete the file and create a directory in its place, but this leads a race condition which can be exploited to create security vulnerabilities, especially when executable files are to be written into the directory.

        This method assumes that the temporary volume is writable, has free inodes and free blocks, and that it will not be called thousands of times per second.

        Returns:
        the newly-created directory
        Throws:
        IllegalStateException - if the directory could not be created
      • touch

        public static void touch​(File file)
                          throws IOException
        Creates an empty file or updates the last updated timestamp on the same as the unix command of the same name.
        Parameters:
        file - the file to create or update
        Throws:
        IOException - if an I/O error occurs
      • createParentDirs

        public static void createParentDirs​(File file)
                                     throws IOException
        Creates any necessary but nonexistent parent directories of the specified file. Note that if this operation fails it may have succeeded in creating some (but not all) of the necessary parent directories.
        Throws:
        IOException - if an I/O error occurs, or if any necessary but nonexistent parent directories of the specified file could not be created.
        Since:
        4.0
      • move

        public static void move​(File from,
                                File to)
                         throws IOException
        Moves the file from one path to another. This method can rename a file or move it to a different directory, like the Unix mv command.
        Parameters:
        from - the source file
        to - the destination file
        Throws:
        IOException - if an I/O error occurs
        IllegalArgumentException - if from.equals(to)
      • readFirstLine

        public static String readFirstLine​(File file,
                                           Charset charset)
                                    throws IOException
        Reads the first line from a file. The line does not include line-termination characters, but does include other leading and trailing whitespace.
        Parameters:
        file - the file to read from
        charset - the charset used to decode the input stream; see Charsets for helpful predefined constants
        Returns:
        the first line, or null if the file is empty
        Throws:
        IOException - if an I/O error occurs
      • readLines

        public static List<String> readLines​(File file,
                                             Charset charset)
                                      throws IOException
        Reads all of the lines from a file. The lines do not include line-termination characters, but do include other leading and trailing whitespace.

        This method returns a mutable List. For an ImmutableList, use Files.asCharSource(file, charset).readLines().

        Parameters:
        file - the file to read from
        charset - the charset used to decode the input stream; see Charsets for helpful predefined constants
        Returns:
        a mutable List containing all the lines
        Throws:
        IOException - if an I/O error occurs
      • readLines

        public static <T> T readLines​(File file,
                                      Charset charset,
                                      LineProcessor<T> callback)
                               throws IOException
        Streams lines from a File, stopping when our callback returns false, or we have read all of the lines.
        Parameters:
        file - the file to read from
        charset - the charset used to decode the input stream; see Charsets for helpful predefined constants
        callback - the LineProcessor to use to handle the lines
        Returns:
        the output of processing the lines
        Throws:
        IOException - if an I/O error occurs
      • readBytes

        public static <T> T readBytes​(File file,
                                      ByteProcessor<T> processor)
                               throws IOException
        Process the bytes of a file.

        (If this seems too complicated, maybe you're looking for toByteArray(java.io.File).)

        Parameters:
        file - the file to read
        processor - the object to which the bytes of the file are passed.
        Returns:
        the result of the byte processor
        Throws:
        IOException - if an I/O error occurs
      • hash

        public static HashCode hash​(File file,
                                    HashFunction hashFunction)
                             throws IOException
        Computes the hash code of the file using hashFunction.
        Parameters:
        file - the file to read
        hashFunction - the hash function to use to hash the data
        Returns:
        the HashCode of all of the bytes in the file
        Throws:
        IOException - if an I/O error occurs
        Since:
        12.0
      • simplifyPath

        public static String simplifyPath​(String pathname)
        Returns the lexically cleaned form of the path name, usually (but not always) equivalent to the original. The following heuristics are used:
        • empty string becomes .
        • . stays as .
        • fold out ./
        • fold out ../ when possible
        • collapse multiple slashes
        • delete trailing slashes (unless the path is just "/")

        These heuristics do not always match the behavior of the filesystem. In particular, consider the path a/../b, which simplifyPath will change to b. If a is a symlink to x, a/../b may refer to a sibling of x, rather than the sibling of a referred to by b.

        Since:
        11.0
      • getFileExtension

        public static String getFileExtension​(String fullName)
        Returns the file extension for the given file name, or the empty string if the file has no extension. The result does not include the '.'.
        Since:
        11.0
      • getNameWithoutExtension

        public static String getNameWithoutExtension​(String file)
        Returns the file name without its file extension or path. This is similar to the basename unix command. The result does not include the '.'.
        Parameters:
        file - The name of the file to trim the extension from. This can be either a fully qualified file name (including a path) or just a file name.
        Returns:
        The file name without its path or extension.
        Since:
        14.0
      • fileTreeTraverser

        public static TreeTraverser<File> fileTreeTraverser()
        Returns a TreeTraverser instance for File trees.

        Warning: File provides no support for symbolic links, and as such there is no way to ensure that a symbolic link to a directory is not followed when traversing the tree. In this case, iterables created by this traverser could contain files that are outside of the given directory or even be infinite if there is a symbolic link loop.

        Since:
        15.0
      • isFile

        public static Predicate<File> isFile()
        Returns a predicate that returns the result of File.isFile() on input files.
        Since:
        15.0