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