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 }
--- EOF ---