Source code

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
018package org.apache.commons.io.input;
019
020import static org.apache.commons.io.IOUtils.CR;
021import static org.apache.commons.io.IOUtils.EOF;
022import static org.apache.commons.io.IOUtils.LF;
023
024import java.io.BufferedReader;
025import java.io.BufferedWriter;
026import java.io.IOException;
027import java.io.Reader;
028
029import org.apache.commons.io.IOUtils;
030
031/**
032 * Wraps an existing {@link Reader} and buffers the input <em>without any synchronization</em>. Expensive interaction with the underlying reader is minimized,
033 * since most (smaller) requests can be satisfied by accessing the buffer alone. The drawback is that some extra space is required to hold the buffer and that
034 * copying takes place when filling that buffer, but this is usually outweighed by the performance benefits.
035 * <p>
036 * A typical application pattern for the class looks like this:
037 * </p>
038 *
039 * <pre>{@code
040 * UnsynchronizedBufferedReader buf = new UnsynchronizedBufferedReader(new FileReader("file"));
041 * }</pre>
042 * <p>
043 * Provenance: Apache Harmony's java.io.BufferedReader, renamed, and modified.
044 * </p>
045 *
046 * @see BufferedReader
047 * @see BufferedWriter
048 * @since 2.17.0
049 */
050public class UnsynchronizedBufferedReader extends UnsynchronizedReader {
051
052    private static final char NUL = '\0';
053
054    private final Reader in;
055
056    /**
057     * The characters that can be read and refilled in bulk. We maintain three indices into this buffer:
058     *
059     * <pre>
060     *     { X X X X X X X X X X X X - - }
061     *           ^     ^             ^
062     *           |     |             |
063     *         mark   pos           end
064     * </pre>
065     * <p>
066     * Pos points to the next readable character. End is one greater than the last readable character. When {@code pos == end}, the buffer is empty and must be
067     * {@link #fillBuf() filled} before characters can be read.
068     * </p>
069     * <p>
070     * Mark is the value pos will be set to on calls to {@link #reset()}. Its value is in the range {@code [0...pos]}. If the mark is {@code -1}, the buffer
071     * cannot be reset.
072     * </p>
073     * <p>
074     * MarkLimit limits the distance between the mark and the pos. When this limit is exceeded, {@link #reset()} is permitted (but not required) to throw an
075     * exception. For shorter distances, {@link #reset()} shall not throw (unless the reader is closed).
076     * </p>
077     */
078    private char[] buf;
079
080    private int pos;
081
082    private int end;
083
084    private int mark = -1;
085
086    private int markLimit = -1;
087
088    /**
089     * Constructs a new BufferedReader on the Reader {@code in}. The buffer gets the default size (8 KB).
090     *
091     * @param in the Reader that is buffered.
092     */
093    public UnsynchronizedBufferedReader(final Reader in) {
094        this(in, IOUtils.DEFAULT_BUFFER_SIZE);
095    }
096
097    /**
098     * Constructs a new BufferedReader on the Reader {@code in}. The buffer size is specified by the parameter {@code size}.
099     *
100     * @param in   the Reader that is buffered.
101     * @param size the size of the buffer to allocate.
102     * @throws IllegalArgumentException if {@code size <= 0}.
103     */
104    public UnsynchronizedBufferedReader(final Reader in, final int size) {
105        if (size <= 0) {
106            throw new IllegalArgumentException("size <= 0");
107        }
108        this.in = in;
109        buf = new char[size];
110    }
111
112    /**
113     * Peeks at the next input character, refilling the buffer if necessary. If this character is a newline character ("\n"), it is discarded.
114     */
115    final void chompNewline() throws IOException {
116        if ((pos != end || fillBuf() != EOF) && buf[pos] == LF) {
117            pos++;
118        }
119    }
120
121    /**
122     * Closes this reader. This implementation closes the buffered source reader and releases the buffer. Nothing is done if this reader has already been
123     * closed.
124     *
125     * @throws IOException if an error occurs while closing this reader.
126     */
127    @Override
128    public void close() throws IOException {
129        if (!isClosed()) {
130            in.close();
131            buf = null;
132            super.close();
133        }
134    }
135
136    /**
137     * Populates the buffer with data. It is an error to call this method when the buffer still contains data; ie. if {@code pos < end}.
138     *
139     * @return the number of bytes read into the buffer, or -1 if the end of the source stream has been reached.
140     */
141    private int fillBuf() throws IOException {
142        // assert(pos == end);
143
144        if (mark == EOF || pos - mark >= markLimit) {
145            /* mark isn't set or has exceeded its limit. use the whole buffer */
146            final int result = in.read(buf, 0, buf.length);
147            if (result > 0) {
148                mark = -1;
149                pos = 0;
150                end = result;
151            }
152            return result;
153        }
154
155        if (mark == 0 && markLimit > buf.length) {
156            /* the only way to make room when mark=0 is by growing the buffer */
157            int newLength = buf.length * 2;
158            if (newLength > markLimit) {
159                newLength = markLimit;
160            }
161            final char[] newbuf = new char[newLength];
162            System.arraycopy(buf, 0, newbuf, 0, buf.length);
163            buf = newbuf;
164        } else if (mark > 0) {
165            /* make room by shifting the buffered data to left mark positions */
166            System.arraycopy(buf, mark, buf, 0, buf.length - mark);
167            pos -= mark;
168            end -= mark;
169            mark = 0;
170        }
171
172        /* Set the new position and mark position */
173        final int count = in.read(buf, pos, buf.length - pos);
174        if (count != EOF) {
175            end += count;
176        }
177        return count;
178    }
179
180    /**
181     * Sets a mark position in this reader. The parameter {@code markLimit} indicates how many characters can be read before the mark is invalidated. Calling
182     * {@link #reset()} will reposition the reader back to the marked position if {@code markLimit} has not been surpassed.
183     *
184     * @param markLimit the number of characters that can be read before the mark is invalidated.
185     * @throws IllegalArgumentException if {@code markLimit < 0}.
186     * @throws IOException              if an error occurs while setting a mark in this reader.
187     * @see #markSupported()
188     * @see #reset()
189     */
190    @Override
191    public void mark(final int markLimit) throws IOException {
192        if (markLimit < 0) {
193            throw new IllegalArgumentException();
194        }
195        checkOpen();
196        this.markLimit = markLimit;
197        mark = pos;
198    }
199
200    /**
201     * Tests whether this reader supports the {@link #mark(int)} and {@link #reset()} methods. This implementation returns {@code true}.
202     *
203     * @return {@code true} for {@code BufferedReader}.
204     * @see #mark(int)
205     * @see #reset()
206     */
207    @Override
208    public boolean markSupported() {
209        return true;
210    }
211
212    /**
213     * Returns the next character in the current reader without consuming it. So the next call to {@link #read()} will still return this value.
214     *
215     * @return the next character
216     * @throws IOException If an I/O error occurs
217     */
218    public int peek() throws IOException {
219        mark(1);
220        final int c = read();
221        reset();
222        return c;
223    }
224
225    /**
226     * Populates the buffer with the next {@code buf.length} characters in the current reader without consuming them. The next call to {@link #read()} will
227     * still return the next value.
228     *
229     * @param buf the buffer to fill for the look ahead.
230     * @return the buffer itself
231     * @throws IOException If an I/O error occurs
232     */
233    public int peek(final char[] buf) throws IOException {
234        final int n = buf.length;
235        mark(n);
236        final int c = read(buf, 0, n);
237        reset();
238        return c;
239    }
240
241    /**
242     * Reads a single character from this reader and returns it with the two higher-order bytes set to 0. If possible, BufferedReader returns a character from
243     * the buffer. If there are no characters available in the buffer, it fills the buffer and then returns a character. It returns -1 if there are no more
244     * characters in the source reader.
245     *
246     * @return the character read or -1 if the end of the source reader has been reached.
247     * @throws IOException if this reader is closed or some other I/O error occurs.
248     */
249    @Override
250    public int read() throws IOException {
251        checkOpen();
252        /* Are there buffered characters available? */
253        if (pos < end || fillBuf() != EOF) {
254            return buf[pos++];
255        }
256        return EOF;
257    }
258
259    /**
260     * Reads at most {@code length} characters from this reader and stores them at {@code offset} in the character array {@code buffer}. Returns the number of
261     * characters actually read or -1 if the end of the source reader has been reached. If all the buffered characters have been used, a mark has not been set
262     * and the requested number of characters is larger than this readers buffer size, BufferedReader bypasses the buffer and simply places the results directly
263     * into {@code buffer}.
264     *
265     * @param buffer the character array to store the characters read.
266     * @param offset the initial position in {@code buffer} to store the bytes read from this reader.
267     * @param length the maximum number of characters to read, must be non-negative.
268     * @return number of characters read or -1 if the end of the source reader has been reached.
269     * @throws IndexOutOfBoundsException if {@code offset < 0} or {@code length < 0}, or if {@code offset + length} is greater than the size of {@code buffer}.
270     * @throws IOException               if this reader is closed or some other I/O error occurs.
271     */
272    @Override
273    public int read(final char[] buffer, int offset, final int length) throws IOException {
274        checkOpen();
275        if (offset < 0 || offset > buffer.length - length || length < 0) {
276            throw new IndexOutOfBoundsException();
277        }
278        int outstanding = length;
279        while (outstanding > 0) {
280
281            /*
282             * If there are bytes in the buffer, grab those first.
283             */
284            final int available = end - pos;
285            if (available > 0) {
286                final int count = available >= outstanding ? outstanding : available;
287                System.arraycopy(buf, pos, buffer, offset, count);
288                pos += count;
289                offset += count;
290                outstanding -= count;
291            }
292
293            /*
294             * Before attempting to read from the underlying stream, make sure we really, really want to. We won't bother if we're done, or if we've already got
295             * some bytes and reading from the underlying stream would block.
296             */
297            if (outstanding == 0 || outstanding < length && !in.ready()) {
298                break;
299            }
300
301            // assert(pos == end);
302
303            /*
304             * If we're unmarked and the requested size is greater than our buffer, read the bytes directly into the caller's buffer. We don't read into smaller
305             * buffers because that could result in a many reads.
306             */
307            if ((mark == -1 || pos - mark >= markLimit) && outstanding >= buf.length) {
308                final int count = in.read(buffer, offset, outstanding);
309                if (count > 0) {
310                    outstanding -= count;
311                    mark = -1;
312                }
313
314                break; // assume the source stream gave us all that it could
315            }
316
317            if (fillBuf() == EOF) {
318                break; // source is exhausted
319            }
320        }
321
322        final int count = length - outstanding;
323        return count > 0 || count == length ? count : EOF;
324    }
325
326    /**
327     * Returns the next line of text available from this reader. A line is represented by zero or more characters followed by {@code LF}, {@code CR},
328     * {@code "\r\n"} or the end of the reader. The string does not include the newline sequence.
329     *
330     * @return the contents of the line or {@code null} if no characters were read before the end of the reader has been reached.
331     * @throws IOException if this reader is closed or some other I/O error occurs.
332     */
333    public String readLine() throws IOException {
334        checkOpen();
335        /* has the underlying stream been exhausted? */
336        if (pos == end && fillBuf() == EOF) {
337            return null;
338        }
339        for (int charPos = pos; charPos < end; charPos++) {
340            final char ch = buf[charPos];
341            if (ch > CR) {
342                continue;
343            }
344            if (ch == LF) {
345                final String res = new String(buf, pos, charPos - pos);
346                pos = charPos + 1;
347                return res;
348            }
349            if (ch == CR) {
350                final String res = new String(buf, pos, charPos - pos);
351                pos = charPos + 1;
352                if ((pos < end || fillBuf() != EOF) && buf[pos] == LF) {
353                    pos++;
354                }
355                return res;
356            }
357        }
358
359        char eol = NUL;
360        final StringBuilder result = new StringBuilder(80);
361        /* Typical Line Length */
362
363        result.append(buf, pos, end - pos);
364        while (true) {
365            pos = end;
366
367            /* Are there buffered characters available? */
368            if (eol == LF) {
369                return result.toString();
370            }
371            // attempt to fill buffer
372            if (fillBuf() == EOF) {
373                // characters or null.
374                return result.length() > 0 || eol != NUL ? result.toString() : null;
375            }
376            for (int charPos = pos; charPos < end; charPos++) {
377                final char c = buf[charPos];
378                if (eol != NUL) {
379                    if (eol == CR && c == LF) {
380                        if (charPos > pos) {
381                            result.append(buf, pos, charPos - pos - 1);
382                        }
383                        pos = charPos + 1;
384                    } else {
385                        if (charPos > pos) {
386                            result.append(buf, pos, charPos - pos - 1);
387                        }
388                        pos = charPos;
389                    }
390                    return result.toString();
391                }
392                if (c == LF || c == CR) {
393                    eol = c;
394                }
395            }
396            if (eol == NUL) {
397                result.append(buf, pos, end - pos);
398            } else {
399                result.append(buf, pos, end - pos - 1);
400            }
401        }
402    }
403
404    /**
405     * Tests whether this reader is ready to be read without blocking.
406     *
407     * @return {@code true} if this reader will not block when {@code read} is called, {@code false} if unknown or blocking will occur.
408     * @throws IOException if this reader is closed or some other I/O error occurs.
409     * @see #read()
410     * @see #read(char[], int, int)
411     * @see #readLine()
412     */
413    @Override
414    public boolean ready() throws IOException {
415        checkOpen();
416        return end - pos > 0 || in.ready();
417    }
418
419    /**
420     * Resets this reader's position to the last {@code mark()} location. Invocations of {@code read()} and {@code skip()} will occur from this new location.
421     *
422     * @throws IOException if this reader is closed or no mark has been set.
423     * @see #mark(int)
424     * @see #markSupported()
425     */
426    @Override
427    public void reset() throws IOException {
428        checkOpen();
429        if (mark == -1) {
430            throw new IOException("mark == -1");
431        }
432        pos = mark;
433    }
434
435    /**
436     * Skips {@code amount} characters in this reader. Subsequent {@code read()}s will not return these characters unless {@code reset()} is used. Skipping
437     * characters may invalidate a mark if {@code markLimit} is surpassed.
438     *
439     * @param amount the maximum number of characters to skip.
440     * @return the number of characters actually skipped.
441     * @throws IllegalArgumentException if {@code amount < 0}.
442     * @throws IOException              if this reader is closed or some other I/O error occurs.
443     * @see #mark(int)
444     * @see #markSupported()
445     * @see #reset()
446     */
447    @Override
448    public long skip(final long amount) throws IOException {
449        if (amount < 0) {
450            throw new IllegalArgumentException();
451        }
452        checkOpen();
453        if (amount < 1) {
454            return 0;
455        }
456        if (end - pos >= amount) {
457            pos += amount;
458            return amount;
459        }
460
461        long read = end - pos;
462        pos = end;
463        while (read < amount) {
464            if (fillBuf() == EOF) {
465                return read;
466            }
467            if (end - pos >= amount - read) {
468                pos += amount - read;
469                return amount;
470            }
471            // Couldn't get all the characters, skip what we read
472            read += end - pos;
473            pos = end;
474        }
475        return amount;
476    }
477
478}