Class Files
- java.lang.Object
-
- com.google.common.io.Files
-
-
Method Summary
All Methods Static Methods Concrete Methods Deprecated Methods Modifier and Type Method Description static void
append(CharSequence from, File to, Charset charset)
Deprecated.PreferasCharSink(to, charset, FileWriteMode.APPEND).write(from)
.static ByteSink
asByteSink(File file, FileWriteMode... modes)
Returns a newByteSink
for writing bytes to the given file.static ByteSource
asByteSource(File file)
Returns a newByteSource
for reading bytes from the given file.static CharSink
asCharSink(File file, Charset charset, FileWriteMode... modes)
Returns a newCharSink
for writing character data to the given file using the given character set.static CharSource
asCharSource(File file, Charset charset)
Returns a newCharSource
for reading character data from the given file 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
copy(File from, Charset charset, Appendable to)
Deprecated.PreferasCharSource(from, charset).copyTo(to)
.static void
createParentDirs(File file)
Creates any necessary but nonexistent parent directories of the specified file.static File
createTempDir()
Deprecated.For Android users, see the Data and File Storage overview to select an appropriate temporary directory (perhapscontext.getCacheDir()
).static boolean
equal(File file1, File file2)
Returns true if the given files exist, are not directories, and contain the same bytes.static Traverser<File>
fileTraverser()
Returns aTraverser
instance for the file and directory tree.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)
Deprecated.PreferasByteSource(file).hash(hashFunction)
.static Predicate<File>
isDirectory()
Returns a predicate that returns the result ofFile.isDirectory()
on input files.static Predicate<File>
isFile()
Returns a predicate that returns the result ofFile.isFile()
on input files.static MappedByteBuffer
map(File file)
Fully maps a file read-only in to memory as perFileChannel.map(java.nio.channels.FileChannel.MapMode, long, long)
.static MappedByteBuffer
map(File file, FileChannel.MapMode mode)
Fully maps a file in to memory as perFileChannel.map(java.nio.channels.FileChannel.MapMode, long, long)
using the requestedFileChannel.MapMode
.static MappedByteBuffer
map(File file, FileChannel.MapMode mode, long size)
Maps a file in to memory as perFileChannel.map(java.nio.channels.FileChannel.MapMode, long, long)
using the requestedFileChannel.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 extends @Nullable Object>
TreadBytes(File file, ByteProcessor<T> processor)
Deprecated.PreferasByteSource(file).read(processor)
.static String
readFirstLine(File file, Charset charset)
Deprecated.PreferasCharSource(file, charset).readFirstLine()
.static List<String>
readLines(File file, Charset charset)
Reads all of the lines from a file.static <T extends @Nullable Object>
TreadLines(File file, Charset charset, LineProcessor<T> callback)
Deprecated.PreferasCharSource(file, charset).readLines(callback)
.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)
Deprecated.PreferasCharSource(file, charset).read()
.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)
Deprecated.PreferasCharSink(to, charset).write(from)
.
-
-
-
Method Detail
-
newReader
@Beta 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 fromcharset
- the charset used to decode the input stream; seeStandardCharsets
for helpful predefined constants- Returns:
- the buffered reader
- Throws:
FileNotFoundException
-
newWriter
@Beta 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 tocharset
- the charset used to encode the output stream; seeStandardCharsets
for helpful predefined constants- Returns:
- the buffered writer
- Throws:
FileNotFoundException
-
asByteSource
public static ByteSource asByteSource(File file)
Returns a newByteSource
for reading bytes from the given file.- Since:
- 14.0
-
asByteSink
public static ByteSink asByteSink(File file, FileWriteMode... modes)
Returns a newByteSink
for writing bytes to the given file. The givenmodes
control how the file is opened for writing. When no mode is provided, the file will be truncated before writing. When theAPPEND
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 newCharSource
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 newCharSink
for writing character data to the given file using the given character set. The givenmodes
control how the file is opened for writing. When no mode is provided, the file will be truncated before writing. When theAPPEND
mode is provided, writes will append to the end of the file without truncating it.- Since:
- 14.0
-
toByteArray
@Beta 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
@Beta @Deprecated public static String toString(File file, Charset charset) throws IOException
Deprecated.PreferasCharSource(file, charset).read()
. This method is scheduled to be removed in October 2019.Reads all characters from a file into aString
, using the given character set.- Parameters:
file
- the file to read fromcharset
- the charset used to decode the input stream; seeStandardCharsets
for helpful predefined constants- Returns:
- a string containing all the characters from the file
- Throws:
IOException
- if an I/O error occurs
-
write
@Beta 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 writeto
- the destination file- Throws:
IOException
- if an I/O error occurs
-
write
@Beta @Deprecated public static void write(CharSequence from, File to, Charset charset) throws IOException
Deprecated.PreferasCharSink(to, charset).write(from)
. This method is scheduled to be removed in October 2019.Writes a character sequence (such as a string) to a file using the given character set.- Parameters:
from
- the character sequence to writeto
- the destination filecharset
- the charset used to encode the output stream; seeStandardCharsets
for helpful predefined constants- Throws:
IOException
- if an I/O error occurs
-
copy
@Beta 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 fileto
- the output stream- Throws:
IOException
- if an I/O error occurs
-
copy
@Beta 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 offrom
. 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 offrom
. Ifto
andfrom
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 fileto
- the destination file- Throws:
IOException
- if an I/O error occursIllegalArgumentException
- iffrom.equals(to)
-
copy
@Beta @Deprecated public static void copy(File from, Charset charset, Appendable to) throws IOException
Deprecated.PreferasCharSource(from, charset).copyTo(to)
. This method is scheduled to be removed in October 2019.Copies all characters from a file to an appendable object, using the given character set.- Parameters:
from
- the source filecharset
- the charset used to decode the input stream; seeStandardCharsets
for helpful predefined constantsto
- the appendable object- Throws:
IOException
- if an I/O error occurs
-
append
@Beta @Deprecated public static void append(CharSequence from, File to, Charset charset) throws IOException
Deprecated.PreferasCharSink(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 appendto
- the destination filecharset
- the charset used to encode the output stream; seeStandardCharsets
for helpful predefined constants- Throws:
IOException
- if an I/O error occurs
-
equal
@Beta 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 public static File createTempDir()
Deprecated.For Android users, see the Data and File Storage overview to select an appropriate temporary directory (perhapscontext.getCacheDir()
). For developers on Java 7 or later, useFiles.createTempDirectory(java.nio.file.Path, java.lang.String, java.nio.file.attribute.FileAttribute<?>...)
, transforming it to aFile
usingtoFile()
if needed.Atomically creates a new directory somewhere beneath the system's temporary directory (as defined by thejava.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 callcreateTempFile
, 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.Depending on the environmment that this code is run in, the system temporary directory (and thus the directory this method creates) may be more visible that a program would like - files written to this directory may be read or overwritten by hostile programs running on the same machine.
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
-
touch
@Beta 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
@Beta 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
@Beta 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 caseto
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 fileto
- the destination file- Throws:
IOException
- if an I/O error occursIllegalArgumentException
- iffrom.equals(to)
-
readFirstLine
@Beta @Deprecated @CheckForNull public static String readFirstLine(File file, Charset charset) throws IOException
Deprecated.PreferasCharSource(file, charset).readFirstLine()
. This method is scheduled to be removed in October 2019.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 fromcharset
- the charset used to decode the input stream; seeStandardCharsets
for helpful predefined constants- Returns:
- the first line, or null if the file is empty
- Throws:
IOException
- if an I/O error occurs
-
readLines
@Beta 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 anImmutableList
, useFiles.asCharSource(file, charset).readLines()
.Path
equivalent:Files.readAllLines(java.nio.file.Path, Charset)
.- Parameters:
file
- the file to read fromcharset
- the charset used to decode the input stream; seeStandardCharsets
for helpful predefined constants- Returns:
- a mutable
List
containing all the lines - Throws:
IOException
- if an I/O error occurs
-
readLines
@Beta @Deprecated @CanIgnoreReturnValue public static <T extends @Nullable Object> T readLines(File file, Charset charset, LineProcessor<T> callback) throws IOException
Deprecated.PreferasCharSource(file, charset).readLines(callback)
. This method is scheduled to be removed in October 2019.Streams lines from aFile
, stopping when our callback returns false, or we have read all of the lines.- Parameters:
file
- the file to read fromcharset
- the charset used to decode the input stream; seeStandardCharsets
for helpful predefined constantscallback
- theLineProcessor
to use to handle the lines- Returns:
- the output of processing the lines
- Throws:
IOException
- if an I/O error occurs
-
readBytes
@Beta @Deprecated @CanIgnoreReturnValue public static <T extends @Nullable Object> T readBytes(File file, ByteProcessor<T> processor) throws IOException
Deprecated.PreferasByteSource(file).read(processor)
. This method is scheduled to be removed in October 2019.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 readprocessor
- 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
@Beta @Deprecated public static HashCode hash(File file, HashFunction hashFunction) throws IOException
Deprecated.PreferasByteSource(file).hash(hashFunction)
. This method is scheduled to be removed in October 2019.Computes the hash code of thefile
usinghashFunction
.- Parameters:
file
- the file to readhashFunction
- 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
@Beta public static MappedByteBuffer map(File file) throws IOException
Fully maps a file read-only in to memory as perFileChannel.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 thefile
does not existIOException
- if an I/O error occurs- Since:
- 2.0
- See Also:
FileChannel.map(MapMode, long, long)
-
map
@Beta public static MappedByteBuffer map(File file, FileChannel.MapMode mode) throws IOException
Fully maps a file in to memory as perFileChannel.map(java.nio.channels.FileChannel.MapMode, long, long)
using the requestedFileChannel.MapMode
.Files are mapped from offset 0 to its length.
This only works for files ≤
Integer.MAX_VALUE
bytes.- Parameters:
file
- the file to mapmode
- the mode to use when mappingfile
- Returns:
- a buffer reflecting
file
- Throws:
FileNotFoundException
- if thefile
does not existIOException
- if an I/O error occurs- Since:
- 2.0
- See Also:
FileChannel.map(MapMode, long, long)
-
map
@Beta public static MappedByteBuffer map(File file, FileChannel.MapMode mode, long size) throws IOException
Maps a file in to memory as perFileChannel.map(java.nio.channels.FileChannel.MapMode, long, long)
using the requestedFileChannel.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 requestedsize
. 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 mapmode
- the mode to use when mappingfile
- Returns:
- a buffer reflecting
file
- Throws:
IOException
- if an I/O error occurs- Since:
- 2.0
- See Also:
FileChannel.map(MapMode, long, long)
-
simplifyPath
@Beta 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
, whichsimplifyPath
will change tob
. Ifa
is a symlink tox
,a/../b
may refer to a sibling ofx
, rather than the sibling ofa
referred to byb
.- Since:
- 11.0
-
getFileExtension
@Beta 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 byFile.getName()
. It does not account for any filesystem-specific behavior that theFile
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
@Beta public static String getNameWithoutExtension(String file)
Returns the file name without its file extension or path. This is similar to thebasename
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
@Beta public static Traverser<File> fileTraverser()
Returns aTraverser
instance for the file and directory tree. The returned traverser starts from aFile
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 returnsPath
instances.If the
File
passed to one of theTraverser
methods does not exist or is not a directory, no exception will be thrown and the returnedIterable
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
@Beta public static Predicate<File> isDirectory()
Returns a predicate that returns the result ofFile.isDirectory()
on input files.- Since:
- 15.0
-
isFile
@Beta public static Predicate<File> isFile()
Returns a predicate that returns the result ofFile.isFile()
on input files.- Since:
- 15.0
-
-