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