changeset 10919:40166c6c23d9

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
author alanb
date Mon, 03 Nov 2014 15:33:11 +0000
parents 62923b97448a
children 44c35d768412 30c2d576a1be 46e6ae6eaf50
files src/java.base/share/classes/java/nio/file/Files.java src/java.base/share/classes/java/nio/file/package-info.java
diffstat 2 files changed, 32 insertions(+), 12 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.base/share/classes/java/nio/file/Files.java	Fri Oct 31 13:21:51 2014 -0400
+++ b/src/java.base/share/classes/java/nio/file/Files.java	Mon Nov 03 15:33:11 2014 +0000
@@ -303,7 +303,7 @@
      * is a {@link java.nio.channels.FileChannel}.
      *
      * <p> <b>Usage Examples:</b>
-     * <pre>
+     * <pre>{@code
      *     Path path = ...
      *
      *     // open file for reading
@@ -314,9 +314,10 @@
      *     WritableByteChannel wbc = Files.newByteChannel(path, EnumSet.of(CREATE,APPEND));
      *
      *     // create file with initial permissions, opening it for both reading and writing
-     *     {@code FileAttribute<Set<PosixFilePermission>> perms = ...}
-     *     SeekableByteChannel sbc = Files.newByteChannel(path, EnumSet.of(CREATE_NEW,READ,WRITE), perms);
-     * </pre>
+     *     FileAttribute<Set<PosixFilePermission>> perms = ...
+     *     SeekableByteChannel sbc =
+     *         Files.newByteChannel(path, EnumSet.of(CREATE_NEW,READ,WRITE), perms);
+     * }</pre>
      *
      * @param   path
      *          the path to the file to open or create
@@ -1702,7 +1703,8 @@
      * Alternatively, suppose we want to read file's POSIX attributes without
      * following symbolic links:
      * <pre>
-     *    PosixFileAttributes attrs = Files.readAttributes(path, PosixFileAttributes.class, NOFOLLOW_LINKS);
+     *    PosixFileAttributes attrs =
+     *        Files.readAttributes(path, PosixFileAttributes.class, NOFOLLOW_LINKS);
      * </pre>
      *
      * @param   <A>
@@ -2840,6 +2842,8 @@
      * @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 @@
      * @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 @@
      *
      * @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 @@
      *
      * @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 @@
      *
      * @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 @@
      *
      * @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 @@
             final Iterator<Path> delegate = ds.iterator();
 
             // Re-wrap DirectoryIteratorException to UncheckedIOException
-            Iterator<Path> it = new Iterator<Path>() {
+            Iterator<Path> iterator = new Iterator<Path>() {
                 @Override
                 public boolean hasNext() {
                     try {
@@ -3471,7 +3485,9 @@
                 }
             };
 
-            return StreamSupport.stream(Spliterators.spliteratorUnknownSize(it, Spliterator.DISTINCT), false)
+            Spliterator<Path> spliterator =
+                Spliterators.spliteratorUnknownSize(iterator, Spliterator.DISTINCT);
+            return StreamSupport.stream(spliterator, false)
                                 .onClose(asUncheckedRunnable(ds));
         } catch (Error|RuntimeException e) {
             try {
@@ -3572,7 +3588,9 @@
     {
         FileTreeIterator iterator = new FileTreeIterator(start, maxDepth, options);
         try {
-            return StreamSupport.stream(Spliterators.spliteratorUnknownSize(iterator, Spliterator.DISTINCT), false)
+            Spliterator<FileTreeWalker.Event> 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 @@
     {
         FileTreeIterator iterator = new FileTreeIterator(start, maxDepth, options);
         try {
-            return StreamSupport.stream(Spliterators.spliteratorUnknownSize(iterator, Spliterator.DISTINCT), false)
+            Spliterator<FileTreeWalker.Event> 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());
--- a/src/java.base/share/classes/java/nio/file/package-info.java	Fri Oct 31 13:21:51 2014 -0400
+++ b/src/java.base/share/classes/java/nio/file/package-info.java	Mon Nov 03 15:33:11 2014 +0000
@@ -86,8 +86,8 @@
  * <p> 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. </p>
+ * invoking a method with an array or collection containing a {@code null} element
+ * will cause a {@code NullPointerException}, unless otherwise specified. </p>
  *
  * <p> Unless otherwise noted, methods that attempt to access the file system
  * will throw {@link java.nio.file.ClosedFileSystemException} when invoked on