Class Files

java.lang.Object
com.google.common.io.Files
@GwtIncompatible public final class Files extends Object
Provides utility methods for working with files.

Path users will find similar utilities in MoreFiles and the JDK's Files class.

Since:
1.0
Author:
Chris Nokleberg, Colin Decker

  • Method Details

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

      Path equivalent: Files.newBufferedReader(java.nio.file.Path, Charset).

      Parameters:
      file - the file to read from
      charset - the charset used to decode the input stream; see StandardCharsets 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.

      Path equivalent: Files.newBufferedWriter(java.nio.file.Path, Charset, java.nio.file.OpenOption...).

      Parameters:
      file - the file to write to
      charset - the charset used to encode the output stream; see StandardCharsets 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

    • toByteArray

      public static byte[] toByteArray(File file) throws IOException
      Reads all bytes from a file into a byte array.

      Path equivalent: Files.readAllBytes(java.nio.file.Path).

      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

      @Deprecated @InlineMe(replacement="Files.asCharSource(file, charset).read()", imports="com.google.common.io.Files") public static String toString(File file, Charset charset) throws IOException
      Deprecated.
      Prefer asCharSource(file, charset).read().
      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 StandardCharsets 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.

      Path equivalent: Files.write(java.nio.file.Path, byte[], java.nio.file.OpenOption...).

      Parameters:
      from - the bytes to write
      to - the destination file
      Throws:
      IOException - if an I/O error occurs

    • write

      @Deprecated @InlineMe(replacement="Files.asCharSink(to, charset).write(from)", imports="com.google.common.io.Files") public static void write(CharSequence from, File to, Charset charset) throws IOException
      Deprecated.
      Prefer asCharSink(to, charset).write(from).
      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 StandardCharsets for helpful predefined constants
      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.

      Path equivalent: Files.copy(java.nio.file.Path, OutputStream).

      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.

      Copying is not an atomic operation - in the case of an I/O error, power loss, process termination, or other problems, to may not be a complete copy of from. If you need to guard against those conditions, you should employ other file-level synchronization.

      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.

      Path equivalent: Files.copy(java.nio.file.Path, java.nio.file.Path, java.nio.file.CopyOption...).

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

    • copy

      @Deprecated @InlineMe(replacement="Files.asCharSource(from, charset).copyTo(to)", imports="com.google.common.io.Files") public static void copy(File from, Charset charset, Appendable to) throws IOException
      Deprecated.
      Prefer asCharSource(from, charset).copyTo(to).
      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 StandardCharsets for helpful predefined constants
      to - the appendable object
      Throws:
      IOException - if an I/O error occurs

    • append

      @Deprecated @InlineMe(replacement="Files.asCharSink(to, charset, FileWriteMode.APPEND).write(from)", imports={"com.google.common.io.FileWriteMode","com.google.common.io.Files"}) public static void append(CharSequence from, File to, Charset charset) throws IOException
      Deprecated.
      Prefer asCharSink(to, charset, FileWriteMode.APPEND).write(from). This method is scheduled to be removed in October 2019.
      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 StandardCharsets for helpful predefined constants
      Throws:
      IOException - if an I/O error occurs

    • equal

      public static boolean equal(File file1, File file2) throws IOException
      Returns true if the given files exist, are not directories, and contain the same bytes.
      Throws:
      IOException - if an I/O error occurs

    • createTempDir

      @Beta @Deprecated @J2ObjCIncompatible public static File createTempDir()
      Deprecated.
      For Android users, see the Data and File Storage overview to select an appropriate temporary directory (perhaps context.getCacheDir()), and create your own directory under that. (For example, you might use new File(context.getCacheDir(), "directoryname").mkdir(), or, if you need an arbitrary number of temporary directories, you might have to generate multiple directory names in a loop until mkdir() returns true.) For JRE users, prefer Files.createTempDirectory(java.nio.file.Path, java.lang.String, java.nio.file.attribute.FileAttribute<?>...), transforming it to a File using toFile() if needed. To restrict permissions as this method does, pass PosixFilePermissions.asFileAttribute(PosixFilePermissions.fromString("rwx------")) to your call to createTempDirectory.
      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.

      The temporary directory is created with permissions restricted to the current user or, in the case of Android, the current app. If that is not possible (as is the case under the very old Android Ice Cream Sandwich release), then this method throws an exception instead of creating a directory that would be more accessible. (This behavior is new in Guava 32.0.0. Previous versions would create a directory that is more accessible, as discussed in CVE-2020-8908.)

      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.

      Path equivalent: Files.createTempDirectory(java.nio.file.Path, java.lang.String, java.nio.file.attribute.FileAttribute<?>...).

      Returns:
      the newly-created directory
      Throws:
      IllegalStateException - if the directory could not be created, such as if the system does not support creating temporary directories securely

    • 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 a file from one path to another. This method can rename a file and/or move it to a different directory. In either case to must be the target path for the file itself; not just the new name for the file or the path to the new parent directory.

      Path equivalent: Files.move(java.nio.file.Path, java.nio.file.Path, java.nio.file.CopyOption...).

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

    • readFirstLine

      @Deprecated @InlineMe(replacement="Files.asCharSource(file, charset).readFirstLine()", imports="com.google.common.io.Files") public static @Nullable String readFirstLine(File file, Charset charset) throws IOException
      Deprecated.
      Prefer asCharSource(file, charset).readFirstLine().
      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 StandardCharsets 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().

      Path equivalent: Files.readAllLines(java.nio.file.Path, Charset).

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

    • readLines

      @Deprecated @InlineMe(replacement="Files.asCharSource(file, charset).readLines(callback)", imports="com.google.common.io.Files") @CanIgnoreReturnValue public static <T extends @Nullable Object> T readLines(File file, Charset charset, LineProcessor<T> callback) throws IOException
      Deprecated.
      Prefer asCharSource(file, charset).readLines(callback).
      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 StandardCharsets 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

      @Deprecated @InlineMe(replacement="Files.asByteSource(file).read(processor)", imports="com.google.common.io.Files") @CanIgnoreReturnValue public static <T extends @Nullable Object> T readBytes(File file, ByteProcessor<T> processor) throws IOException
      Deprecated.
      Prefer asByteSource(file).read(processor).
      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

      @Deprecated @InlineMe(replacement="Files.asByteSource(file).hash(hashFunction)", imports="com.google.common.io.Files") public static HashCode hash(File file, HashFunction hashFunction) throws IOException
      Deprecated.
      Prefer asByteSource(file).hash(hashFunction).
      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

    • map

      public static MappedByteBuffer map(File file) throws IOException
      Fully maps a file read-only in to memory as per FileChannel.map(java.nio.channels.FileChannel.MapMode, long, long).

      Files are mapped from offset 0 to its length.

      This only works for files ≤ Integer.MAX_VALUE bytes.

      Parameters:
      file - the file to map
      Returns:
      a read-only buffer reflecting file
      Throws:
      FileNotFoundException - if the file does not exist
      IOException - if an I/O error occurs
      Since:
      2.0
      See Also:

    • map

      public static MappedByteBuffer map(File file, FileChannel.MapMode mode) throws IOException
      Fully maps a file in to memory as per FileChannel.map(java.nio.channels.FileChannel.MapMode, long, long) using the requested FileChannel.MapMode.

      Files are mapped from offset 0 to its length.

      This only works for files ≤ Integer.MAX_VALUE bytes.

      Parameters:
      file - the file to map
      mode - the mode to use when mapping file
      Returns:
      a buffer reflecting file
      Throws:
      FileNotFoundException - if the file does not exist
      IOException - if an I/O error occurs
      Since:
      2.0
      See Also:

    • map

      public static MappedByteBuffer map(File file, FileChannel.MapMode mode, long size) throws IOException
      Maps a file in to memory as per FileChannel.map(java.nio.channels.FileChannel.MapMode, long, long) using the requested FileChannel.MapMode.

      Files are mapped from offset 0 to size.

      If the mode is FileChannel.MapMode.READ_WRITE and the file does not exist, it will be created with the requested size. Thus this method is useful for creating memory mapped files which do not yet exist.

      This only works for files ≤ Integer.MAX_VALUE bytes.

      Parameters:
      file - the file to map
      mode - the mode to use when mapping file
      Returns:
      a buffer reflecting file
      Throws:
      IOException - if an I/O error occurs
      Since:
      2.0
      See Also:

    • 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 '.'.

      Note: This method simply returns everything after the last '.' in the file's name as determined by File.getName(). It does not account for any filesystem-specific behavior that the File API does not already account for. For example, on NTFS it will report "txt" as the extension for the filename "foo.exe:.txt" even though NTFS will drop the ":.txt" part of the name when the file is actually created on the filesystem due to NTFS's Alternate Data Streams.

      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

    • fileTraverser

      public static Traverser<File> fileTraverser()
      Returns a Traverser instance for the file and directory tree. The returned traverser starts from a File and will return all files and directories it encounters.

      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.

      If available, consider using MoreFiles.fileTraverser() instead. It behaves the same except that it doesn't follow symbolic links and returns Path instances.

      If the File passed to one of the Traverser methods does not exist or is not a directory, no exception will be thrown and the returned Iterable will contain a single element: that file.

      Example: Files.fileTraverser().depthFirstPreOrder(new File("/")) may return files with the following paths: ["/", "/etc", "/etc/config.txt", "/etc/fonts", "/home", "/home/alice", ...]

      Since:
      23.5

    • isDirectory

      public static Predicate<File> isDirectory()
      Returns a predicate that returns the result of File.isDirectory() on input files.
      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