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}