Java tutorial
/* * 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(); }