Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.google.common.io
Class Files

    java.lang.Object
      com.google.common.io.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
Author:
  Chris Nokleberg

Method Summary
`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 void` | `copy(File from, Charset charset, Appendable to)` Copies all characters from a file to an appendable object, using the given character set.
`static
`<W extends Appendable & Closeable> void`
` | `copy(File from, Charset charset, OutputSupplier<W> to)` Copies all characters from a file to a `Appendable` & `Closeable` object supplied by a factory, 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, OutputSupplier<? extends OutputStream> to)` Copies all bytes from a file to an `OutputStream` supplied by a factory.
`static void` | `copy(InputSupplier<? extends InputStream> from, File to)` Copies to a file all bytes from an `InputStream` supplied by a factory.
`static
`<R extends Readable & Closeable> void`
` | `copy(InputSupplier<R> from, File to, Charset charset)` Copies to a file all characters from a `Readable` and `Closeable` object supplied by a factory, using the given character set.
`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 long` | `getChecksum(File file, Checksum checksum)` Computes and returns the checksum value for a file.
`static String` | `getFileExtension(String fileName)` Returns the file extension for the given file name, or the empty string if the file has no extension.
`static HashCode` | `hash(File file, HashFunction hashFunction)` Computes the hash code of the `file` using `hashFunction`.
`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 the file from one path to another.
`static InputSupplier<FileInputStream>` | `newInputStreamSupplier(File file)` Returns a factory that will supply instances of `FileInputStream` that read from a file.
`static OutputSupplier<FileOutputStream>` | `newOutputStreamSupplier(File file)` Returns a factory that will supply instances of `FileOutputStream` that write to a file.
`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.
`static BufferedReader` | `newReader(File file, Charset charset)` Returns a buffered reader that reads from a file using the given character set.
`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.
`static BufferedWriter` | `newWriter(File file, Charset charset)` Returns a buffered writer that writes to a file using the given character set.
`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.
`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.
`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 `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`

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

### copy

    public static void copy(InputSupplier<? extends InputStream> from,
                            File to)
                     throws IOException

  Copies to a file all bytes from an `InputStream` supplied by a factory.

  Parameters:
    `from` - the input factory
    `to` - the destination 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,
                            OutputSupplier<? extends OutputStream> to)
                     throws IOException

  Copies all bytes from a file to an `OutputStream` supplied by a factory.

  Parameters:
    `from` - the source file
    `to` - the output factory
  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. .

  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.

  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

### getChecksum

    public static long getChecksum(File file,
                                   Checksum checksum)
                            throws IOException

  Computes and returns the checksum value for a file. The checksum object is reset when this method returns successfully.

  Parameters:
    `file` - the file to read
    `checksum` - the checksum object
  Returns:
    the result of `Checksum.getValue()` after updating the checksum object with all of the bytes in the file
  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 fileName)

  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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2010-2012. All Rights Reserved.