62 import java.security.PrivilegedAction;
63 import java.util.ArrayList;
64 import java.util.Arrays;
65 import java.util.Collections;
66 import java.util.EnumSet;
67 import java.util.HashSet;
68 import java.util.Iterator;
69 import java.util.List;
70 import java.util.Map;
71 import java.util.Objects;
72 import java.util.ServiceLoader;
73 import java.util.Set;
74 import java.util.Spliterator;
75 import java.util.Spliterators;
76 import java.util.function.BiPredicate;
77 import java.util.stream.Stream;
78 import java.util.stream.StreamSupport;
79
80 import jdk.internal.util.ArraysSupport;
81 import sun.nio.ch.FileChannelImpl;
82 import sun.nio.fs.AbstractFileSystemProvider;
83
84 /**
85 * This class consists exclusively of static methods that operate on files,
86 * directories, or other types of files.
87 *
88 * <p> In most cases, the methods defined here will delegate to the associated
89 * file system provider to perform the file operations.
90 *
91 * @since 1.7
92 */
93
94 public final class Files {
95 // buffer size used for reading and writing
96 private static final int BUFFER_SIZE = 8192;
97
98 private Files() { }
99
100 /**
101 * Returns the {@code FileSystemProvider} to delegate to.
2927 * <pre>{@code
2928 * Files.newBufferedReader(path, StandardCharsets.UTF_8)
2929 * }</pre>
2930 *
2931 * @param path
2932 * the path to the file
2933 *
2934 * @return a new buffered reader, with default buffer size, to read text
2935 * from the file
2936 *
2937 * @throws IOException
2938 * if an I/O error occurs opening the file
2939 * @throws SecurityException
2940 * In the case of the default provider, and a security manager is
2941 * installed, the {@link SecurityManager#checkRead(String) checkRead}
2942 * method is invoked to check read access to the file.
2943 *
2944 * @since 1.8
2945 */
2946 public static BufferedReader newBufferedReader(Path path) throws IOException {
2947 return newBufferedReader(path, StandardCharsets.UTF_8);
2948 }
2949
2950 /**
2951 * Opens or creates a file for writing, returning a {@code BufferedWriter}
2952 * that may be used to write text to the file in an efficient manner.
2953 * The {@code options} parameter specifies how the file is created or
2954 * opened. If no options are present then this method works as if the {@link
2955 * StandardOpenOption#CREATE CREATE}, {@link
2956 * StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING}, and {@link
2957 * StandardOpenOption#WRITE WRITE} options are present. In other words, it
2958 * opens the file for writing, creating the file if it doesn't exist, or
2959 * initially truncating an existing {@link #isRegularFile regular-file} to
2960 * a size of {@code 0} if it exists.
2961 *
2962 * <p> The {@code Writer} methods to write text throw {@code IOException}
2963 * if the text cannot be encoded using the specified charset.
2964 *
2965 * @param path
2966 * the path to the file
2967 * @param cs
3019 *
3020 * @throws IllegalArgumentException
3021 * if {@code options} contains an invalid combination of options
3022 * @throws IOException
3023 * if an I/O error occurs opening or creating the file
3024 * @throws UnsupportedOperationException
3025 * if an unsupported option is specified
3026 * @throws SecurityException
3027 * In the case of the default provider, and a security manager is
3028 * installed, the {@link SecurityManager#checkWrite(String) checkWrite}
3029 * method is invoked to check write access to the file. The {@link
3030 * SecurityManager#checkDelete(String) checkDelete} method is
3031 * invoked to check delete access if the file is opened with the
3032 * {@code DELETE_ON_CLOSE} option.
3033 *
3034 * @since 1.8
3035 */
3036 public static BufferedWriter newBufferedWriter(Path path, OpenOption... options)
3037 throws IOException
3038 {
3039 return newBufferedWriter(path, StandardCharsets.UTF_8, options);
3040 }
3041
3042 /**
3043 * Copies all bytes from an input stream to a file. On return, the input
3044 * stream will be at end of stream.
3045 *
3046 * <p> By default, the copy fails if the target file already exists or is a
3047 * symbolic link. If the {@link StandardCopyOption#REPLACE_EXISTING
3048 * REPLACE_EXISTING} option is specified, and the target file already exists,
3049 * then it is replaced if it is not a non-empty directory. If the target
3050 * file exists and is a symbolic link, then the symbolic link is replaced.
3051 * In this release, the {@code REPLACE_EXISTING} option is the only option
3052 * required to be supported by this method. Additional options may be
3053 * supported in future releases.
3054 *
3055 * <p> If an I/O error occurs reading from the input stream or writing to
3056 * the file, then it may do so after the target file has been created and
3057 * after some bytes have been read or written. Consequently the input
3058 * stream may not be at end of stream and may be in an inconsistent state.
3059 * It is strongly recommended that the input stream be promptly closed if an
3288 * <p> This method is equivalent to:
3289 * {@code readString(path, StandardCharsets.UTF_8) }
3290 *
3291 * @param path the path to the file
3292 *
3293 * @return a String containing the content read from the file
3294 *
3295 * @throws IOException
3296 * if an I/O error occurs reading from the file or a malformed or
3297 * unmappable byte sequence is read
3298 * @throws OutOfMemoryError
3299 * if the file is extremely large, for example larger than {@code 2GB}
3300 * @throws SecurityException
3301 * In the case of the default provider, and a security manager is
3302 * installed, the {@link SecurityManager#checkRead(String) checkRead}
3303 * method is invoked to check read access to the file.
3304 *
3305 * @since 11
3306 */
3307 public static String readString(Path path) throws IOException {
3308 return readString(path, StandardCharsets.UTF_8);
3309 }
3310
3311 /**
3312 * Reads all characters from a file into a string, decoding from bytes to characters
3313 * using the specified {@linkplain Charset charset}.
3314 * The method ensures that the file is closed when all content have been read
3315 * or an I/O error, or other runtime exception, is thrown.
3316 *
3317 * <p> This method reads all content including the line separators in the middle
3318 * and/or at the end. The resulting string will contain line separators as they
3319 * appear in the file.
3320 *
3321 * @apiNote
3322 * This method is intended for simple cases where it is appropriate and convenient
3323 * to read the content of a file into a String. It is not intended for reading
3324 * very large files.
3325 *
3326 *
3327 *
3328 * @param path the path to the file
3413 * }</pre>
3414 *
3415 * @param path
3416 * the path to the file
3417 *
3418 * @return the lines from the file as a {@code List}; whether the {@code
3419 * List} is modifiable or not is implementation dependent and
3420 * therefore not specified
3421 *
3422 * @throws IOException
3423 * if an I/O error occurs reading from the file or a malformed or
3424 * unmappable byte sequence is read
3425 * @throws SecurityException
3426 * In the case of the default provider, and a security manager is
3427 * installed, the {@link SecurityManager#checkRead(String) checkRead}
3428 * method is invoked to check read access to the file.
3429 *
3430 * @since 1.8
3431 */
3432 public static List<String> readAllLines(Path path) throws IOException {
3433 return readAllLines(path, StandardCharsets.UTF_8);
3434 }
3435
3436 /**
3437 * Writes bytes to a file. The {@code options} parameter specifies how
3438 * the file is created or opened. If no options are present then this method
3439 * works as if the {@link StandardOpenOption#CREATE CREATE}, {@link
3440 * StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING}, and {@link
3441 * StandardOpenOption#WRITE WRITE} options are present. In other words, it
3442 * opens the file for writing, creating the file if it doesn't exist, or
3443 * initially truncating an existing {@link #isRegularFile regular-file} to
3444 * a size of {@code 0}. All bytes in the byte array are written to the file.
3445 * The method ensures that the file is closed when all bytes have been
3446 * written (or an I/O error or other runtime exception is thrown). If an I/O
3447 * error occurs then it may do so after the file has been created or
3448 * truncated, or after some bytes have been written to the file.
3449 *
3450 * <p> <b>Usage example</b>: By default the method creates a new file or
3451 * overwrites an existing file. Suppose you instead want to append bytes
3452 * to an existing file:
3453 * <pre>
3584 * @throws IOException
3585 * if an I/O error occurs writing to or creating the file, or the
3586 * text cannot be encoded as {@code UTF-8}
3587 * @throws UnsupportedOperationException
3588 * if an unsupported option is specified
3589 * @throws SecurityException
3590 * In the case of the default provider, and a security manager is
3591 * installed, the {@link SecurityManager#checkWrite(String) checkWrite}
3592 * method is invoked to check write access to the file. The {@link
3593 * SecurityManager#checkDelete(String) checkDelete} method is
3594 * invoked to check delete access if the file is opened with the
3595 * {@code DELETE_ON_CLOSE} option.
3596 *
3597 * @since 1.8
3598 */
3599 public static Path write(Path path,
3600 Iterable<? extends CharSequence> lines,
3601 OpenOption... options)
3602 throws IOException
3603 {
3604 return write(path, lines, StandardCharsets.UTF_8, options);
3605 }
3606
3607 /**
3608 * Write a {@linkplain java.lang.CharSequence CharSequence} to a file.
3609 * Characters are encoded into bytes using the
3610 * {@link StandardCharsets#UTF_8 UTF-8} {@link Charset charset}.
3611 *
3612 * <p> This method is equivalent to:
3613 * {@code writeString(path, test, StandardCharsets.UTF_8, options) }
3614 *
3615 * @param path
3616 * the path to the file
3617 * @param csq
3618 * the CharSequence to be written
3619 * @param options
3620 * options specifying how the file is opened
3621 *
3622 * @return the path
3623 *
3624 * @throws IllegalArgumentException
3625 * if {@code options} contains an invalid combination of options
3626 * @throws IOException
3627 * if an I/O error occurs writing to or creating the file, or the
3628 * text cannot be encoded using the specified charset
3629 * @throws UnsupportedOperationException
3630 * if an unsupported option is specified
3631 * @throws SecurityException
3632 * In the case of the default provider, and a security manager is
3633 * installed, the {@link SecurityManager#checkWrite(String) checkWrite}
3634 * method is invoked to check write access to the file. The {@link
3635 * SecurityManager#checkDelete(String) checkDelete} method is
3636 * invoked to check delete access if the file is opened with the
3637 * {@code DELETE_ON_CLOSE} option.
3638 *
3639 * @since 11
3640 */
3641 public static Path writeString(Path path, CharSequence csq, OpenOption... options)
3642 throws IOException
3643 {
3644 return writeString(path, csq, StandardCharsets.UTF_8, options);
3645 }
3646
3647 /**
3648 * Write a {@linkplain java.lang.CharSequence CharSequence} to a file.
3649 * Characters are encoded into bytes using the specified
3650 * {@linkplain java.nio.charset.Charset charset}.
3651 *
3652 * <p> All characters are written as they are, including the line separators in
3653 * the char sequence. No extra characters are added.
3654 *
3655 * <p> The {@code options} parameter specifies how the file is created
3656 * or opened. If no options are present then this method works as if the
3657 * {@link StandardOpenOption#CREATE CREATE}, {@link
3658 * StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING}, and {@link
3659 * StandardOpenOption#WRITE WRITE} options are present. In other words, it
3660 * opens the file for writing, creating the file if it doesn't exist, or
3661 * initially truncating an existing {@link #isRegularFile regular-file} to
3662 * a size of {@code 0}.
3663 *
3664 *
4171 * @apiNote
4172 * This method must be used within a try-with-resources statement or similar
4173 * control structure to ensure that the stream's open file is closed promptly
4174 * after the stream's operations have completed.
4175 *
4176 * @param path
4177 * the path to the file
4178 *
4179 * @return the lines from the file as a {@code Stream}
4180 *
4181 * @throws IOException
4182 * if an I/O error occurs opening the file
4183 * @throws SecurityException
4184 * In the case of the default provider, and a security manager is
4185 * installed, the {@link SecurityManager#checkRead(String) checkRead}
4186 * method is invoked to check read access to the file.
4187 *
4188 * @since 1.8
4189 */
4190 public static Stream<String> lines(Path path) throws IOException {
4191 return lines(path, StandardCharsets.UTF_8);
4192 }
4193 }
|
62 import java.security.PrivilegedAction;
63 import java.util.ArrayList;
64 import java.util.Arrays;
65 import java.util.Collections;
66 import java.util.EnumSet;
67 import java.util.HashSet;
68 import java.util.Iterator;
69 import java.util.List;
70 import java.util.Map;
71 import java.util.Objects;
72 import java.util.ServiceLoader;
73 import java.util.Set;
74 import java.util.Spliterator;
75 import java.util.Spliterators;
76 import java.util.function.BiPredicate;
77 import java.util.stream.Stream;
78 import java.util.stream.StreamSupport;
79
80 import jdk.internal.util.ArraysSupport;
81 import sun.nio.ch.FileChannelImpl;
82 import sun.nio.cs.UTF_8;
83 import sun.nio.fs.AbstractFileSystemProvider;
84
85 /**
86 * This class consists exclusively of static methods that operate on files,
87 * directories, or other types of files.
88 *
89 * <p> In most cases, the methods defined here will delegate to the associated
90 * file system provider to perform the file operations.
91 *
92 * @since 1.7
93 */
94
95 public final class Files {
96 // buffer size used for reading and writing
97 private static final int BUFFER_SIZE = 8192;
98
99 private Files() { }
100
101 /**
102 * Returns the {@code FileSystemProvider} to delegate to.
2928 * <pre>{@code
2929 * Files.newBufferedReader(path, StandardCharsets.UTF_8)
2930 * }</pre>
2931 *
2932 * @param path
2933 * the path to the file
2934 *
2935 * @return a new buffered reader, with default buffer size, to read text
2936 * from the file
2937 *
2938 * @throws IOException
2939 * if an I/O error occurs opening the file
2940 * @throws SecurityException
2941 * In the case of the default provider, and a security manager is
2942 * installed, the {@link SecurityManager#checkRead(String) checkRead}
2943 * method is invoked to check read access to the file.
2944 *
2945 * @since 1.8
2946 */
2947 public static BufferedReader newBufferedReader(Path path) throws IOException {
2948 return newBufferedReader(path, UTF_8.INSTANCE);
2949 }
2950
2951 /**
2952 * Opens or creates a file for writing, returning a {@code BufferedWriter}
2953 * that may be used to write text to the file in an efficient manner.
2954 * The {@code options} parameter specifies how the file is created or
2955 * opened. If no options are present then this method works as if the {@link
2956 * StandardOpenOption#CREATE CREATE}, {@link
2957 * StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING}, and {@link
2958 * StandardOpenOption#WRITE WRITE} options are present. In other words, it
2959 * opens the file for writing, creating the file if it doesn't exist, or
2960 * initially truncating an existing {@link #isRegularFile regular-file} to
2961 * a size of {@code 0} if it exists.
2962 *
2963 * <p> The {@code Writer} methods to write text throw {@code IOException}
2964 * if the text cannot be encoded using the specified charset.
2965 *
2966 * @param path
2967 * the path to the file
2968 * @param cs
3020 *
3021 * @throws IllegalArgumentException
3022 * if {@code options} contains an invalid combination of options
3023 * @throws IOException
3024 * if an I/O error occurs opening or creating the file
3025 * @throws UnsupportedOperationException
3026 * if an unsupported option is specified
3027 * @throws SecurityException
3028 * In the case of the default provider, and a security manager is
3029 * installed, the {@link SecurityManager#checkWrite(String) checkWrite}
3030 * method is invoked to check write access to the file. The {@link
3031 * SecurityManager#checkDelete(String) checkDelete} method is
3032 * invoked to check delete access if the file is opened with the
3033 * {@code DELETE_ON_CLOSE} option.
3034 *
3035 * @since 1.8
3036 */
3037 public static BufferedWriter newBufferedWriter(Path path, OpenOption... options)
3038 throws IOException
3039 {
3040 return newBufferedWriter(path, UTF_8.INSTANCE, options);
3041 }
3042
3043 /**
3044 * Copies all bytes from an input stream to a file. On return, the input
3045 * stream will be at end of stream.
3046 *
3047 * <p> By default, the copy fails if the target file already exists or is a
3048 * symbolic link. If the {@link StandardCopyOption#REPLACE_EXISTING
3049 * REPLACE_EXISTING} option is specified, and the target file already exists,
3050 * then it is replaced if it is not a non-empty directory. If the target
3051 * file exists and is a symbolic link, then the symbolic link is replaced.
3052 * In this release, the {@code REPLACE_EXISTING} option is the only option
3053 * required to be supported by this method. Additional options may be
3054 * supported in future releases.
3055 *
3056 * <p> If an I/O error occurs reading from the input stream or writing to
3057 * the file, then it may do so after the target file has been created and
3058 * after some bytes have been read or written. Consequently the input
3059 * stream may not be at end of stream and may be in an inconsistent state.
3060 * It is strongly recommended that the input stream be promptly closed if an
3289 * <p> This method is equivalent to:
3290 * {@code readString(path, StandardCharsets.UTF_8) }
3291 *
3292 * @param path the path to the file
3293 *
3294 * @return a String containing the content read from the file
3295 *
3296 * @throws IOException
3297 * if an I/O error occurs reading from the file or a malformed or
3298 * unmappable byte sequence is read
3299 * @throws OutOfMemoryError
3300 * if the file is extremely large, for example larger than {@code 2GB}
3301 * @throws SecurityException
3302 * In the case of the default provider, and a security manager is
3303 * installed, the {@link SecurityManager#checkRead(String) checkRead}
3304 * method is invoked to check read access to the file.
3305 *
3306 * @since 11
3307 */
3308 public static String readString(Path path) throws IOException {
3309 return readString(path, UTF_8.INSTANCE);
3310 }
3311
3312 /**
3313 * Reads all characters from a file into a string, decoding from bytes to characters
3314 * using the specified {@linkplain Charset charset}.
3315 * The method ensures that the file is closed when all content have been read
3316 * or an I/O error, or other runtime exception, is thrown.
3317 *
3318 * <p> This method reads all content including the line separators in the middle
3319 * and/or at the end. The resulting string will contain line separators as they
3320 * appear in the file.
3321 *
3322 * @apiNote
3323 * This method is intended for simple cases where it is appropriate and convenient
3324 * to read the content of a file into a String. It is not intended for reading
3325 * very large files.
3326 *
3327 *
3328 *
3329 * @param path the path to the file
3414 * }</pre>
3415 *
3416 * @param path
3417 * the path to the file
3418 *
3419 * @return the lines from the file as a {@code List}; whether the {@code
3420 * List} is modifiable or not is implementation dependent and
3421 * therefore not specified
3422 *
3423 * @throws IOException
3424 * if an I/O error occurs reading from the file or a malformed or
3425 * unmappable byte sequence is read
3426 * @throws SecurityException
3427 * In the case of the default provider, and a security manager is
3428 * installed, the {@link SecurityManager#checkRead(String) checkRead}
3429 * method is invoked to check read access to the file.
3430 *
3431 * @since 1.8
3432 */
3433 public static List<String> readAllLines(Path path) throws IOException {
3434 return readAllLines(path, UTF_8.INSTANCE);
3435 }
3436
3437 /**
3438 * Writes bytes to a file. The {@code options} parameter specifies how
3439 * the file is created or opened. If no options are present then this method
3440 * works as if the {@link StandardOpenOption#CREATE CREATE}, {@link
3441 * StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING}, and {@link
3442 * StandardOpenOption#WRITE WRITE} options are present. In other words, it
3443 * opens the file for writing, creating the file if it doesn't exist, or
3444 * initially truncating an existing {@link #isRegularFile regular-file} to
3445 * a size of {@code 0}. All bytes in the byte array are written to the file.
3446 * The method ensures that the file is closed when all bytes have been
3447 * written (or an I/O error or other runtime exception is thrown). If an I/O
3448 * error occurs then it may do so after the file has been created or
3449 * truncated, or after some bytes have been written to the file.
3450 *
3451 * <p> <b>Usage example</b>: By default the method creates a new file or
3452 * overwrites an existing file. Suppose you instead want to append bytes
3453 * to an existing file:
3454 * <pre>
3585 * @throws IOException
3586 * if an I/O error occurs writing to or creating the file, or the
3587 * text cannot be encoded as {@code UTF-8}
3588 * @throws UnsupportedOperationException
3589 * if an unsupported option is specified
3590 * @throws SecurityException
3591 * In the case of the default provider, and a security manager is
3592 * installed, the {@link SecurityManager#checkWrite(String) checkWrite}
3593 * method is invoked to check write access to the file. The {@link
3594 * SecurityManager#checkDelete(String) checkDelete} method is
3595 * invoked to check delete access if the file is opened with the
3596 * {@code DELETE_ON_CLOSE} option.
3597 *
3598 * @since 1.8
3599 */
3600 public static Path write(Path path,
3601 Iterable<? extends CharSequence> lines,
3602 OpenOption... options)
3603 throws IOException
3604 {
3605 return write(path, lines, UTF_8.INSTANCE, options);
3606 }
3607
3608 /**
3609 * Write a {@linkplain java.lang.CharSequence CharSequence} to a file.
3610 * Characters are encoded into bytes using the
3611 * {@link StandardCharsets#UTF_8 UTF-8} {@link Charset charset}.
3612 *
3613 * <p> This method is equivalent to:
3614 * {@code writeString(path, test, StandardCharsets.UTF_8, options) }
3615 *
3616 * @param path
3617 * the path to the file
3618 * @param csq
3619 * the CharSequence to be written
3620 * @param options
3621 * options specifying how the file is opened
3622 *
3623 * @return the path
3624 *
3625 * @throws IllegalArgumentException
3626 * if {@code options} contains an invalid combination of options
3627 * @throws IOException
3628 * if an I/O error occurs writing to or creating the file, or the
3629 * text cannot be encoded using the specified charset
3630 * @throws UnsupportedOperationException
3631 * if an unsupported option is specified
3632 * @throws SecurityException
3633 * In the case of the default provider, and a security manager is
3634 * installed, the {@link SecurityManager#checkWrite(String) checkWrite}
3635 * method is invoked to check write access to the file. The {@link
3636 * SecurityManager#checkDelete(String) checkDelete} method is
3637 * invoked to check delete access if the file is opened with the
3638 * {@code DELETE_ON_CLOSE} option.
3639 *
3640 * @since 11
3641 */
3642 public static Path writeString(Path path, CharSequence csq, OpenOption... options)
3643 throws IOException
3644 {
3645 return writeString(path, csq, UTF_8.INSTANCE, options);
3646 }
3647
3648 /**
3649 * Write a {@linkplain java.lang.CharSequence CharSequence} to a file.
3650 * Characters are encoded into bytes using the specified
3651 * {@linkplain java.nio.charset.Charset charset}.
3652 *
3653 * <p> All characters are written as they are, including the line separators in
3654 * the char sequence. No extra characters are added.
3655 *
3656 * <p> The {@code options} parameter specifies how the file is created
3657 * or opened. If no options are present then this method works as if the
3658 * {@link StandardOpenOption#CREATE CREATE}, {@link
3659 * StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING}, and {@link
3660 * StandardOpenOption#WRITE WRITE} options are present. In other words, it
3661 * opens the file for writing, creating the file if it doesn't exist, or
3662 * initially truncating an existing {@link #isRegularFile regular-file} to
3663 * a size of {@code 0}.
3664 *
3665 *
4172 * @apiNote
4173 * This method must be used within a try-with-resources statement or similar
4174 * control structure to ensure that the stream's open file is closed promptly
4175 * after the stream's operations have completed.
4176 *
4177 * @param path
4178 * the path to the file
4179 *
4180 * @return the lines from the file as a {@code Stream}
4181 *
4182 * @throws IOException
4183 * if an I/O error occurs opening the file
4184 * @throws SecurityException
4185 * In the case of the default provider, and a security manager is
4186 * installed, the {@link SecurityManager#checkRead(String) checkRead}
4187 * method is invoked to check read access to the file.
4188 *
4189 * @since 1.8
4190 */
4191 public static Stream<String> lines(Path path) throws IOException {
4192 return lines(path, UTF_8.INSTANCE);
4193 }
4194 }
|