History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/java/nio/file/DirectoryStream.java (1 of 18352 files). Show all

Unified · Split

java/pkg/java/nio/file/DirectoryStream.java+159−0
@@ -0,0 +1,159 @@
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&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+ /**
123+ * An interface that is implemented by objects that decide if a directory
124+ * entry should be accepted or filtered. A {@code Filter} is passed as the
125+ * parameter to the {@link Files#newDirectoryStream(Path,DirectoryStream.Filter)}
126+ * method when opening a directory to iterate over the entries in the
127+ * directory.
128+ *
129+ * @param <T> the type of the directory entry
130+ *
131+ * @since 1.7
132+ */
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+ */
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+}