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     */
017    package org.apache.commons.io;
018    
019    import java.io.BufferedReader;
020    import java.io.IOException;
021    import java.io.Reader;
022    import java.util.Iterator;
023    import java.util.NoSuchElementException;
024    
025    /**
026     * An Iterator over the lines in a <code>Reader</code>.
027     * <p>
028     * <code>LineIterator</code> holds a reference to an open <code>Reader</code>.
029     * When you have finished with the iterator you should close the reader
030     * to free internal resources. This can be done by closing the reader directly,
031     * or by calling the {@link #close()} or {@link #closeQuietly(LineIterator)}
032     * method on the iterator.
033     * <p>
034     * The recommended usage pattern is:
035     * <pre>
036     * LineIterator it = FileUtils.lineIterator(file, "UTF-8");
037     * try {
038     *   while (it.hasNext()) {
039     *     String line = it.nextLine();
040     *     // do something with line
041     *   }
042     * } finally {
043     *   it.close();
044     * }
045     * </pre>
046     *
047     * @version $Id: LineIterator.java 1304073 2012-03-22 21:19:18Z sebb $
048     * @since 1.2
049     */
050    public class LineIterator implements Iterator<String> {
051    
052        // N.B. This class deliberately does not implement Iterable, see https://issues.apache.org/jira/browse/IO-181
053        
054        /** The reader that is being read. */
055        private final BufferedReader bufferedReader;
056        /** The current line. */
057        private String cachedLine;
058        /** A flag indicating if the iterator has been fully read. */
059        private boolean finished = false;
060    
061        /**
062         * Constructs an iterator of the lines for a <code>Reader</code>.
063         *
064         * @param reader the <code>Reader</code> to read from, not null
065         * @throws IllegalArgumentException if the reader is null
066         */
067        public LineIterator(final Reader reader) throws IllegalArgumentException {
068            if (reader == null) {
069                throw new IllegalArgumentException("Reader must not be null");
070            }
071            if (reader instanceof BufferedReader) {
072                bufferedReader = (BufferedReader) reader;
073            } else {
074                bufferedReader = new BufferedReader(reader);
075            }
076        }
077    
078        //-----------------------------------------------------------------------
079        /**
080         * Indicates whether the <code>Reader</code> has more lines.
081         * If there is an <code>IOException</code> then {@link #close()} will
082         * be called on this instance.
083         *
084         * @return <code>true</code> if the Reader has more lines
085         * @throws IllegalStateException if an IO exception occurs
086         */
087        public boolean hasNext() {
088            if (cachedLine != null) {
089                return true;
090            } else if (finished) {
091                return false;
092            } else {
093                try {
094                    while (true) {
095                        String line = bufferedReader.readLine();
096                        if (line == null) {
097                            finished = true;
098                            return false;
099                        } else if (isValidLine(line)) {
100                            cachedLine = line;
101                            return true;
102                        }
103                    }
104                } catch(IOException ioe) {
105                    close();
106                    throw new IllegalStateException(ioe);
107                }
108            }
109        }
110    
111        /**
112         * Overridable method to validate each line that is returned.
113         * This implementation always returns true.
114         * @param line  the line that is to be validated
115         * @return true if valid, false to remove from the iterator
116         */
117        protected boolean isValidLine(String line) {
118            return true;
119        }
120    
121        /**
122         * Returns the next line in the wrapped <code>Reader</code>.
123         *
124         * @return the next line from the input
125         * @throws NoSuchElementException if there is no line to return
126         */
127        public String next() {
128            return nextLine();
129        }
130    
131        /**
132         * Returns the next line in the wrapped <code>Reader</code>.
133         *
134         * @return the next line from the input
135         * @throws NoSuchElementException if there is no line to return
136         */
137        public String nextLine() {
138            if (!hasNext()) {
139                throw new NoSuchElementException("No more lines");
140            }
141            String currentLine = cachedLine;
142            cachedLine = null;
143            return currentLine;        
144        }
145    
146        /**
147         * Closes the underlying <code>Reader</code> quietly.
148         * This method is useful if you only want to process the first few
149         * lines of a larger file. If you do not close the iterator
150         * then the <code>Reader</code> remains open.
151         * This method can safely be called multiple times.
152         */
153        public void close() {
154            finished = true;
155            IOUtils.closeQuietly(bufferedReader);
156            cachedLine = null;
157        }
158    
159        /**
160         * Unsupported.
161         *
162         * @throws UnsupportedOperationException always
163         */
164        public void remove() {
165            throw new UnsupportedOperationException("Remove unsupported on LineIterator");
166        }
167    
168        //-----------------------------------------------------------------------
169        /**
170         * Closes the iterator, handling null and ignoring exceptions.
171         *
172         * @param iterator  the iterator to close
173         */
174        public static void closeQuietly(LineIterator iterator) {
175            if (iterator != null) {
176                iterator.close();
177            }
178        }
179    
180    }