1 /*
2  * Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved.
3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4  *
5  * This code is free software; you can redistribute it and/or modify it
6  * under the terms of the GNU General Public License version 2 only, as
7  * published by the Free Software Foundation.  Oracle designates this
8  * particular file as subject to the "Classpath" exception as provided
9  * by Oracle in the LICENSE file that accompanied this code.
10  *
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  *           }
105  *       } catch (DirectoryIteratorException ex) {
106  *           // I/O error encounted during the iteration, the cause is an IOException
107  *           throw ex.getCause();
108  *       }
109  *       return result;
110  *   }
111  * </pre>
112  * @param   <T>     The type of element returned by the iterator
113  *
114  * @since 1.7
115  *
116  * @see Files#newDirectoryStream(Path)
117  */
118 
119 public interface DirectoryStream<T>
120     extends Closeable, Iterable<T> {
121     /**
122      * An interface that is implemented by objects that decide if a directory
123      * entry should be accepted or filtered. A {@code Filter} is passed as the
124      * parameter to the {@link Files#newDirectoryStream(Path,DirectoryStream.Filter)}
125      * method when opening a directory to iterate over the entries in the
126      * directory.
127      *
128      * @param   <T>     the type of the directory entry
129      *
130      * @since 1.7
131      */
132     @FunctionalInterface
133     public static interface Filter<T> {
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          */
accept(T entry)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
iterator()158     Iterator<T> iterator();
159 }
160