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 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<Path> 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<Path> listSourceFiles(Path dir) throws IOException {
106 * List<Path> result = new ArrayList<>();
107 * try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir, "*.{c,h,cpp,hpp,java}")) {
108 * for (Path entry: stream) {
109 * result.add(entry);
110 * }
111 * } catch (DirectoryIteratorException ex) {
112 * // I/O error encounted during the iteration, the cause is an IOException
113 * throw ex.getCause();
114 * }
115 * return result;
116 * }
117 * </pre>
118 * @param <T> The type of element returned by the iterator
119 *
120 * @since 1.7
121 *
122 * @see Files#newDirectoryStream(Path)
123 */
124
125 public interface DirectoryStream<T>
126 extends Closeable, Iterable<T> {
127 /**
128 * An interface that is implemented by objects that decide if a directory
129 * entry should be accepted or filtered. A {@code Filter} is passed as the
130 * parameter to the {@link Files#newDirectoryStream(Path,DirectoryStream.Filter)}
131 * method when opening a directory to iterate over the entries in the
132 * directory.
133 *
134 * @param <T> the type of the directory entry
135 *
136 * @since 1.7
137 */
138 @FunctionalInterface
139 public static interface Filter<T> {
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 }