1 /*
   2  * Copyright (c) 1994, 2019, 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         if (in == null) {
  63             throw new NullPointerException();
  64         }
  65         this.in = in;
  66     }
  67 
  68     /**
  69      * Reads the next byte of data from this input stream. The value
  70      * byte is returned as an <code>int</code> in the range
  71      * <code>0</code> to <code>255</code>. If no byte is available
  72      * because the end of the stream has been reached, the value
  73      * <code>-1</code> is returned. This method blocks until input data
  74      * is available, the end of the stream is detected, or an exception
  75      * is thrown.
  76      * <p>
  77      * This method
  78      * simply performs <code>in.read()</code> and returns the result.
  79      *
  80      * @return     the next byte of data, or <code>-1</code> if the end of the
  81      *             stream is reached.
  82      * @exception  IOException  if an I/O error occurs.
  83      * @see        java.io.FilterInputStream#in
  84      */
  85     public int read() throws IOException {
  86         return in.read();
  87     }
  88 
  89     /**
  90      * Reads up to <code>b.length</code> bytes of data from this
  91      * input stream into an array of bytes. This method blocks until some
  92      * input is available.
  93      * <p>
  94      * This method simply performs the call
  95      * <code>read(b, 0, b.length)</code> and returns
  96      * the  result. It is important that it does
  97      * <i>not</i> do <code>in.read(b)</code> instead;
  98      * certain subclasses of  <code>FilterInputStream</code>
  99      * depend on the implementation strategy actually
 100      * used.
 101      *
 102      * @param      b   the buffer into which the data is read.
 103      * @return     the total number of bytes read into the buffer, or
 104      *             <code>-1</code> if there is no more data because the end of
 105      *             the stream has been reached.
 106      * @exception  IOException  if an I/O error occurs.
 107      * @see        java.io.FilterInputStream#read(byte[], int, int)
 108      */
 109     public int read(byte b[]) throws IOException {
 110         return read(b, 0, b.length);
 111     }
 112 
 113     /**
 114      * Reads up to <code>len</code> bytes of data from this input stream
 115      * into an array of bytes. If <code>len</code> is not zero, the method
 116      * blocks until some input is available; otherwise, no
 117      * bytes are read and <code>0</code> is returned.
 118      * <p>
 119      * This method simply performs <code>in.read(b, off, len)</code>
 120      * and returns the result.
 121      *
 122      * @param      b     the buffer into which the data is read.
 123      * @param      off   the start offset in the destination array <code>b</code>
 124      * @param      len   the maximum number of bytes read.
 125      * @return     the total number of bytes read into the buffer, or
 126      *             <code>-1</code> if there is no more data because the end of
 127      *             the stream has been reached.
 128      * @exception  NullPointerException If <code>b</code> is <code>null</code>.
 129      * @exception  IndexOutOfBoundsException If <code>off</code> is negative,
 130      * <code>len</code> is negative, or <code>len</code> is greater than
 131      * <code>b.length - off</code>
 132      * @exception  IOException  if an I/O error occurs.
 133      * @see        java.io.FilterInputStream#in
 134      */
 135     public int read(byte b[], int off, int len) throws IOException {
 136         return in.read(b, off, len);
 137     }
 138 
 139     /**
 140      * Skips over and discards <code>n</code> bytes of data from the
 141      * input stream. The <code>skip</code> method may, for a variety of
 142      * reasons, end up skipping over some smaller number of bytes,
 143      * possibly <code>0</code>. The actual number of bytes skipped is
 144      * returned.
 145      * <p>
 146      * This method simply performs <code>in.skip(n)</code>.
 147      *
 148      * @param      n   the number of bytes to be skipped.
 149      * @return     the actual number of bytes skipped.
 150      * @throws     IOException  if {@code in.skip(n)} throws an IOException.
 151      */
 152     public long skip(long n) throws IOException {
 153         return in.skip(n);
 154     }
 155 
 156     /**
 157      * Returns an estimate of the number of bytes that can be read (or
 158      * skipped over) from this input stream without blocking by the next
 159      * caller of a method for this input stream. The next caller might be
 160      * the same thread or another thread.  A single read or skip of this
 161      * many bytes will not block, but may read or skip fewer bytes.
 162      * <p>
 163      * This method returns the result of {@link #in in}.available().
 164      *
 165      * @return     an estimate of the number of bytes that can be read (or skipped
 166      *             over) from this input stream without blocking.
 167      * @exception  IOException  if an I/O error occurs.
 168      */
 169     public int available() throws IOException {
 170         return in.available();
 171     }
 172 
 173     /**
 174      * Closes this input stream and releases any system resources
 175      * associated with the stream.
 176      * This
 177      * method simply performs <code>in.close()</code>.
 178      *
 179      * @exception  IOException  if an I/O error occurs.
 180      * @see        java.io.FilterInputStream#in
 181      */
 182     public void close() throws IOException {
 183         in.close();
 184     }
 185 
 186     /**
 187      * Marks the current position in this input stream. A subsequent
 188      * call to the <code>reset</code> method repositions this stream at
 189      * the last marked position so that subsequent reads re-read the same bytes.
 190      * <p>
 191      * The <code>readlimit</code> argument tells this input stream to
 192      * allow that many bytes to be read before the mark position gets
 193      * invalidated.
 194      * <p>
 195      * This method simply performs <code>in.mark(readlimit)</code>.
 196      *
 197      * @param   readlimit   the maximum limit of bytes that can be read before
 198      *                      the mark position becomes invalid.
 199      * @see     java.io.FilterInputStream#in
 200      * @see     java.io.FilterInputStream#reset()
 201      */
 202     public synchronized void mark(int readlimit) {
 203         in.mark(readlimit);
 204     }
 205 
 206     /**
 207      * Repositions this stream to the position at the time the
 208      * <code>mark</code> method was last called on this input stream.
 209      * <p>
 210      * This method
 211      * simply performs <code>in.reset()</code>.
 212      * <p>
 213      * Stream marks are intended to be used in
 214      * situations where you need to read ahead a little to see what's in
 215      * the stream. Often this is most easily done by invoking some
 216      * general parser. If the stream is of the type handled by the
 217      * parse, it just chugs along happily. If the stream is not of
 218      * that type, the parser should toss an exception when it fails.
 219      * If this happens within readlimit bytes, it allows the outer
 220      * code to reset the stream and try another parser.
 221      *
 222      * @exception  IOException  if the stream has not been marked or if the
 223      *               mark has been invalidated.
 224      * @see        java.io.FilterInputStream#in
 225      * @see        java.io.FilterInputStream#mark(int)
 226      */
 227     public synchronized void reset() throws IOException {
 228         in.reset();
 229     }
 230 
 231     /**
 232      * Tests if this input stream supports the <code>mark</code>
 233      * and <code>reset</code> methods.
 234      * This method
 235      * simply performs <code>in.markSupported()</code>.
 236      *
 237      * @return  <code>true</code> if this stream type supports the
 238      *          <code>mark</code> and <code>reset</code> method;
 239      *          <code>false</code> otherwise.
 240      * @see     java.io.FilterInputStream#in
 241      * @see     java.io.InputStream#mark(int)
 242      * @see     java.io.InputStream#reset()
 243      */
 244     public boolean markSupported() {
 245         return in.markSupported();
 246     }
 247 }
--- EOF ---