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

Print this page
rev 7023 : 8006884: (fs) Add Files.list, lines and find
Reviewed-by:
Contributed-by: alan.bateman@oracle.com, henry.jen@oracle.com


  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.nio.file;
  27 
  28 import java.util.Iterator;
  29 import java.io.Closeable;
  30 import java.io.IOException;




  31 
  32 /**
  33  * An object to iterate over the entries in a directory. A directory stream
  34  * allows for the convenient use of the for-each construct to iterate over a
  35  * directory.
  36  *
  37  * <p> <b> While {@code DirectoryStream} extends {@code Iterable}, it is not a
  38  * general-purpose {@code Iterable} as it supports only a single {@code
  39  * Iterator}; invoking the {@link #iterator iterator} method to obtain a second
  40  * or subsequent iterator throws {@code IllegalStateException}. </b>

  41  *
  42  * <p> An important property of the directory stream's {@code Iterator} is that
  43  * its {@link Iterator#hasNext() hasNext} method is guaranteed to read-ahead by
  44  * at least one element. If {@code hasNext} method returns {@code true}, and is
  45  * followed by a call to the {@code next} method, it is guaranteed that the
  46  * {@code next} method will not throw an exception due to an I/O error, or
  47  * because the stream has been {@link #close closed}. The {@code Iterator} does
  48  * not support the {@link Iterator#remove remove} operation.
  49  *
  50  * <p> A {@code DirectoryStream} is opened upon creation and is closed by
  51  * invoking the {@code close} method. Closing a directory stream releases any
  52  * resources associated with the stream. Failure to close the stream may result
  53  * in a resource leak. The try-with-resources statement provides a useful
  54  * construct to ensure that the stream is closed:
  55  * <pre>
  56  *   Path dir = ...
  57  *   try (DirectoryStream&lt;Path&gt; stream = Files.newDirectoryStream(dir)) {
  58  *       for (Path entry: stream) {
  59  *           ...
  60  *       }
  61  *   }
  62  * </pre>
  63  *
  64  * <p> Once a directory stream is closed, then further access to the directory,
  65  * using the {@code Iterator}, behaves as if the end of stream has been reached.
  66  * Due to read-ahead, the {@code Iterator} may return one or more elements
  67  * after the directory stream has been closed. Once these buffered elements
  68  * have been read, then subsequent calls to the {@code hasNext} method returns
  69  * {@code false}, and subsequent calls to the {@code next} method will throw
  70  * {@code NoSuchElementException}.
  71  *
  72  * <p> A directory stream is not required to be <i>asynchronously closeable</i>.
  73  * If a thread is blocked on the directory stream's iterator reading from the
  74  * directory, and another thread invokes the {@code close} method, then the
  75  * second thread may block until the read operation is complete.
  76  *
  77  * <p> If an I/O error is encountered when accessing the directory then it
  78  * causes the {@code Iterator}'s {@code hasNext} or {@code next} methods to
  79  * throw {@link DirectoryIteratorException} with the {@link IOException} as the
  80  * cause. As stated above, the {@code hasNext} method is guaranteed to
  81  * read-ahead by at least one element. This means that if {@code hasNext} method
  82  * returns {@code true}, and is followed by a call to the {@code next} method,
  83  * then it is guaranteed that the {@code next} method will not fail with a
  84  * {@code DirectoryIteratorException}.

  85  *
  86  * <p> The elements returned by the iterator are in no specific order. Some file
  87  * systems maintain special links to the directory itself and the directory's
  88  * parent directory. Entries representing these links are not returned by the
  89  * iterator.
  90  *
  91  * <p> The iterator is <i>weakly consistent</i>. It is thread safe but does not
  92  * freeze the directory while iterating, so it may (or may not) reflect updates
  93  * to the directory that occur after the {@code DirectoryStream} is created.
  94  *
  95  * <p> <b>Usage Examples:</b>
  96  * Suppose we want a list of the source files in a directory. This example uses
  97  * both the for-each and try-with-resources constructs.
  98  * <pre>
  99  *   List&lt;Path&gt; listSourceFiles(Path dir) throws IOException {
 100  *       List&lt;Path&gt; result = new ArrayList&lt;&gt;();
 101  *       try (DirectoryStream&lt;Path&gt; stream = Files.newDirectoryStream(dir, "*.{c,h,cpp,hpp,java}")) {
 102  *           for (Path entry: stream) {
 103  *               result.add(entry);
 104  *           }


 134         /**
 135          * Decides if the given directory entry should be accepted or filtered.
 136          *
 137          * @param   entry
 138          *          the directory entry to be tested
 139          *
 140          * @return  {@code true} if the directory entry should be accepted
 141          *
 142          * @throws  IOException
 143          *          If an I/O error occurs
 144          */
 145         boolean accept(T entry) throws IOException;
 146     }
 147 
 148     /**
 149      * Returns the iterator associated with this {@code DirectoryStream}.
 150      *
 151      * @return  the iterator associated with this {@code DirectoryStream}
 152      *
 153      * @throws  IllegalStateException
 154      *          if this directory stream is closed or the iterator has already
 155      *          been returned
 156      */
 157     @Override
 158     Iterator<T> iterator();














 159 }


  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.nio.file;
  27 
  28 import java.util.Iterator;
  29 import java.io.Closeable;
  30 import java.io.IOException;
  31 import java.util.Spliterator;
  32 import java.util.Spliterators;
  33 import java.util.stream.Stream;
  34 import java.util.stream.StreamSupport;
  35 
  36 /**
  37  * An object to iterate over the entries in a directory. A directory stream
  38  * allows for the convenient use of the for-each construct or the {@link
  39  * Stream} API to iterate over a directory.
  40  *
  41  * <p> <b> While {@code DirectoryStream} extends {@code Iterable}, it is not a
  42  * general-purpose {@code Iterable}. A {@code DirectoryStream} supports only a
  43  * single iteration via either the {@link #iterator iterator} or the {@link
  44  * #entries entries} method. Invoking either method to do a second or
  45  * subsequent iteration throws {@code IllegalStateException}. </b>
  46  *
  47  * <p> An important property of the directory stream's {@code Iterator} is that
  48  * its {@link Iterator#hasNext() hasNext} method is guaranteed to read-ahead by
  49  * at least one element. If {@code hasNext} method returns {@code true}, and is
  50  * followed by a call to the {@code next} method, it is guaranteed that the
  51  * {@code next} method will not throw an exception due to an I/O error, or
  52  * because the stream has been {@link #close closed}. The {@code Iterator} does
  53  * not support the {@link Iterator#remove remove} operation.
  54  *
  55  * <p> A {@code DirectoryStream} is opened upon creation and is closed by
  56  * invoking the {@code close} method. Closing a directory stream releases any
  57  * resources associated with the stream. Failure to close the stream may result
  58  * in a resource leak. The try-with-resources statement provides a useful
  59  * construct to ensure that the stream is closed:
  60  * <pre>
  61  *   Path dir = ...
  62  *   try (DirectoryStream&lt;Path&gt; stream = Files.newDirectoryStream(dir)) {
  63  *       for (Path entry: stream) {
  64  *           ...
  65  *       }
  66  *   }
  67  * </pre>
  68  *
  69  * <p> Once a directory stream is closed, then further access to the
  70  * directory, using the {@code Iterator} or {@code Stream}, behaves as if the
  71  * end of stream has been reached. Due to read-ahead, one or more elements may
  72  * be returned after the directory stream has been closed. Once these buffered
  73  * elements have been read, then subsequent calls to the {@code hasNext}
  74  * method returns {@code false}, and subsequent calls to the {@code next}
  75  * method will throw {@code NoSuchElementException}.
  76  *
  77  * <p> A directory stream is not required to be <i>asynchronously closeable</i>.
  78  * If a thread is blocked on the directory stream's iterator reading from the
  79  * directory, and another thread invokes the {@code close} method, then the
  80  * second thread may block until the read operation is complete.
  81  *
  82  * <p> If an I/O error is encountered when accessing the directory then it
  83  * causes the methods to throw {@link DirectoryIteratorException} with the
  84  * {@link IOException} as the cause. This could be the {@code Iterator}'s
  85  * {@code hasNext} or {@code next} method or one of the {@code Stream} methods.
  86  * As stated above, the {@code hasNext} method is guaranteed to read-ahead by
  87  * at least one element. This means that if {@code hasNext} method returns
  88  * {@code true}, and is followed by a call to the {@code next} method, then it
  89  * is guaranteed that the {@code next} method will not fail with a {@code
  90  * DirectoryIteratorException}.
  91  *
  92  * <p> The elements returned by the iterator are in no specific order. Some file
  93  * systems maintain special links to the directory itself and the directory's
  94  * parent directory. Entries representing these links are not returned by the
  95  * iterator.
  96  *
  97  * <p> The iterator is <i>weakly consistent</i>. It is thread safe but does not
  98  * freeze the directory while iterating, so it may (or may not) reflect updates
  99  * to the directory that occur after the {@code DirectoryStream} is created.
 100  *
 101  * <p> <b>Usage Examples:</b>
 102  * Suppose we want a list of the source files in a directory. This example uses
 103  * both the for-each and try-with-resources constructs.
 104  * <pre>
 105  *   List&lt;Path&gt; listSourceFiles(Path dir) throws IOException {
 106  *       List&lt;Path&gt; result = new ArrayList&lt;&gt;();
 107  *       try (DirectoryStream&lt;Path&gt; stream = Files.newDirectoryStream(dir, "*.{c,h,cpp,hpp,java}")) {
 108  *           for (Path entry: stream) {
 109  *               result.add(entry);
 110  *           }


 140         /**
 141          * Decides if the given directory entry should be accepted or filtered.
 142          *
 143          * @param   entry
 144          *          the directory entry to be tested
 145          *
 146          * @return  {@code true} if the directory entry should be accepted
 147          *
 148          * @throws  IOException
 149          *          If an I/O error occurs
 150          */
 151         boolean accept(T entry) throws IOException;
 152     }
 153 
 154     /**
 155      * Returns the iterator associated with this {@code DirectoryStream}.
 156      *
 157      * @return  the iterator associated with this {@code DirectoryStream}
 158      *
 159      * @throws  IllegalStateException
 160      *          if this directory stream is closed or the iterator or stream
 161      *          has already been returned
 162      */
 163     @Override
 164     Iterator<T> iterator();
 165 
 166     /**
 167      * Returns the stream associated with this {@code DirectoryStream}.
 168      *
 169      * @return the stream associated with this {@code DirectoryStream}
 170      *
 171      * @throws IllegalStateException
 172      *         if this directory stream is closed or the iterator or stream
 173      *         has already been returned
 174      * @since 1.8
 175      */
 176     default Stream<T> entries() {
 177         return StreamSupport.stream(Spliterators.spliteratorUnknownSize(iterator(), Spliterator.DISTINCT));
 178     }
 179 }