    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.io;
    018
    019import java.io.BufferedReader;
    020import java.io.Closeable;
    021import java.io.IOException;
    022import java.io.Reader;
    023import java.util.Iterator;
    024import java.util.NoSuchElementException;
    025import java.util.Objects;
    026
    027/**
    028 * An Iterator over the lines in a {@link Reader}.
    029 * <p>
    030 * {@link LineIterator} holds a reference to an open {@link Reader}.
    031 * When you have finished with the iterator you should close the reader
    032 * to free internal resources. This can be done by closing the reader directly,
    033 * or by calling the {@link #close()} or {@link #closeQuietly(LineIterator)}
    034 * method on the iterator.
    035 * <p>
    036 * The recommended usage pattern is:
    037 * <pre>
    038 * LineIterator it = FileUtils.lineIterator(file, StandardCharsets.UTF_8.name());
    039 * try {
    040 *   while (it.hasNext()) {
    041 *     String line = it.nextLine();
    042 *     // do something with line
    043 *   }
    044 * } finally {
    045 *   it.close();
    046 * }
    047 * </pre>
    048 *
    049 * @since 1.2
    050 */
    051public class LineIterator implements Iterator<String>, Closeable {
    052
    053    // N.B. This class deliberately does not implement Iterable, see https://issues.apache.org/jira/browse/IO-181
    054
    055    /**
    056     * Closes a {@link LineIterator} quietly.
    057     *
    058     * @param iterator The iterator to close, or {@code null}.
    059     * @deprecated As of 2.6 deprecated without replacement. Please use the try-with-resources statement or handle
    060     * suppressed exceptions manually.
    061     * @see Throwable#addSuppressed(Throwable)
    062     */
    063    @Deprecated
    064    public static void closeQuietly(final LineIterator iterator) {
    065        IOUtils.closeQuietly(iterator);
    066    }
    067
    068    /** The reader that is being read. */
    069    private final BufferedReader bufferedReader;
    070
    071    /** The current line. */
    072    private String cachedLine;
    073
    074    /** A flag indicating if the iterator has been fully read. */
    075    private boolean finished;
    076
    077    /**
    078     * Constructs an iterator of the lines for a {@link Reader}.
    079     *
    080     * @param reader the {@link Reader} to read from, not null
    081     * @throws NullPointerException if the reader is null
    082     */
    083    @SuppressWarnings("resource") // Caller closes Reader
    084    public LineIterator(final Reader reader) {
    085        Objects.requireNonNull(reader, "reader");
    086        if (reader instanceof BufferedReader) {
    087            bufferedReader = (BufferedReader) reader;
    088        } else {
    089            bufferedReader = new BufferedReader(reader);
    090        }
    091    }
    092
    093    /**
    094     * Closes the underlying {@link Reader}.
    095     * This method is useful if you only want to process the first few
    096     * lines of a larger file. If you do not close the iterator
    097     * then the {@link Reader} remains open.
    098     * This method can safely be called multiple times.
    099     *
    100     * @throws IOException if closing the underlying {@link Reader} fails.
    101     */
    102    @Override
    103    public void close() throws IOException {
    104        finished = true;
    105        cachedLine = null;
    106        IOUtils.close(bufferedReader);
    107    }
    108
    109    /**
    110     * Indicates whether the {@link Reader} has more lines.
    111     * If there is an {@link IOException} then {@link #close()} will
    112     * be called on this instance.
    113     *
    114     * @return {@code true} if the Reader has more lines
    115     * @throws IllegalStateException if an IO exception occurs
    116     */
    117    @Override
    118    public boolean hasNext() {
    119        if (cachedLine != null) {
    120            return true;
    121        }
    122        if (finished) {
    123            return false;
    124        }
    125        try {
    126            while (true) {
    127                final String line = bufferedReader.readLine();
    128                if (line == null) {
    129                    finished = true;
    130                    return false;
    131                }
    132                if (isValidLine(line)) {
    133                    cachedLine = line;
    134                    return true;
    135                }
    136            }
    137        } catch (final IOException ioe) {
    138            IOUtils.closeQuietly(this, ioe::addSuppressed);
    139            throw new IllegalStateException(ioe);
    140        }
    141    }
    142
    143    /**
    144     * Overridable method to validate each line that is returned.
    145     * This implementation always returns true.
    146     * @param line  the line that is to be validated
    147     * @return true if valid, false to remove from the iterator
    148     */
    149    protected boolean isValidLine(final String line) {
    150        return true;
    151    }
    152
    153    /**
    154     * Returns the next line in the wrapped {@link Reader}.
    155     *
    156     * @return the next line from the input
    157     * @throws NoSuchElementException if there is no line to return
    158     */
    159    @Override
    160    public String next() {
    161        return nextLine();
    162    }
    163
    164    /**
    165     * Returns the next line in the wrapped {@link Reader}.
    166     *
    167     * @return the next line from the input
    168     * @throws NoSuchElementException if there is no line to return
    169     * @deprecated Use {@link #next()}.
    170     */
    171    @Deprecated
    172    public String nextLine() {
    173        if (!hasNext()) {
    174            throw new NoSuchElementException("No more lines");
    175        }
    176        final String currentLine = cachedLine;
    177        cachedLine = null;
    178        return currentLine;
    179    }
    180
    181    /**
    182     * Unsupported.
    183     *
    184     * @throws UnsupportedOperationException always
    185     */
    186    @Override
    187    public void remove() {
    188        throw new UnsupportedOperationException("remove not supported");
    189    }
    190
    191}