From 5598ed0cf0261a1eed6afda856093fcd60184bf9 Mon Sep 17 00:00:00 2001 From: Alan Bateman Date: Mon, 3 Nov 2014 15:33:11 +0000 Subject: [PATCH] 8062632: (fs spec) Package description could be clearer on the cases where NPE is thrown 8062553: (fs spec) Files.write and newBufferedWriter methods missing @throws IAE Reviewed-by: dfuchs --- .../share/classes/java/nio/file/Files.java | 40 ++++++++++++++----- .../classes/java/nio/file/package-info.java | 4 +- 2 files changed, 32 insertions(+), 12 deletions(-) diff --git a/jdk/src/java.base/share/classes/java/nio/file/Files.java b/jdk/src/java.base/share/classes/java/nio/file/Files.java index ba18b6c9e30..18ef214e9a0 100644 --- a/jdk/src/java.base/share/classes/java/nio/file/Files.java +++ b/jdk/src/java.base/share/classes/java/nio/file/Files.java @@ -303,7 +303,7 @@ public final class Files { * is a {@link java.nio.channels.FileChannel}. * *

Usage Examples: - * 

+     * 
{@code
      *     Path path = ...
      *
      *     // open file for reading
@@ -314,9 +314,10 @@ public final class Files {
      *     WritableByteChannel wbc = Files.newByteChannel(path, EnumSet.of(CREATE,APPEND));
      *
      *     // create file with initial permissions, opening it for both reading and writing
-     *     {@code FileAttribute> perms = ...}
-     *     SeekableByteChannel sbc = Files.newByteChannel(path, EnumSet.of(CREATE_NEW,READ,WRITE), perms);
-     * 

+     *     FileAttribute> perms = ...
+     *     SeekableByteChannel sbc =
+     *         Files.newByteChannel(path, EnumSet.of(CREATE_NEW,READ,WRITE), perms);
+     * }
* * @param path * the path to the file to open or create @@ -1702,7 +1703,8 @@ public final class Files { * Alternatively, suppose we want to read file's POSIX attributes without * following symbolic links: * 
-     *    PosixFileAttributes attrs = Files.readAttributes(path, PosixFileAttributes.class, NOFOLLOW_LINKS);
+     *    PosixFileAttributes attrs =
+     *        Files.readAttributes(path, PosixFileAttributes.class, NOFOLLOW_LINKS);
      *
* * @param @@ -2840,6 +2842,8 @@ public final class Files { * @return a new buffered writer, with default buffer size, to write text * to the file * + * @throws IllegalArgumentException + * if {@code options} contains an invalid combination of options * @throws IOException * if an I/O error occurs opening or creating the file * @throws UnsupportedOperationException @@ -2880,6 +2884,8 @@ public final class Files { * @return a new buffered writer, with default buffer size, to write text * to the file * + * @throws IllegalArgumentException + * if {@code options} contains an invalid combination of options * @throws IOException * if an I/O error occurs opening or creating the file * @throws UnsupportedOperationException @@ -2891,7 +2897,9 @@ public final class Files { * * @since 1.8 */ - public static BufferedWriter newBufferedWriter(Path path, OpenOption... options) throws IOException { + public static BufferedWriter newBufferedWriter(Path path, OpenOption... options) + throws IOException + { return newBufferedWriter(path, StandardCharsets.UTF_8, options); } @@ -3273,6 +3281,8 @@ public final class Files { * * @return the path * + * @throws IllegalArgumentException + * if {@code options} contains an invalid combination of options * @throws IOException * if an I/O error occurs writing to or creating the file * @throws UnsupportedOperationException @@ -3330,6 +3340,8 @@ public final class Files { * * @return the path * + * @throws IllegalArgumentException + * if {@code options} contains an invalid combination of options * @throws IOException * if an I/O error occurs writing to or creating the file, or the * text cannot be encoded using the specified charset @@ -3376,6 +3388,8 @@ public final class Files { * * @return the path * + * @throws IllegalArgumentException + * if {@code options} contains an invalid combination of options * @throws IOException * if an I/O error occurs writing to or creating the file, or the * text cannot be encoded as {@code UTF-8} @@ -3452,7 +3466,7 @@ public final class Files { final Iterator delegate = ds.iterator(); // Re-wrap DirectoryIteratorException to UncheckedIOException - Iterator it = new Iterator() { + Iterator iterator = new Iterator() { @Override public boolean hasNext() { try { @@ -3471,7 +3485,9 @@ public final class Files { } }; - return StreamSupport.stream(Spliterators.spliteratorUnknownSize(it, Spliterator.DISTINCT), false) + Spliterator spliterator = + Spliterators.spliteratorUnknownSize(iterator, Spliterator.DISTINCT); + return StreamSupport.stream(spliterator, false) .onClose(asUncheckedRunnable(ds)); } catch (Error|RuntimeException e) { try { @@ -3572,7 +3588,9 @@ public final class Files { { FileTreeIterator iterator = new FileTreeIterator(start, maxDepth, options); try { - return StreamSupport.stream(Spliterators.spliteratorUnknownSize(iterator, Spliterator.DISTINCT), false) + Spliterator spliterator = + Spliterators.spliteratorUnknownSize(iterator, Spliterator.DISTINCT); + return StreamSupport.stream(spliterator, false) .onClose(iterator::close) .map(entry -> entry.file()); } catch (Error|RuntimeException e) { @@ -3685,7 +3703,9 @@ public final class Files { { FileTreeIterator iterator = new FileTreeIterator(start, maxDepth, options); try { - return StreamSupport.stream(Spliterators.spliteratorUnknownSize(iterator, Spliterator.DISTINCT), false) + Spliterator spliterator = + Spliterators.spliteratorUnknownSize(iterator, Spliterator.DISTINCT); + return StreamSupport.stream(spliterator, false) .onClose(iterator::close) .filter(entry -> matcher.test(entry.file(), entry.attributes())) .map(entry -> entry.file()); diff --git a/jdk/src/java.base/share/classes/java/nio/file/package-info.java b/jdk/src/java.base/share/classes/java/nio/file/package-info.java index ca3e946d567..556df2b8c6a 100644 --- a/jdk/src/java.base/share/classes/java/nio/file/package-info.java +++ b/jdk/src/java.base/share/classes/java/nio/file/package-info.java @@ -86,8 +86,8 @@ *

Unless otherwise noted, passing a {@code null} argument to a constructor * or method of any class or interface in this package will cause a {@link * java.lang.NullPointerException NullPointerException} to be thrown. Additionally, - * invoking a method with a collection containing a {@code null} element will - * cause a {@code NullPointerException}, unless otherwise specified.

+ * invoking a method with an array or collection containing a {@code null} element + * will cause a {@code NullPointerException}, unless otherwise specified.

* *

Unless otherwise noted, methods that attempt to access the file system * will throw {@link java.nio.file.ClosedFileSystemException} when invoked on