1 /*

     2  * Copyright (c) 1994, 2017, Oracle and/or its affiliates. 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.  Oracle designates this

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

     9  * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package java.io;

    27 

    28 /**

    29  * A <code>FilterInputStream</code> contains

    30  * some other input stream, which it uses as

    31  * its  basic source of data, possibly transforming

    32  * the data along the way or providing  additional

    33  * functionality. The class <code>FilterInputStream</code>

    34  * itself simply overrides all  methods of

    35  * <code>InputStream</code> with versions that

    36  * pass all requests to the contained  input

    37  * stream. Subclasses of <code>FilterInputStream</code>

    38  * may further override some of  these methods

    39  * and may also provide additional methods

    40  * and fields.

    41  *

    42  * @author  Jonathan Payne

    43  * @since   1.0

    44  */

    45 public

    46 class FilterInputStream extends InputStream {

    47     /**

    48      * The input stream to be filtered.

    49      */

    50     protected volatile InputStream in;

    51 

    52     /**

    53      * Creates a <code>FilterInputStream</code>

    54      * by assigning the  argument <code>in</code>

    55      * to the field <code>this.in</code> so as

    56      * to remember it for later use.

    57      *

    58      * @param   in   the underlying input stream, or <code>null</code> if

    59      *          this instance is to be created without an underlying stream.

    60      */

    61     protected FilterInputStream(InputStream in) {

    62         this.in = in;

    63     }

    64 

    65     /**

    66      * Reads the next byte of data from this input stream. The value

    67      * byte is returned as an <code>int</code> in the range

    68      * <code>0</code> to <code>255</code>. If no byte is available

    69      * because the end of the stream has been reached, the value

    70      * <code>-1</code> is returned. This method blocks until input data

    71      * is available, the end of the stream is detected, or an exception

    72      * is thrown.

    73      * <p>

    74      * This method

    75      * simply performs <code>in.read()</code> and returns the result.

    76      *

    77      * @return     the next byte of data, or <code>-1</code> if the end of the

    78      *             stream is reached.

    79      * @exception  IOException  if an I/O error occurs.

    80      * @see        java.io.FilterInputStream#in

    81      */

    82     public int read() throws IOException {

    83         return in.read();

    84     }

    85 

    86     /**

    87      * Reads up to <code>b.length</code> bytes of data from this

    88      * input stream into an array of bytes. This method blocks until some

    89      * input is available.

    90      * <p>

    91      * This method simply performs the call

    92      * <code>read(b, 0, b.length)</code> and returns

    93      * the  result. It is important that it does

    94      * <i>not</i> do <code>in.read(b)</code> instead;

    95      * certain subclasses of  <code>FilterInputStream</code>

    96      * depend on the implementation strategy actually

    97      * used.

    98      *

    99      * @param      b   the buffer into which the data is read.

   100      * @return     the total number of bytes read into the buffer, or

   101      *             <code>-1</code> if there is no more data because the end of

   102      *             the stream has been reached.

   103      * @exception  IOException  if an I/O error occurs.

   104      * @see        java.io.FilterInputStream#read(byte[], int, int)

   105      */

   106     public int read(byte b[]) throws IOException {

   107         return read(b, 0, b.length);

   108     }

   109 

   110     /**

   111      * Reads up to <code>len</code> bytes of data from this input stream

   112      * into an array of bytes. If <code>len</code> is not zero, the method

   113      * blocks until some input is available; otherwise, no

   114      * bytes are read and <code>0</code> is returned.

   115      * <p>

   116      * This method simply performs <code>in.read(b, off, len)</code>

   117      * and returns the result.

   118      *

   119      * @param      b     the buffer into which the data is read.

   120      * @param      off   the start offset in the destination array <code>b</code>

   121      * @param      len   the maximum number of bytes read.

   122      * @return     the total number of bytes read into the buffer, or

   123      *             <code>-1</code> if there is no more data because the end of

   124      *             the stream has been reached.

   125      * @exception  NullPointerException If <code>b</code> is <code>null</code>.

   126      * @exception  IndexOutOfBoundsException If <code>off</code> is negative,

   127      * <code>len</code> is negative, or <code>len</code> is greater than

   128      * <code>b.length - off</code>

   129      * @exception  IOException  if an I/O error occurs.

   130      * @see        java.io.FilterInputStream#in

   131      */

   132     public int read(byte b[], int off, int len) throws IOException {

   133         return in.read(b, off, len);

   134     }

   135 

   136     /**

   137      * Skips over and discards <code>n</code> bytes of data from the

   138      * input stream. The <code>skip</code> method may, for a variety of

   139      * reasons, end up skipping over some smaller number of bytes,

   140      * possibly <code>0</code>. The actual number of bytes skipped is

   141      * returned.

   142      * <p>

   143      * This method simply performs <code>in.skip(n)</code>.

   144      *

   145      * @param      n   the number of bytes to be skipped.

   146      * @return     the actual number of bytes skipped.

   147      * @throws     IOException  if {@code in.skip(n)} throws an IOException.

   148      */

   149     public long skip(long n) throws IOException {

   150         return in.skip(n);

   151     }

   152 

   153     /**

   154      * Returns an estimate of the number of bytes that can be read (or

   155      * skipped over) from this input stream without blocking by the next

   156      * caller of a method for this input stream. The next caller might be

   157      * the same thread or another thread.  A single read or skip of this

   158      * many bytes will not block, but may read or skip fewer bytes.

   159      * <p>

   160      * This method returns the result of {@link #in in}.available().

   161      *

   162      * @return     an estimate of the number of bytes that can be read (or skipped

   163      *             over) from this input stream without blocking.

   164      * @exception  IOException  if an I/O error occurs.

   165      */

   166     public int available() throws IOException {

   167         return in.available();

   168     }

   169 

   170     /**

   171      * Closes this input stream and releases any system resources

   172      * associated with the stream.

   173      * This

   174      * method simply performs <code>in.close()</code>.

   175      *

   176      * @exception  IOException  if an I/O error occurs.

   177      * @see        java.io.FilterInputStream#in

   178      */

   179     public void close() throws IOException {

   180         in.close();

   181     }

   182 

   183     /**

   184      * Marks the current position in this input stream. A subsequent

   185      * call to the <code>reset</code> method repositions this stream at

   186      * the last marked position so that subsequent reads re-read the same bytes.

   187      * <p>

   188      * The <code>readlimit</code> argument tells this input stream to

   189      * allow that many bytes to be read before the mark position gets

   190      * invalidated.

   191      * <p>

   192      * This method simply performs <code>in.mark(readlimit)</code>.

   193      *

   194      * @param   readlimit   the maximum limit of bytes that can be read before

   195      *                      the mark position becomes invalid.

   196      * @see     java.io.FilterInputStream#in

   197      * @see     java.io.FilterInputStream#reset()

   198      */

   199     public synchronized void mark(int readlimit) {

   200         in.mark(readlimit);

   201     }

   202 

   203     /**

   204      * Repositions this stream to the position at the time the

   205      * <code>mark</code> method was last called on this input stream.

   206      * <p>

   207      * This method

   208      * simply performs <code>in.reset()</code>.

   209      * <p>

   210      * Stream marks are intended to be used in

   211      * situations where you need to read ahead a little to see what's in

   212      * the stream. Often this is most easily done by invoking some

   213      * general parser. If the stream is of the type handled by the

   214      * parse, it just chugs along happily. If the stream is not of

   215      * that type, the parser should toss an exception when it fails.

   216      * If this happens within readlimit bytes, it allows the outer

   217      * code to reset the stream and try another parser.

   218      *

   219      * @exception  IOException  if the stream has not been marked or if the

   220      *               mark has been invalidated.

   221      * @see        java.io.FilterInputStream#in

   222      * @see        java.io.FilterInputStream#mark(int)

   223      */

   224     public synchronized void reset() throws IOException {

   225         in.reset();

   226     }

   227 

   228     /**

   229      * Tests if this input stream supports the <code>mark</code>

   230      * and <code>reset</code> methods.

   231      * This method

   232      * simply performs <code>in.markSupported()</code>.

   233      *

   234      * @return  <code>true</code> if this stream type supports the

   235      *          <code>mark</code> and <code>reset</code> method;

   236      *          <code>false</code> otherwise.

   237      * @see     java.io.FilterInputStream#in

   238      * @see     java.io.InputStream#mark(int)

   239      * @see     java.io.InputStream#reset()

   240      */

   241     public boolean markSupported() {

   242         return in.markSupported();

   243     }

   244 }