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