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