com.google.common.io

Class Files

java.lang.Object

com.google.common.io.Files

@Beta
 @GwtIncompatible
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

Author:

Chris Nokleberg, Colin Decker

Method Summary

Modifier and Type	Method and Description
static void	append(CharSequence from, File to, Charset charset) Appends a character sequence (such as a string) to a file using the given character set.
static ByteSink	asByteSink(File file, FileWriteMode... modes) Returns a new ByteSink for writing bytes to the given file.
static ByteSource	asByteSource(File file) Returns a new ByteSource for reading bytes from the given file.
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.
static CharSource	asCharSource(File file, Charset charset) Returns a new CharSource for reading character data from the given file using the given character set.
static void	copy(File from, Charset charset, Appendable to) Copies all characters from a file to an appendable object, using the given character set.
static void	copy(File from, File to) Copies all the bytes from one file to another.
static void	copy(File from, OutputStream to) Copies all bytes from a file to an output stream.
static void	createParentDirs(File file) Creates any necessary but nonexistent parent directories of the specified file.
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.
static boolean	equal(File file1, File file2) Returns true if the files contains the same bytes.
static TreeTraverser<File>	fileTreeTraverser() Returns a TreeTraverser instance for File trees.
static String	getFileExtension(String fullName) Returns the file extension for the given file name, or the empty string if the file has no extension.
static String	getNameWithoutExtension(String file) Returns the file name without its file extension or path.
static HashCode	hash(File file, HashFunction hashFunction) Computes the hash code of the file using hashFunction.
static Predicate<File>	isDirectory() Returns a predicate that returns the result of File.isDirectory() on input files.
static Predicate<File>	isFile() Returns a predicate that returns the result of File.isFile() on input files.
static MappedByteBuffer	map(File file) Fully maps a file read-only in to memory as per FileChannel.map(java.nio.channels.FileChannel.MapMode, long, long).
static MappedByteBuffer	map(File file, FileChannel.MapMode mode) Fully maps a file in to memory as per FileChannel.map(java.nio.channels.FileChannel.MapMode, long, long) using the requested FileChannel.MapMode.
static MappedByteBuffer	map(File file, FileChannel.MapMode mode, long size) Maps a file in to memory as per FileChannel.map(java.nio.channels.FileChannel.MapMode, long, long) using the requested FileChannel.MapMode.
static void	move(File from, File to) Moves a file from one path to another.
static BufferedReader	newReader(File file, Charset charset) Returns a buffered reader that reads from a file using the given character set.
static BufferedWriter	newWriter(File file, Charset charset) Returns a buffered writer that writes to a file using the given character set.
static <T> T	readBytes(File file, ByteProcessor<T> processor) Process the bytes of a file.
static String	readFirstLine(File file, Charset charset) Reads the first line from a file.
static List<String>	readLines(File file, Charset charset) Reads all of the lines from a file.
static <T> T	readLines(File file, Charset charset, LineProcessor<T> callback) Streams lines from a File, stopping when our callback returns false, or we have read all of the lines.
static String	simplifyPath(String pathname) Returns the lexically cleaned form of the path name, usually (but not always) equivalent to the original.
static byte[]	toByteArray(File file) Reads all bytes from a file into a byte array.
static String	toString(File file, Charset charset) Reads all characters from a file into a String, using the given character set.
static void	touch(File file) Creates an empty file or updates the last updated timestamp on the same as the unix command of the same name.
static void	write(byte[] from, File to) Overwrites a file with the contents of a byte array.
static void	write(CharSequence from, File to, Charset charset) Writes a character sequence (such as a string) to a file using the given character set.

Methods inherited from class java.lang.Object

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

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

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.

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

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.

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.

Parameters:

from - the source file

to - the destination file

Throws:

IOException - if an I/O error occurs

IllegalArgumentException - if from.equals(to)

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 StandardCharsets 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 StandardCharsets for helpful predefined constants

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

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 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().

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

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

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

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:

FileChannel.map(MapMode, long, long)

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:

FileChannel.map(MapMode, long, long)

map

public static MappedByteBuffer map(File file,
                                   FileChannel.MapMode mode,
                                   long size)
                            throws FileNotFoundException,
                                   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

FileNotFoundException

Since:

2.0

See Also:

FileChannel.map(MapMode, long, long)

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

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