1 /*

     2  * Copyright 2007-2009 Sun Microsystems, Inc.  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.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 package java.nio.file;

    27 

    28 import java.util.Iterator;

    29 import java.io.Closeable;

    30 

    31 /**

    32  * An object to iterate over the entries in a directory. A directory stream

    33  * allows for convenient use of the for-each construct:

    34  * <pre>

    35  *   Path dir = ...

    36  *   DirectoryStream<Path> stream = dir.newDirectoryStream();

    37  *   try {

    38  *       for (Path entry: stream) {

    39  *         ..

    40  *       }

    41  *   } finally {

    42  *       stream.close();

    43  *   }

    44  * </pre>

    45  *

    46  * <p><b> A {@code DirectoryStream} is not a general-purpose {@code Iterable}.

    47  * While this interface extends {@code Iterable}, the {@code iterator} method

    48  * may only be invoked once to obtain the iterator; a second, or subsequent,

    49  * call to the {@code iterator} method throws {@code IllegalStateException}. </b>

    50  *

    51  * <p> A {@code DirectoryStream} is opened upon creation and is closed by

    52  * invoking the {@link #close close} method. Closing the directory stream

    53  * releases any resources associated with the stream. The {@link

    54  * Files#withDirectory Files.withDirectory} utility method is useful for cases

    55  * where a task is performed on entries in a directory. This method automatically

    56  * closes the directory stream when iteration is complete (or an error occurs).

    57  * Once a directory stream is closed, all further method invocations on the

    58  * iterator throw {@link java.util.concurrent.ConcurrentModificationException}

    59  * with cause {@link ClosedDirectoryStreamException}.

    60  *

    61  * <p> A directory stream is not required to be <i>asynchronously closeable</i>.

    62  * If a thread is blocked on the directory stream's iterator, reading from the

    63  * directory, and another thread invokes the {@code close} method then it may

    64  * require to block until the read operation is complete.

    65  *

    66  * <p> The {@link Iterator#hasNext() hasNext} and {@link Iterator#next() next}

    67  * methods can encounter an I/O error when iterating over the directory in which

    68  * case {@code ConcurrentModificationException} is thrown with cause

    69  * {@link java.io.IOException}. The {@code hasNext} method is guaranteed to

    70  * read-ahead by at least one element. This means that if the {@code hasNext}

    71  * method returns {@code true} and is followed by a call to the {@code next}

    72  * method then it is guaranteed not to fail with a {@code

    73  * ConcurrentModificationException}.

    74  *

    75  * <p> The elements returned by the iterator are in no specific order. Some file

    76  * systems maintain special links to the directory itself and the directory's

    77  * parent directory. Entries representing these links are not returned by the

    78  * iterator.

    79  *

    80  * <p> The iterator's {@link Iterator#remove() remove} method removes the

    81  * directory entry for the last element returned by the iterator, as if by

    82  * invoking the {@link FileRef#delete delete} method. If an I/O error or

    83  * security exception occurs then {@code ConcurrentModificationException} is

    84  * thrown with the cause.

    85  *

    86  * <p> The iterator is <i>weakly consistent</i>. It is thread safe but does not

    87  * freeze the directory while iterating, so it may (or may not) reflect updates

    88  * to the directory that occur after the {@code DirectoryStream} is created.

    89  *

    90  * @param   <T>     The type of element returned by the iterator

    91  *

    92  * @since 1.7

    93  *

    94  * @see Path#newDirectoryStream

    95  */

    96 

    97 public interface DirectoryStream<T>

    98     extends Closeable, Iterable<T>

    99 {

   100     /**

   101      * An interface that is implemented by objects that decide if a directory

   102      * entry should be accepted or filtered. A {@code Filter} is passed as the

   103      * parameter to the {@link Path#newDirectoryStream(DirectoryStream.Filter)

   104      * newDirectoryStream} method when opening a directory to iterate over the

   105      * entries in the directory.

   106      *

   107      * <p> The {@link DirectoryStreamFilters} class defines factory methods to

   108      * create filters for a number of common usages and also methods to combine

   109      * filters.

   110      *

   111      * @param   <T>     The type of the directory entry

   112      *

   113      * @since 1.7

   114      */

   115     public static interface Filter<T> {

   116         /**

   117          * Decides if the given directory entry should be accepted or filtered.

   118          *

   119          * @param   entry

   120          *          The directory entry to be tested

   121          *

   122          * @return  {@code true} if the directory entry should be accepted

   123          */

   124         boolean accept(T entry);

   125     }

   126 

   127     /**

   128      * Returns the iterator associated with this {@code DirectoryStream}.

   129      *

   130      * @return  The iterator associated with this {@code DirectoryStream}

   131      *

   132      * @throws  IllegalStateException

   133      *          If this directory stream is closed or the iterator has already

   134      *          been returned

   135      */

   136     @Override

   137     Iterator<T> iterator();

   138 }