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