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