001/*
002 * Copyright (C) 2007 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.io;
016
017import static com.google.common.base.Preconditions.checkArgument;
018import static com.google.common.base.Preconditions.checkNotNull;
019import static com.google.common.io.FileWriteMode.APPEND;
020
021import com.google.common.annotations.Beta;
022import com.google.common.annotations.GwtIncompatible;
023import com.google.common.base.Joiner;
024import com.google.common.base.Optional;
025import com.google.common.base.Predicate;
026import com.google.common.base.Splitter;
027import com.google.common.collect.ImmutableSet;
028import com.google.common.collect.Lists;
029import com.google.common.collect.TreeTraverser;
030import com.google.common.hash.HashCode;
031import com.google.common.hash.HashFunction;
032import com.google.errorprone.annotations.CanIgnoreReturnValue;
033import java.io.BufferedReader;
034import java.io.BufferedWriter;
035import java.io.File;
036import java.io.FileInputStream;
037import java.io.FileNotFoundException;
038import java.io.FileOutputStream;
039import java.io.IOException;
040import java.io.InputStream;
041import java.io.InputStreamReader;
042import java.io.OutputStream;
043import java.io.OutputStreamWriter;
044import java.io.RandomAccessFile;
045import java.nio.MappedByteBuffer;
046import java.nio.channels.FileChannel;
047import java.nio.channels.FileChannel.MapMode;
048import java.nio.charset.Charset;
049import java.nio.charset.StandardCharsets;
050import java.util.ArrayList;
051import java.util.Arrays;
052import java.util.Collections;
053import java.util.List;
054
055/**
056 * Provides utility methods for working with {@linkplain File files}.
057 *
058 * <p>{@link java.nio.file.Path} users will find similar utilities in {@link MoreFiles} and the
059 * JDK's {@link java.nio.file.Files} class.
060 *
061 * @author Chris Nokleberg
062 * @author Colin Decker
063 * @since 1.0
064 */
065@Beta
066@GwtIncompatible
067public final class Files {
068
069  /** Maximum loop count when creating temp directories. */
070  private static final int TEMP_DIR_ATTEMPTS = 10000;
071
072  private Files() {}
073
074  /**
075   * Returns a buffered reader that reads from a file using the given character set.
076   *
077   * <p><b>{@link java.nio.file.Path} equivalent:</b> {@link
078   * java.nio.file.Files#newBufferedReader(java.nio.file.Path, Charset)}.
079   *
080   * @param file the file to read from
081   * @param charset the charset used to decode the input stream; see {@link StandardCharsets} for
082   *     helpful predefined constants
083   * @return the buffered reader
084   */
085  public static BufferedReader newReader(File file, Charset charset) throws FileNotFoundException {
086    checkNotNull(file);
087    checkNotNull(charset);
088    return new BufferedReader(new InputStreamReader(new FileInputStream(file), charset));
089  }
090
091  /**
092   * Returns a buffered writer that writes to a file using the given character set.
093   *
094   * <p><b>{@link java.nio.file.Path} equivalent:</b> {@link
095   * java.nio.file.Files#newBufferedWriter(java.nio.file.Path, Charset,
096   * java.nio.file.OpenOption...)}.
097   *
098   * @param file the file to write to
099   * @param charset the charset used to encode the output stream; see {@link StandardCharsets} for
100   *     helpful predefined constants
101   * @return the buffered writer
102   */
103  public static BufferedWriter newWriter(File file, Charset charset) throws FileNotFoundException {
104    checkNotNull(file);
105    checkNotNull(charset);
106    return new BufferedWriter(new OutputStreamWriter(new FileOutputStream(file), charset));
107  }
108
109  /**
110   * Returns a new {@link ByteSource} for reading bytes from the given file.
111   *
112   * @since 14.0
113   */
114  public static ByteSource asByteSource(File file) {
115    return new FileByteSource(file);
116  }
117
118  private static final class FileByteSource extends ByteSource {
119
120    private final File file;
121
122    private FileByteSource(File file) {
123      this.file = checkNotNull(file);
124    }
125
126    @Override
127    public FileInputStream openStream() throws IOException {
128      return new FileInputStream(file);
129    }
130
131    @Override
132    public Optional<Long> sizeIfKnown() {
133      if (file.isFile()) {
134        return Optional.of(file.length());
135      } else {
136        return Optional.absent();
137      }
138    }
139
140    @Override
141    public long size() throws IOException {
142      if (!file.isFile()) {
143        throw new FileNotFoundException(file.toString());
144      }
145      return file.length();
146    }
147
148    @Override
149    public byte[] read() throws IOException {
150      Closer closer = Closer.create();
151      try {
152        FileInputStream in = closer.register(openStream());
153        return readFile(in, in.getChannel().size());
154      } catch (Throwable e) {
155        throw closer.rethrow(e);
156      } finally {
157        closer.close();
158      }
159    }
160
161    @Override
162    public String toString() {
163      return "Files.asByteSource(" + file + ")";
164    }
165  }
166
167  /**
168   * Reads a file of the given expected size from the given input stream, if it will fit into a byte
169   * array. This method handles the case where the file size changes between when the size is read
170   * and when the contents are read from the stream.
171   */
172  static byte[] readFile(InputStream in, long expectedSize) throws IOException {
173    if (expectedSize > Integer.MAX_VALUE) {
174      throw new OutOfMemoryError(
175          "file is too large to fit in a byte array: " + expectedSize + " bytes");
176    }
177
178    // some special files may return size 0 but have content, so read
179    // the file normally in that case guessing at the buffer size to use.  Note, there is no point
180    // in calling the 'toByteArray' overload that doesn't take a size because that calls
181    // InputStream.available(), but our caller has already done that.  So instead just guess that
182    // the file is 4K bytes long and rely on the fallback in toByteArray to expand the buffer if
183    // needed.
184    // This also works around an app-engine bug where FileInputStream.available() consistently
185    // throws an IOException for certain files, even though FileInputStream.getChannel().size() does
186    // not!
187    return ByteStreams.toByteArray(in, expectedSize == 0 ? 4096 : (int) expectedSize);
188  }
189
190  /**
191   * Returns a new {@link ByteSink} for writing bytes to the given file. The given {@code modes}
192   * control how the file is opened for writing. When no mode is provided, the file will be
193   * truncated before writing. When the {@link FileWriteMode#APPEND APPEND} mode is provided, writes
194   * will append to the end of the file without truncating it.
195   *
196   * @since 14.0
197   */
198  public static ByteSink asByteSink(File file, FileWriteMode... modes) {
199    return new FileByteSink(file, modes);
200  }
201
202  private static final class FileByteSink extends ByteSink {
203
204    private final File file;
205    private final ImmutableSet<FileWriteMode> modes;
206
207    private FileByteSink(File file, FileWriteMode... modes) {
208      this.file = checkNotNull(file);
209      this.modes = ImmutableSet.copyOf(modes);
210    }
211
212    @Override
213    public FileOutputStream openStream() throws IOException {
214      return new FileOutputStream(file, modes.contains(APPEND));
215    }
216
217    @Override
218    public String toString() {
219      return "Files.asByteSink(" + file + ", " + modes + ")";
220    }
221  }
222
223  /**
224   * Returns a new {@link CharSource} for reading character data from the given file using the given
225   * character set.
226   *
227   * @since 14.0
228   */
229  public static CharSource asCharSource(File file, Charset charset) {
230    return asByteSource(file).asCharSource(charset);
231  }
232
233  /**
234   * Returns a new {@link CharSink} for writing character data to the given file using the given
235   * character set. The given {@code modes} control how the file is opened for writing. When no mode
236   * is provided, the file will be truncated before writing. When the {@link FileWriteMode#APPEND
237   * APPEND} mode is provided, writes will append to the end of the file without truncating it.
238   *
239   * @since 14.0
240   */
241  public static CharSink asCharSink(File file, Charset charset, FileWriteMode... modes) {
242    return asByteSink(file, modes).asCharSink(charset);
243  }
244
245  /**
246   * Reads all bytes from a file into a byte array.
247   *
248   * <p><b>{@link java.nio.file.Path} equivalent:</b> {@link java.nio.file.Files#readAllBytes}.
249   *
250   * @param file the file to read from
251   * @return a byte array containing all the bytes from file
252   * @throws IllegalArgumentException if the file is bigger than the largest possible byte array
253   *     (2^31 - 1)
254   * @throws IOException if an I/O error occurs
255   */
256  public static byte[] toByteArray(File file) throws IOException {
257    return asByteSource(file).read();
258  }
259
260  /**
261   * Reads all characters from a file into a {@link String}, using the given character set.
262   *
263   * @param file the file to read from
264   * @param charset the charset used to decode the input stream; see {@link StandardCharsets} for
265   *     helpful predefined constants
266   * @return a string containing all the characters from the file
267   * @throws IOException if an I/O error occurs
268   * @deprecated Prefer {@code asCharSource(file, charset).read()}. This method is scheduled to be
269   *     removed in January 2019.
270   */
271  @Deprecated
272  public static String toString(File file, Charset charset) throws IOException {
273    return asCharSource(file, charset).read();
274  }
275
276  /**
277   * Overwrites a file with the contents of a byte array.
278   *
279   * <p><b>{@link java.nio.file.Path} equivalent:</b> {@link
280   * java.nio.file.Files#write(java.nio.file.Path, byte[], java.nio.file.OpenOption...)}.
281   *
282   * @param from the bytes to write
283   * @param to the destination file
284   * @throws IOException if an I/O error occurs
285   */
286  public static void write(byte[] from, File to) throws IOException {
287    asByteSink(to).write(from);
288  }
289
290  /**
291   * Copies all bytes from a file to an output stream.
292   *
293   * <p><b>{@link java.nio.file.Path} equivalent:</b> {@link
294   * java.nio.file.Files#copy(java.nio.file.Path, OutputStream)}.
295   *
296   * @param from the source file
297   * @param to the output stream
298   * @throws IOException if an I/O error occurs
299   */
300  public static void copy(File from, OutputStream to) throws IOException {
301    asByteSource(from).copyTo(to);
302  }
303
304  /**
305   * Copies all the bytes from one file to another.
306   *
307   * <p>Copying is not an atomic operation - in the case of an I/O error, power loss, process
308   * termination, or other problems, {@code to} may not be a complete copy of {@code from}. If you
309   * need to guard against those conditions, you should employ other file-level synchronization.
310   *
311   * <p><b>Warning:</b> If {@code to} represents an existing file, that file will be overwritten
312   * with the contents of {@code from}. If {@code to} and {@code from} refer to the <i>same</i>
313   * file, the contents of that file will be deleted.
314   *
315   * <p><b>{@link java.nio.file.Path} equivalent:</b> {@link
316   * java.nio.file.Files#copy(java.nio.file.Path, java.nio.file.Path, java.nio.file.CopyOption...)}.
317   *
318   * @param from the source file
319   * @param to the destination file
320   * @throws IOException if an I/O error occurs
321   * @throws IllegalArgumentException if {@code from.equals(to)}
322   */
323  public static void copy(File from, File to) throws IOException {
324    checkArgument(!from.equals(to), "Source %s and destination %s must be different", from, to);
325    asByteSource(from).copyTo(asByteSink(to));
326  }
327
328  /**
329   * Writes a character sequence (such as a string) to a file using the given character set.
330   *
331   * @param from the character sequence to write
332   * @param to the destination file
333   * @param charset the charset used to encode the output stream; see {@link StandardCharsets} for
334   *     helpful predefined constants
335   * @throws IOException if an I/O error occurs
336   * @deprecated Prefer {@code asCharSink(to, charset).write(from)}. This method is scheduled to be
337   *     removed in January 2019.
338   */
339  @Deprecated
340  public static void write(CharSequence from, File to, Charset charset) throws IOException {
341    asCharSink(to, charset).write(from);
342  }
343
344  /**
345   * Appends a character sequence (such as a string) to a file using the given character set.
346   *
347   * @param from the character sequence to append
348   * @param to the destination file
349   * @param charset the charset used to encode the output stream; see {@link StandardCharsets} for
350   *     helpful predefined constants
351   * @throws IOException if an I/O error occurs
352   * @deprecated Prefer {@code asCharSink(to, charset, FileWriteMode.APPEND).write(from)}. This
353   *     method is scheduled to be removed in January 2019.
354   */
355  @Deprecated
356  public static void append(CharSequence from, File to, Charset charset) throws IOException {
357    asCharSink(to, charset, FileWriteMode.APPEND).write(from);
358  }
359
360  /**
361   * Copies all characters from a file to an appendable object, using the given character set.
362   *
363   * @param from the source file
364   * @param charset the charset used to decode the input stream; see {@link StandardCharsets} for
365   *     helpful predefined constants
366   * @param to the appendable object
367   * @throws IOException if an I/O error occurs
368   * @deprecated Prefer {@code asCharSource(from, charset).copyTo(to)}. This method is scheduled to
369   *     be removed in January 2019.
370   */
371  @Deprecated
372  public static void copy(File from, Charset charset, Appendable to) throws IOException {
373    asCharSource(from, charset).copyTo(to);
374  }
375
376  /**
377   * Returns true if the given files exist, are not directories, and contain the same bytes.
378   *
379   * @throws IOException if an I/O error occurs
380   */
381  public static boolean equal(File file1, File file2) throws IOException {
382    checkNotNull(file1);
383    checkNotNull(file2);
384    if (file1 == file2 || file1.equals(file2)) {
385      return true;
386    }
387
388    /*
389     * Some operating systems may return zero as the length for files denoting system-dependent
390     * entities such as devices or pipes, in which case we must fall back on comparing the bytes
391     * directly.
392     */
393    long len1 = file1.length();
394    long len2 = file2.length();
395    if (len1 != 0 && len2 != 0 && len1 != len2) {
396      return false;
397    }
398    return asByteSource(file1).contentEquals(asByteSource(file2));
399  }
400
401  /**
402   * Atomically creates a new directory somewhere beneath the system's temporary directory (as
403   * defined by the {@code java.io.tmpdir} system property), and returns its name.
404   *
405   * <p>Use this method instead of {@link File#createTempFile(String, String)} when you wish to
406   * create a directory, not a regular file. A common pitfall is to call {@code createTempFile},
407   * delete the file and create a directory in its place, but this leads a race condition which can
408   * be exploited to create security vulnerabilities, especially when executable files are to be
409   * written into the directory.
410   *
411   * <p>This method assumes that the temporary volume is writable, has free inodes and free blocks,
412   * and that it will not be called thousands of times per second.
413   *
414   * <p><b>{@link java.nio.file.Path} equivalent:</b> {@link
415   * java.nio.file.Files#createTempDirectory}.
416   *
417   * @return the newly-created directory
418   * @throws IllegalStateException if the directory could not be created
419   */
420  public static File createTempDir() {
421    File baseDir = new File(System.getProperty("java.io.tmpdir"));
422    String baseName = System.currentTimeMillis() + "-";
423
424    for (int counter = 0; counter < TEMP_DIR_ATTEMPTS; counter++) {
425      File tempDir = new File(baseDir, baseName + counter);
426      if (tempDir.mkdir()) {
427        return tempDir;
428      }
429    }
430    throw new IllegalStateException(
431        "Failed to create directory within "
432            + TEMP_DIR_ATTEMPTS
433            + " attempts (tried "
434            + baseName
435            + "0 to "
436            + baseName
437            + (TEMP_DIR_ATTEMPTS - 1)
438            + ')');
439  }
440
441  /**
442   * Creates an empty file or updates the last updated timestamp on the same as the unix command of
443   * the same name.
444   *
445   * @param file the file to create or update
446   * @throws IOException if an I/O error occurs
447   */
448  public static void touch(File file) throws IOException {
449    checkNotNull(file);
450    if (!file.createNewFile() && !file.setLastModified(System.currentTimeMillis())) {
451      throw new IOException("Unable to update modification time of " + file);
452    }
453  }
454
455  /**
456   * Creates any necessary but nonexistent parent directories of the specified file. Note that if
457   * this operation fails it may have succeeded in creating some (but not all) of the necessary
458   * parent directories.
459   *
460   * @throws IOException if an I/O error occurs, or if any necessary but nonexistent parent
461   *     directories of the specified file could not be created.
462   * @since 4.0
463   */
464  public static void createParentDirs(File file) throws IOException {
465    checkNotNull(file);
466    File parent = file.getCanonicalFile().getParentFile();
467    if (parent == null) {
468      /*
469       * The given directory is a filesystem root. All zero of its ancestors exist. This doesn't
470       * mean that the root itself exists -- consider x:\ on a Windows machine without such a drive
471       * -- or even that the caller can create it, but this method makes no such guarantees even for
472       * non-root files.
473       */
474      return;
475    }
476    parent.mkdirs();
477    if (!parent.isDirectory()) {
478      throw new IOException("Unable to create parent directories of " + file);
479    }
480  }
481
482  /**
483   * Moves a file from one path to another. This method can rename a file and/or move it to a
484   * different directory. In either case {@code to} must be the target path for the file itself; not
485   * just the new name for the file or the path to the new parent directory.
486   *
487   * <p><b>{@link java.nio.file.Path} equivalent:</b> {@link java.nio.file.Files#move}.
488   *
489   * @param from the source file
490   * @param to the destination file
491   * @throws IOException if an I/O error occurs
492   * @throws IllegalArgumentException if {@code from.equals(to)}
493   */
494  public static void move(File from, File to) throws IOException {
495    checkNotNull(from);
496    checkNotNull(to);
497    checkArgument(!from.equals(to), "Source %s and destination %s must be different", from, to);
498
499    if (!from.renameTo(to)) {
500      copy(from, to);
501      if (!from.delete()) {
502        if (!to.delete()) {
503          throw new IOException("Unable to delete " + to);
504        }
505        throw new IOException("Unable to delete " + from);
506      }
507    }
508  }
509
510  /**
511   * Reads the first line from a file. The line does not include line-termination characters, but
512   * does include other leading and trailing whitespace.
513   *
514   * @param file the file to read from
515   * @param charset the charset used to decode the input stream; see {@link StandardCharsets} for
516   *     helpful predefined constants
517   * @return the first line, or null if the file is empty
518   * @throws IOException if an I/O error occurs
519   * @deprecated Prefer {@code asCharSource(file, charset).readFirstLine()}. This method is
520   *     scheduled to be removed in January 2019.
521   */
522  @Deprecated
523  public static String readFirstLine(File file, Charset charset) throws IOException {
524    return asCharSource(file, charset).readFirstLine();
525  }
526
527  /**
528   * Reads all of the lines from a file. The lines do not include line-termination characters, but
529   * do include other leading and trailing whitespace.
530   *
531   * <p>This method returns a mutable {@code List}. For an {@code ImmutableList}, use {@code
532   * Files.asCharSource(file, charset).readLines()}.
533   *
534   * <p><b>{@link java.nio.file.Path} equivalent:</b> {@link
535   * java.nio.file.Files#readAllLines(java.nio.file.Path, Charset)}.
536   *
537   * @param file the file to read from
538   * @param charset the charset used to decode the input stream; see {@link StandardCharsets} for
539   *     helpful predefined constants
540   * @return a mutable {@link List} containing all the lines
541   * @throws IOException if an I/O error occurs
542   */
543  public static List<String> readLines(File file, Charset charset) throws IOException {
544    // don't use asCharSource(file, charset).readLines() because that returns
545    // an immutable list, which would change the behavior of this method
546    return asCharSource(file, charset)
547        .readLines(
548            new LineProcessor<List<String>>() {
549              final List<String> result = Lists.newArrayList();
550
551              @Override
552              public boolean processLine(String line) {
553                result.add(line);
554                return true;
555              }
556
557              @Override
558              public List<String> getResult() {
559                return result;
560              }
561            });
562  }
563
564  /**
565   * Streams lines from a {@link File}, stopping when our callback returns false, or we have read
566   * all of the lines.
567   *
568   * @param file the file to read from
569   * @param charset the charset used to decode the input stream; see {@link StandardCharsets} for
570   *     helpful predefined constants
571   * @param callback the {@link LineProcessor} to use to handle the lines
572   * @return the output of processing the lines
573   * @throws IOException if an I/O error occurs
574   * @deprecated Prefer {@code asCharSource(file, charset).readLines(callback)}. This method is
575   *     scheduled to be removed in January 2019.
576   */
577  @Deprecated
578  @CanIgnoreReturnValue // some processors won't return a useful result
579  public static <T> T readLines(File file, Charset charset, LineProcessor<T> callback)
580      throws IOException {
581    return asCharSource(file, charset).readLines(callback);
582  }
583
584  /**
585   * Process the bytes of a file.
586   *
587   * <p>(If this seems too complicated, maybe you're looking for {@link #toByteArray}.)
588   *
589   * @param file the file to read
590   * @param processor the object to which the bytes of the file are passed.
591   * @return the result of the byte processor
592   * @throws IOException if an I/O error occurs
593   * @deprecated Prefer {@code asByteSource(file).read(processor)}. This method is scheduled to be
594   *     removed in January 2019.
595   */
596  @Deprecated
597  @CanIgnoreReturnValue // some processors won't return a useful result
598  public static <T> T readBytes(File file, ByteProcessor<T> processor) throws IOException {
599    return asByteSource(file).read(processor);
600  }
601
602  /**
603   * Computes the hash code of the {@code file} using {@code hashFunction}.
604   *
605   * @param file the file to read
606   * @param hashFunction the hash function to use to hash the data
607   * @return the {@link HashCode} of all of the bytes in the file
608   * @throws IOException if an I/O error occurs
609   * @since 12.0
610   * @deprecated Prefer {@code asByteSource(file).hash(hashFunction)}. This method is scheduled to
611   *     be removed in January 2019.
612   */
613  @Deprecated
614  public static HashCode hash(File file, HashFunction hashFunction) throws IOException {
615    return asByteSource(file).hash(hashFunction);
616  }
617
618  /**
619   * Fully maps a file read-only in to memory as per {@link
620   * FileChannel#map(java.nio.channels.FileChannel.MapMode, long, long)}.
621   *
622   * <p>Files are mapped from offset 0 to its length.
623   *
624   * <p>This only works for files ≤ {@link Integer#MAX_VALUE} bytes.
625   *
626   * @param file the file to map
627   * @return a read-only buffer reflecting {@code file}
628   * @throws FileNotFoundException if the {@code file} does not exist
629   * @throws IOException if an I/O error occurs
630   * @see FileChannel#map(MapMode, long, long)
631   * @since 2.0
632   */
633  public static MappedByteBuffer map(File file) throws IOException {
634    checkNotNull(file);
635    return map(file, MapMode.READ_ONLY);
636  }
637
638  /**
639   * Fully maps a file in to memory as per {@link
640   * FileChannel#map(java.nio.channels.FileChannel.MapMode, long, long)} using the requested {@link
641   * MapMode}.
642   *
643   * <p>Files are mapped from offset 0 to its length.
644   *
645   * <p>This only works for files ≤ {@link Integer#MAX_VALUE} bytes.
646   *
647   * @param file the file to map
648   * @param mode the mode to use when mapping {@code file}
649   * @return a buffer reflecting {@code file}
650   * @throws FileNotFoundException if the {@code file} does not exist
651   * @throws IOException if an I/O error occurs
652   * @see FileChannel#map(MapMode, long, long)
653   * @since 2.0
654   */
655  public static MappedByteBuffer map(File file, MapMode mode) throws IOException {
656    checkNotNull(file);
657    checkNotNull(mode);
658    if (!file.exists()) {
659      throw new FileNotFoundException(file.toString());
660    }
661    return map(file, mode, file.length());
662  }
663
664  /**
665   * Maps a file in to memory as per {@link FileChannel#map(java.nio.channels.FileChannel.MapMode,
666   * long, long)} using the requested {@link MapMode}.
667   *
668   * <p>Files are mapped from offset 0 to {@code size}.
669   *
670   * <p>If the mode is {@link MapMode#READ_WRITE} and the file does not exist, it will be created
671   * with the requested {@code size}. Thus this method is useful for creating memory mapped files
672   * which do not yet exist.
673   *
674   * <p>This only works for files ≤ {@link Integer#MAX_VALUE} bytes.
675   *
676   * @param file the file to map
677   * @param mode the mode to use when mapping {@code file}
678   * @return a buffer reflecting {@code file}
679   * @throws IOException if an I/O error occurs
680   * @see FileChannel#map(MapMode, long, long)
681   * @since 2.0
682   */
683  public static MappedByteBuffer map(File file, MapMode mode, long size)
684      throws FileNotFoundException, IOException {
685    checkNotNull(file);
686    checkNotNull(mode);
687
688    Closer closer = Closer.create();
689    try {
690      RandomAccessFile raf =
691          closer.register(new RandomAccessFile(file, mode == MapMode.READ_ONLY ? "r" : "rw"));
692      return map(raf, mode, size);
693    } catch (Throwable e) {
694      throw closer.rethrow(e);
695    } finally {
696      closer.close();
697    }
698  }
699
700  private static MappedByteBuffer map(RandomAccessFile raf, MapMode mode, long size)
701      throws IOException {
702    Closer closer = Closer.create();
703    try {
704      FileChannel channel = closer.register(raf.getChannel());
705      return channel.map(mode, 0, size);
706    } catch (Throwable e) {
707      throw closer.rethrow(e);
708    } finally {
709      closer.close();
710    }
711  }
712
713  /**
714   * Returns the lexically cleaned form of the path name, <i>usually</i> (but not always) equivalent
715   * to the original. The following heuristics are used:
716   *
717   * <ul>
718   * <li>empty string becomes .
719   * <li>. stays as .
720   * <li>fold out ./
721   * <li>fold out ../ when possible
722   * <li>collapse multiple slashes
723   * <li>delete trailing slashes (unless the path is just "/")
724   * </ul>
725   *
726   * <p>These heuristics do not always match the behavior of the filesystem. In particular, consider
727   * the path {@code a/../b}, which {@code simplifyPath} will change to {@code b}. If {@code a} is a
728   * symlink to {@code x}, {@code a/../b} may refer to a sibling of {@code x}, rather than the
729   * sibling of {@code a} referred to by {@code b}.
730   *
731   * @since 11.0
732   */
733  public static String simplifyPath(String pathname) {
734    checkNotNull(pathname);
735    if (pathname.length() == 0) {
736      return ".";
737    }
738
739    // split the path apart
740    Iterable<String> components = Splitter.on('/').omitEmptyStrings().split(pathname);
741    List<String> path = new ArrayList<>();
742
743    // resolve ., .., and //
744    for (String component : components) {
745      switch (component) {
746        case ".":
747          continue;
748        case "..":
749          if (path.size() > 0 && !path.get(path.size() - 1).equals("..")) {
750            path.remove(path.size() - 1);
751          } else {
752            path.add("..");
753          }
754          break;
755        default:
756          path.add(component);
757          break;
758      }
759    }
760
761    // put it back together
762    String result = Joiner.on('/').join(path);
763    if (pathname.charAt(0) == '/') {
764      result = "/" + result;
765    }
766
767    while (result.startsWith("/../")) {
768      result = result.substring(3);
769    }
770    if (result.equals("/..")) {
771      result = "/";
772    } else if ("".equals(result)) {
773      result = ".";
774    }
775
776    return result;
777  }
778
779  /**
780   * Returns the <a href="http://en.wikipedia.org/wiki/Filename_extension">file extension</a> for
781   * the given file name, or the empty string if the file has no extension. The result does not
782   * include the '{@code .}'.
783   *
784   * <p><b>Note:</b> This method simply returns everything after the last '{@code .}' in the file's
785   * name as determined by {@link File#getName}. It does not account for any filesystem-specific
786   * behavior that the {@link File} API does not already account for. For example, on NTFS it will
787   * report {@code "txt"} as the extension for the filename {@code "foo.exe:.txt"} even though NTFS
788   * will drop the {@code ":.txt"} part of the name when the file is actually created on the
789   * filesystem due to NTFS's <a href="https://goo.gl/vTpJi4">Alternate Data Streams</a>.
790   *
791   * @since 11.0
792   */
793  public static String getFileExtension(String fullName) {
794    checkNotNull(fullName);
795    String fileName = new File(fullName).getName();
796    int dotIndex = fileName.lastIndexOf('.');
797    return (dotIndex == -1) ? "" : fileName.substring(dotIndex + 1);
798  }
799
800  /**
801   * Returns the file name without its
802   * <a href="http://en.wikipedia.org/wiki/Filename_extension">file extension</a> or path. This is
803   * similar to the {@code basename} unix command. The result does not include the '{@code .}'.
804   *
805   * @param file The name of the file to trim the extension from. This can be either a fully
806   *     qualified file name (including a path) or just a file name.
807   * @return The file name without its path or extension.
808   * @since 14.0
809   */
810  public static String getNameWithoutExtension(String file) {
811    checkNotNull(file);
812    String fileName = new File(file).getName();
813    int dotIndex = fileName.lastIndexOf('.');
814    return (dotIndex == -1) ? fileName : fileName.substring(0, dotIndex);
815  }
816
817  /**
818   * Returns a {@link TreeTraverser} instance for {@link File} trees.
819   *
820   * <p><b>Warning:</b> {@code File} provides no support for symbolic links, and as such there is no
821   * way to ensure that a symbolic link to a directory is not followed when traversing the tree. In
822   * this case, iterables created by this traverser could contain files that are outside of the
823   * given directory or even be infinite if there is a symbolic link loop.
824   *
825   * @since 15.0
826   */
827  public static TreeTraverser<File> fileTreeTraverser() {
828    return FILE_TREE_TRAVERSER;
829  }
830
831  private static final TreeTraverser<File> FILE_TREE_TRAVERSER =
832      new TreeTraverser<File>() {
833        @Override
834        public Iterable<File> children(File file) {
835          // check isDirectory() just because it may be faster than listFiles() on a non-directory
836          if (file.isDirectory()) {
837            File[] files = file.listFiles();
838            if (files != null) {
839              return Collections.unmodifiableList(Arrays.asList(files));
840            }
841          }
842
843          return Collections.emptyList();
844        }
845
846        @Override
847        public String toString() {
848          return "Files.fileTreeTraverser()";
849        }
850      };
851
852  /**
853   * Returns a predicate that returns the result of {@link File#isDirectory} on input files.
854   *
855   * @since 15.0
856   */
857  public static Predicate<File> isDirectory() {
858    return FilePredicate.IS_DIRECTORY;
859  }
860
861  /**
862   * Returns a predicate that returns the result of {@link File#isFile} on input files.
863   *
864   * @since 15.0
865   */
866  public static Predicate<File> isFile() {
867    return FilePredicate.IS_FILE;
868  }
869
870  private enum FilePredicate implements Predicate<File> {
871    IS_DIRECTORY {
872      @Override
873      public boolean apply(File file) {
874        return file.isDirectory();
875      }
876
877      @Override
878      public String toString() {
879        return "Files.isDirectory()";
880      }
881    },
882
883    IS_FILE {
884      @Override
885      public boolean apply(File file) {
886        return file.isFile();
887      }
888
889      @Override
890      public String toString() {
891        return "Files.isFile()";
892      }
893    }
894  }
895}