1e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera/* 2e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved. 3e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 5e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * This code is free software; you can redistribute it and/or modify it 6e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * under the terms of the GNU General Public License version 2 only, as 7e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * published by the Free Software Foundation. Oracle designates this 8e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * particular file as subject to the "Classpath" exception as provided 9e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * by Oracle in the LICENSE file that accompanied this code. 10e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 11e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * This code is distributed in the hope that it will be useful, but WITHOUT 12e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * version 2 for more details (a copy is included in the LICENSE file that 15e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * accompanied this code). 16e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 17e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * You should have received a copy of the GNU General Public License version 18e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 2 along with this work; if not, write to the Free Software Foundation, 19e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 21e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * or visit www.oracle.com if you need additional information or have any 23e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * questions. 24e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera */ 25e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera 26e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmerapackage java.nio.file; 27e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera 28e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmeraimport java.util.Iterator; 29e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmeraimport java.io.Closeable; 30e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmeraimport java.io.IOException; 31e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera 32e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera/** 33e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * An object to iterate over the entries in a directory. A directory stream 34e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * allows for the convenient use of the for-each construct to iterate over a 35e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * directory. 36e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 37e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <p> <b> While {@code DirectoryStream} extends {@code Iterable}, it is not a 38e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * general-purpose {@code Iterable} as it supports only a single {@code 39e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * Iterator}; invoking the {@link #iterator iterator} method to obtain a second 40e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * or subsequent iterator throws {@code IllegalStateException}. </b> 41e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 42e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <p> An important property of the directory stream's {@code Iterator} is that 43e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * its {@link Iterator#hasNext() hasNext} method is guaranteed to read-ahead by 44e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * at least one element. If {@code hasNext} method returns {@code true}, and is 45e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * followed by a call to the {@code next} method, it is guaranteed that the 46e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * {@code next} method will not throw an exception due to an I/O error, or 47e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * because the stream has been {@link #close closed}. The {@code Iterator} does 48e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * not support the {@link Iterator#remove remove} operation. 49e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 50e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <p> A {@code DirectoryStream} is opened upon creation and is closed by 51e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * invoking the {@code close} method. Closing a directory stream releases any 52e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * resources associated with the stream. Failure to close the stream may result 53e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * in a resource leak. The try-with-resources statement provides a useful 54e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * construct to ensure that the stream is closed: 55e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <pre> 56e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * Path dir = ... 57e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir)) { 58e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * for (Path entry: stream) { 59e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * ... 60e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * } 61e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * } 62e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * </pre> 63e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 64e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <p> Once a directory stream is closed, then further access to the directory, 65e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * using the {@code Iterator}, behaves as if the end of stream has been reached. 66e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * Due to read-ahead, the {@code Iterator} may return one or more elements 67e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * after the directory stream has been closed. Once these buffered elements 68e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * have been read, then subsequent calls to the {@code hasNext} method returns 69e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * {@code false}, and subsequent calls to the {@code next} method will throw 70e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * {@code NoSuchElementException}. 71e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 72e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <p> A directory stream is not required to be <i>asynchronously closeable</i>. 73e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * If a thread is blocked on the directory stream's iterator reading from the 74e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * directory, and another thread invokes the {@code close} method, then the 75e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * second thread may block until the read operation is complete. 76e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 77e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <p> If an I/O error is encountered when accessing the directory then it 78e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * causes the {@code Iterator}'s {@code hasNext} or {@code next} methods to 79e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * throw {@link DirectoryIteratorException} with the {@link IOException} as the 80e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * cause. As stated above, the {@code hasNext} method is guaranteed to 81e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * read-ahead by at least one element. This means that if {@code hasNext} method 82e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * returns {@code true}, and is followed by a call to the {@code next} method, 83e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * then it is guaranteed that the {@code next} method will not fail with a 84e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * {@code DirectoryIteratorException}. 85e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 86e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <p> The elements returned by the iterator are in no specific order. Some file 87e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * systems maintain special links to the directory itself and the directory's 88e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * parent directory. Entries representing these links are not returned by the 89e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * iterator. 90e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 91e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <p> The iterator is <i>weakly consistent</i>. It is thread safe but does not 92e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * freeze the directory while iterating, so it may (or may not) reflect updates 93e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * to the directory that occur after the {@code DirectoryStream} is created. 94e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 95e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <p> <b>Usage Examples:</b> 96e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * Suppose we want a list of the source files in a directory. This example uses 97e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * both the for-each and try-with-resources constructs. 98e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <pre> 99e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * List<Path> listSourceFiles(Path dir) throws IOException { 100e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * List<Path> result = new ArrayList<>(); 101e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir, "*.{c,h,cpp,hpp,java}")) { 102e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * for (Path entry: stream) { 103e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * result.add(entry); 104e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * } 105e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * } catch (DirectoryIteratorException ex) { 106e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * // I/O error encounted during the iteration, the cause is an IOException 107e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * throw ex.getCause(); 108e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * } 109e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * return result; 110e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * } 111e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * </pre> 112e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @param <T> The type of element returned by the iterator 113e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 114e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @since 1.7 115e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 116e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @see Files#newDirectoryStream(Path) 117e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera */ 118e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera 119e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmerapublic interface DirectoryStream<T> 120e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera extends Closeable, Iterable<T> { 121e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera /** 122e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * An interface that is implemented by objects that decide if a directory 123e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * entry should be accepted or filtered. A {@code Filter} is passed as the 124e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * parameter to the {@link Files#newDirectoryStream(Path,DirectoryStream.Filter)} 125e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * method when opening a directory to iterate over the entries in the 126e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * directory. 127e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 128e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @param <T> the type of the directory entry 129e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 130e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @since 1.7 131e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera */ 132e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera @FunctionalInterface 133e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera public static interface Filter<T> { 134e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera /** 135e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * Decides if the given directory entry should be accepted or filtered. 136e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 137e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @param entry 138e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * the directory entry to be tested 139e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 140e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @return {@code true} if the directory entry should be accepted 141e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 142e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @throws IOException 143e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * If an I/O error occurs 144e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera */ 145e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera boolean accept(T entry) throws IOException; 146e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera } 147e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera 148e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera /** 149e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * Returns the iterator associated with this {@code DirectoryStream}. 150e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 151e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @return the iterator associated with this {@code DirectoryStream} 152e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 153e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @throws IllegalStateException 154e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * if this directory stream is closed or the iterator has already 155e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * been returned 156e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera */ 157e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera @Override 158e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera Iterator<T> iterator(); 159e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera} 160