src/share/classes/java/nio/file/DirectoryStream.java

rev 7173 : [mq]: nio.diff

@@ -1,7 +1,7 @@
 /*
- * Copyright (c) 2007, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this

@@ -26,20 +26,23 @@
 package java.nio.file;
 
 import java.util.Iterator;
 import java.io.Closeable;
 import java.io.IOException;
+import java.util.stream.Stream;
+import java.util.stream.Streams;
 
 /**
  * An object to iterate over the entries in a directory. A directory stream
- * allows for the convenient use of the for-each construct to iterate over a
- * directory.
+ * allows for the convenient use of the for-each construct or the {@link
+ * Stream} API to iterate over a directory.
  *
  * <p> <b> While {@code DirectoryStream} extends {@code Iterable}, it is not a
- * general-purpose {@code Iterable} as it supports only a single {@code
- * Iterator}; invoking the {@link #iterator iterator} method to obtain a second
- * or subsequent iterator throws {@code IllegalStateException}. </b>
+ * general-purpose {@code Iterable}. A {@code DirectoryStream} supports only a
+ * single iteration via either the {@link #iterator iterator} or the {@link
+ * #entries entries} method. Invoking either method to do a second or
+ * subsequent iteration throws {@code IllegalStateException}. </b>
  *
  * <p> An important property of the directory stream's {@code Iterator} is that
  * its {@link Iterator#hasNext() hasNext} method is guaranteed to read-ahead by
  * at least one element. If {@code hasNext} method returns {@code true}, and is
  * followed by a call to the {@code next} method, it is guaranteed that the

@@ -59,31 +62,32 @@
  *           ...
  *       }
  *   }
  * </pre>
  *
- * <p> Once a directory stream is closed, then further access to the directory,
- * using the {@code Iterator}, behaves as if the end of stream has been reached.
- * Due to read-ahead, the {@code Iterator} may return one or more elements
- * after the directory stream has been closed. Once these buffered elements
- * have been read, then subsequent calls to the {@code hasNext} method returns
- * {@code false}, and subsequent calls to the {@code next} method will throw
- * {@code NoSuchElementException}.
+ * <p> Once a directory stream is closed, then further access to the
+ * directory, using the {@code Iterator} or {@code Stream}, behaves as if the
+ * end of stream has been reached. Due to read-ahead, one or more elements may
+ * be returned after the directory stream has been closed. Once these buffered
+ * elements have been read, then subsequent calls to the {@code hasNext}
+ * method returns {@code false}, and subsequent calls to the {@code next}
+ * method will throw {@code NoSuchElementException}.
  *
  * <p> A directory stream is not required to be <i>asynchronously closeable</i>.
  * If a thread is blocked on the directory stream's iterator reading from the
  * directory, and another thread invokes the {@code close} method, then the
  * second thread may block until the read operation is complete.
  *
  * <p> If an I/O error is encountered when accessing the directory then it
- * causes the {@code Iterator}'s {@code hasNext} or {@code next} methods to
- * throw {@link DirectoryIteratorException} with the {@link IOException} as the
- * cause. As stated above, the {@code hasNext} method is guaranteed to
- * read-ahead by at least one element. This means that if {@code hasNext} method
- * returns {@code true}, and is followed by a call to the {@code next} method,
- * then it is guaranteed that the {@code next} method will not fail with a
- * {@code DirectoryIteratorException}.
+ * causes the methods to throw {@link DirectoryIteratorException} with the
+ * {@link IOException} as the cause. This could be the {@code Iterator}'s
+ * {@code hasNext} or {@code next} method or one of the {@code Stream} methods.
+ * As stated above, the {@code hasNext} method is guaranteed to read-ahead by
+ * at least one element. This means that if {@code hasNext} method returns
+ * {@code true}, and is followed by a call to the {@code next} method, then it
+ * is guaranteed that the {@code next} method will not fail with a {@code
+ * DirectoryIteratorException}.
  *
  * <p> The elements returned by the iterator are in no specific order. Some file
  * systems maintain special links to the directory itself and the directory's
  * parent directory. Entries representing these links are not returned by the
  * iterator.

@@ -149,11 +153,26 @@
      * Returns the iterator associated with this {@code DirectoryStream}.
      *
      * @return  the iterator associated with this {@code DirectoryStream}
      *
      * @throws  IllegalStateException
-     *          if this directory stream is closed or the iterator has already
-     *          been returned
+     *          if this directory stream is closed or the iterator or stream
+     *          has already been returned
      */
     @Override
     Iterator<T> iterator();
+
+    /**
+     * Returns the stream associated with this {@code DirectoryStream}.
+     *
+     * @return the stream associated with this {@code DirectoryStream}
+     *
+     * @throws IllegalStateException
+     *         if this directory stream is closed or the iterator or stream
+     *         has already been returned
+     * @since 1.8
+     */
+    default Stream<T> entries() {
+        return Streams.stream(Streams.spliteratorUnknownSize(iterator()),
+                              Streams.STREAM_IS_DISTINCT);
+    }
 }