    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one
    003 * or more contributor license agreements.  See the NOTICE file
    004 * distributed with this work for additional information
    005 * regarding copyright ownership.  The ASF licenses this file
    006 * to you under the Apache License, Version 2.0 (the
    007 * "License"); you may not use this file except in compliance
    008 * with the License.  You may obtain a copy of the License at
    009 *
    010 *    https://www.apache.org/licenses/LICENSE-2.0
    011 *
    012 * Unless required by applicable law or agreed to in writing,
    013 * software distributed under the License is distributed on an
    014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    015 * KIND, either express or implied.  See the License for the
    016 * specific language governing permissions and limitations
    017 * under the License.
    018 */
    019package org.apache.commons.io.input;
    020
    021import static org.apache.commons.io.IOUtils.EOF;
    022
    023import java.io.IOException;
    024import java.io.Reader;
    025
    026import org.apache.commons.io.IOUtils;
    027
    028/**
    029 * A reader that imposes a limit to the number of characters that can be read from an underlying reader, returning EOF
    030 * when this limit is reached, regardless of state of underlying reader.
    031 *
    032 * <p>
    033 * One use case is to avoid overrunning the readAheadLimit supplied to {@link Reader#mark(int)}, since reading
    034 * too many characters removes the ability to do a successful reset.
    035 * </p>
    036 *
    037 * @since 2.5
    038 */
    039public class BoundedReader extends ProxyReader {
    040
    041    private static final int INVALID = -1;
    042
    043    private int charsRead;
    044
    045    private int markedAt = INVALID;
    046
    047    private int readAheadLimit; // Internally, this value will never exceed the allowed size
    048
    049    private final int maxCharsFromTargetReader;
    050
    051    /**
    052     * Constructs a bounded reader
    053     *
    054     * @param target                   The target stream that will be used.
    055     * @param maxCharsFromTargetReader The maximum number of characters that can be read from target.
    056     */
    057    public BoundedReader(final Reader target, final int maxCharsFromTargetReader) {
    058        super(target);
    059        this.maxCharsFromTargetReader = maxCharsFromTargetReader;
    060    }
    061
    062    /**
    063     * marks the target stream
    064     *
    065     * @param readAheadLimit The number of characters that can be read while still retaining the ability to do #reset().
    066     *                       Note that this parameter is not validated with respect to maxCharsFromTargetReader. There
    067     *                       is no way to pass past maxCharsFromTargetReader, even if this value is greater.
    068     *
    069     * @throws IOException If an I/O error occurs while calling the underlying reader's mark method.
    070     * @see Reader#mark(int)
    071     */
    072    @Override
    073    public void mark(final int readAheadLimit) throws IOException {
    074        this.readAheadLimit = readAheadLimit - charsRead;
    075        markedAt = charsRead;
    076        super.mark(readAheadLimit);
    077    }
    078
    079    /**
    080     * Reads a single character
    081     *
    082     * @return -1 on EOF or the character read.
    083     * @throws IOException If an I/O error occurs while calling the underlying reader's read method.
    084     * @see Reader#read()
    085     */
    086    @Override
    087    public int read() throws IOException {
    088        if (charsRead >= maxCharsFromTargetReader || markedAt >= 0 && charsRead - markedAt >= readAheadLimit) {
    089            return EOF;
    090        }
    091        charsRead++;
    092        return super.read();
    093    }
    094
    095    /**
    096     * Reads into an array
    097     *
    098     * @param cbuf The buffer to fill.
    099     * @param off  The offset.
    100     * @param len  The number of chars to read.
    101     * @return the number of chars read.
    102     * @throws NullPointerException if the buffer is {@code null}.
    103     * @throws IndexOutOfBoundsException if {@code off} or {@code len} are negative, or if {@code off + len} is greater than {@code cbuf.length}.
    104     * @throws IOException If an I/O error occurs while calling the underlying reader's read method.
    105     * @see Reader#read(char[], int, int)
    106     */
    107    @Override
    108    public int read(final char[] cbuf, final int off, final int len) throws IOException {
    109        IOUtils.checkFromIndexSize(cbuf, off, len);
    110        int c;
    111        for (int i = 0; i < len; i++) {
    112            c = read();
    113            if (c == EOF) {
    114                return i == 0 ? EOF : i;
    115            }
    116            cbuf[off + i] = (char) c;
    117        }
    118        return len;
    119    }
    120
    121    /**
    122     * Resets the target to the latest mark,
    123     *
    124     * @throws IOException If an I/O error occurs while calling the underlying reader's reset method.
    125     * @see Reader#reset()
    126     */
    127    @Override
    128    public void reset() throws IOException {
    129        charsRead = markedAt;
    130        super.reset();
    131    }
    132
    133    @Override
    134    public long skip(final long n) throws IOException {
    135        charsRead += n;
    136        return super.skip(n);
    137    }
    138}