1 /*
2 * Copyright (c) 2007, 2011, 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<Path> 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<Path> listSourceFiles(Path dir) throws IOException {
100 * List<Path> result = new ArrayList<>();
101 * try (DirectoryStream<Path> 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 }
|
1 /*
2 * Copyright (c) 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 import java.util.stream.Stream;
32 import java.util.stream.Streams;
33
34 /**
35 * An object to iterate over the entries in a directory. A directory stream
36 * allows for the convenient use of the for-each construct or the {@link
37 * Stream} API to iterate over a directory.
38 *
39 * <p> <b> While {@code DirectoryStream} extends {@code Iterable}, it is not a
40 * general-purpose {@code Iterable}. A {@code DirectoryStream} supports only a
41 * single iteration via either the {@link #iterator iterator} or the {@link
42 * #entries entries} method. Invoking either method to do a second or
43 * subsequent iteration throws {@code IllegalStateException}. </b>
44 *
45 * <p> An important property of the directory stream's {@code Iterator} is that
46 * its {@link Iterator#hasNext() hasNext} method is guaranteed to read-ahead by
47 * at least one element. If {@code hasNext} method returns {@code true}, and is
48 * followed by a call to the {@code next} method, it is guaranteed that the
49 * {@code next} method will not throw an exception due to an I/O error, or
50 * because the stream has been {@link #close closed}. The {@code Iterator} does
51 * not support the {@link Iterator#remove remove} operation.
52 *
53 * <p> A {@code DirectoryStream} is opened upon creation and is closed by
54 * invoking the {@code close} method. Closing a directory stream releases any
55 * resources associated with the stream. Failure to close the stream may result
56 * in a resource leak. The try-with-resources statement provides a useful
57 * construct to ensure that the stream is closed:
58 * <pre>
59 * Path dir = ...
60 * try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir)) {
61 * for (Path entry: stream) {
62 * ...
63 * }
64 * }
65 * </pre>
66 *
67 * <p> Once a directory stream is closed, then further access to the
68 * directory, using the {@code Iterator} or {@code Stream}, behaves as if the
69 * end of stream has been reached. Due to read-ahead, one or more elements may
70 * be returned after the directory stream has been closed. Once these buffered
71 * elements have been read, then subsequent calls to the {@code hasNext}
72 * method returns {@code false}, and subsequent calls to the {@code next}
73 * method will throw {@code NoSuchElementException}.
74 *
75 * <p> A directory stream is not required to be <i>asynchronously closeable</i>.
76 * If a thread is blocked on the directory stream's iterator reading from the
77 * directory, and another thread invokes the {@code close} method, then the
78 * second thread may block until the read operation is complete.
79 *
80 * <p> If an I/O error is encountered when accessing the directory then it
81 * causes the methods to throw {@link DirectoryIteratorException} with the
82 * {@link IOException} as the cause. This could be the {@code Iterator}'s
83 * {@code hasNext} or {@code next} method or one of the {@code Stream} methods.
84 * As stated above, the {@code hasNext} method is guaranteed to read-ahead by
85 * at least one element. This means that if {@code hasNext} method returns
86 * {@code true}, and is followed by a call to the {@code next} method, then it
87 * is guaranteed that the {@code next} method will not fail with a {@code
88 * DirectoryIteratorException}.
89 *
90 * <p> The elements returned by the iterator are in no specific order. Some file
91 * systems maintain special links to the directory itself and the directory's
92 * parent directory. Entries representing these links are not returned by the
93 * iterator.
94 *
95 * <p> The iterator is <i>weakly consistent</i>. It is thread safe but does not
96 * freeze the directory while iterating, so it may (or may not) reflect updates
97 * to the directory that occur after the {@code DirectoryStream} is created.
98 *
99 * <p> <b>Usage Examples:</b>
100 * Suppose we want a list of the source files in a directory. This example uses
101 * both the for-each and try-with-resources constructs.
102 * <pre>
103 * List<Path> listSourceFiles(Path dir) throws IOException {
104 * List<Path> result = new ArrayList<>();
105 * try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir, "*.{c,h,cpp,hpp,java}")) {
106 * for (Path entry: stream) {
107 * result.add(entry);
108 * }
138 /**
139 * Decides if the given directory entry should be accepted or filtered.
140 *
141 * @param entry
142 * the directory entry to be tested
143 *
144 * @return {@code true} if the directory entry should be accepted
145 *
146 * @throws IOException
147 * If an I/O error occurs
148 */
149 boolean accept(T entry) throws IOException;
150 }
151
152 /**
153 * Returns the iterator associated with this {@code DirectoryStream}.
154 *
155 * @return the iterator associated with this {@code DirectoryStream}
156 *
157 * @throws IllegalStateException
158 * if this directory stream is closed or the iterator or stream
159 * has already been returned
160 */
161 @Override
162 Iterator<T> iterator();
163
164 /**
165 * Returns the stream associated with this {@code DirectoryStream}.
166 *
167 * @return the stream associated with this {@code DirectoryStream}
168 *
169 * @throws IllegalStateException
170 * if this directory stream is closed or the iterator or stream
171 * has already been returned
172 * @since 1.8
173 */
174 default Stream<T> entries() {
175 return Streams.stream(Streams.spliteratorUnknownSize(iterator()),
176 Streams.STREAM_IS_DISTINCT);
177 }
178 }
|