| /* |
| * Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package java.nio.file; |
| |
| import java.util.Iterator; |
| import java.io.Closeable; |
| import java.io.IOException; |
| |
| /** |
| * An object to iterate over the entries in a directory. A directory stream |
| * allows for the convenient use of the for-each construct to iterate over a |
| * directory. |
| * |
| * <p> <b> While {@code DirectoryStream} extends {@code Iterable}, it is not a |
| * general-purpose {@code Iterable} as it supports only a single {@code |
| * Iterator}; invoking the {@link #iterator iterator} method to obtain a second |
| * or subsequent iterator throws {@code IllegalStateException}. </b> |
| * |
| * <p> An important property of the directory stream's {@code Iterator} is that |
| * its {@link Iterator#hasNext() hasNext} method is guaranteed to read-ahead by |
| * at least one element. If {@code hasNext} method returns {@code true}, and is |
| * followed by a call to the {@code next} method, it is guaranteed that the |
| * {@code next} method will not throw an exception due to an I/O error, or |
| * because the stream has been {@link #close closed}. The {@code Iterator} does |
| * not support the {@link Iterator#remove remove} operation. |
| * |
| * <p> A {@code DirectoryStream} is opened upon creation and is closed by |
| * invoking the {@code close} method. Closing a directory stream releases any |
| * resources associated with the stream. Failure to close the stream may result |
| * in a resource leak. The try-with-resources statement provides a useful |
| * construct to ensure that the stream is closed: |
| * <pre> |
| * Path dir = ... |
| * try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir)) { |
| * for (Path entry: stream) { |
| * ... |
| * } |
| * } |
| * </pre> |
| * |
| * <p> Once a directory stream is closed, then further access to the directory, |
| * using the {@code Iterator}, behaves as if the end of stream has been reached. |
| * Due to read-ahead, the {@code Iterator} may return one or more elements |
| * after the directory stream has been closed. Once these buffered elements |
| * have been read, then subsequent calls to the {@code hasNext} method returns |
| * {@code false}, and subsequent calls to the {@code next} method will throw |
| * {@code NoSuchElementException}. |
| * |
| * <p> A directory stream is not required to be <i>asynchronously closeable</i>. |
| * If a thread is blocked on the directory stream's iterator reading from the |
| * directory, and another thread invokes the {@code close} method, then the |
| * second thread may block until the read operation is complete. |
| * |
| * <p> If an I/O error is encountered when accessing the directory then it |
| * causes the {@code Iterator}'s {@code hasNext} or {@code next} methods to |
| * throw {@link DirectoryIteratorException} with the {@link IOException} as the |
| * cause. As stated above, the {@code hasNext} method is guaranteed to |
| * read-ahead by at least one element. This means that if {@code hasNext} method |
| * returns {@code true}, and is followed by a call to the {@code next} method, |
| * then it is guaranteed that the {@code next} method will not fail with a |
| * {@code DirectoryIteratorException}. |
| * |
| * <p> The elements returned by the iterator are in no specific order. Some file |
| * systems maintain special links to the directory itself and the directory's |
| * parent directory. Entries representing these links are not returned by the |
| * iterator. |
| * |
| * <p> The iterator is <i>weakly consistent</i>. It is thread safe but does not |
| * freeze the directory while iterating, so it may (or may not) reflect updates |
| * to the directory that occur after the {@code DirectoryStream} is created. |
| * |
| * <p> <b>Usage Examples:</b> |
| * Suppose we want a list of the source files in a directory. This example uses |
| * both the for-each and try-with-resources constructs. |
| * <pre> |
| * List<Path> listSourceFiles(Path dir) throws IOException { |
| * List<Path> result = new ArrayList<>(); |
| * try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir, "*.{c,h,cpp,hpp,java}")) { |
| * for (Path entry: stream) { |
| * result.add(entry); |
| * } |
| * } catch (DirectoryIteratorException ex) { |
| * // I/O error encounted during the iteration, the cause is an IOException |
| * throw ex.getCause(); |
| * } |
| * return result; |
| * } |
| * </pre> |
| * @param <T> The type of element returned by the iterator |
| * |
| * @since 1.7 |
| * |
| * @see Files#newDirectoryStream(Path) |
| */ |
| |
| public interface DirectoryStream<T> |
| extends Closeable, Iterable<T> { |
| /** |
| * An interface that is implemented by objects that decide if a directory |
| * entry should be accepted or filtered. A {@code Filter} is passed as the |
| * parameter to the {@link Files#newDirectoryStream(Path,DirectoryStream.Filter)} |
| * method when opening a directory to iterate over the entries in the |
| * directory. |
| * |
| * @param <T> the type of the directory entry |
| * |
| * @since 1.7 |
| */ |
| @FunctionalInterface |
| public static interface Filter<T> { |
| /** |
| * Decides if the given directory entry should be accepted or filtered. |
| * |
| * @param entry |
| * the directory entry to be tested |
| * |
| * @return {@code true} if the directory entry should be accepted |
| * |
| * @throws IOException |
| * If an I/O error occurs |
| */ |
| boolean accept(T entry) throws IOException; |
| } |
| |
| /** |
| * Returns the iterator associated with this {@code DirectoryStream}. |
| * |
| * @return the iterator associated with this {@code DirectoryStream} |
| * |
| * @throws IllegalStateException |
| * if this directory stream is closed or the iterator has already |
| * been returned |
| */ |
| @Override |
| Iterator<T> iterator(); |
| } |