home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / ProgLangD.iso / VCAFE.3.0A / Main.bin / FilterInputStream.java < prev    next >
Text File  |  1998-09-22  |  10KB  |  248 lines
  1. /*
  2.  * @(#)FilterInputStream.java    1.16 98/07/01
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  * 
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.io;
  16.  
  17. /**
  18.  * This class is the superclass of all classes that filter input 
  19.  * streams. These streams sit on top of an already existing input 
  20.  * stream (the <i>underlying</i> input stream), but provide 
  21.  * additional functionality. 
  22.  * <p>
  23.  * The class <code>FilterInputStream</code> itself simply overrides 
  24.  * all methods of <code>InputStream</code> with versions that pass 
  25.  * all requests to the underlying input stream. Subclasses of 
  26.  * <code>FilterInputStream</code> may further override some of these 
  27.  * methods as well as provide additional methods and fields. 
  28.  *
  29.  * @author  Jonathan Payne
  30.  * @version 1.16, 07/01/98
  31.  * @since   JDK1.0
  32.  */
  33. public
  34. class FilterInputStream extends InputStream {
  35.     /**
  36.      * The underlying input stream. 
  37.      *
  38.      * @since   JDK1.0
  39.      */
  40.     protected InputStream in;
  41.  
  42.     /**
  43.      * Creates an input stream filter built on top of the specified 
  44.      * input stream. 
  45.      *
  46.      * @param   in   the underlying input stream.
  47.      * @since   JDK1.0
  48.      */
  49.     protected FilterInputStream(InputStream in) {
  50.     this.in = in;
  51.     }
  52.  
  53.     /**
  54.      * Reads the next byte of data from this input stream. The value 
  55.      * byte is returned as an <code>int</code> in the range 
  56.      * <code>0</code> to <code>255</code>. If no byte is available 
  57.      * because the end of the stream has been reached, the value 
  58.      * <code>-1</code> is returned. This method blocks until input data 
  59.      * is available, the end of the stream is detected, or an exception 
  60.      * is thrown. 
  61.      * <p>
  62.      * The <code>read</code> method of <code>FilterInputStream</code> 
  63.      * calls the <code>read</code> method of its underlying input stream 
  64.      * and returns whatever value that method returns. 
  65.      *
  66.      * @return     the next byte of data, or <code>-1</code> if the end of the
  67.      *             stream is reached.
  68.      * @exception  IOException  if an I/O error occurs.
  69.      * @see        java.io.FilterInputStream#in
  70.      * @since      JDK1.0
  71.      */
  72.     public int read() throws IOException {
  73.     return in.read();
  74.     }
  75.  
  76.     /**
  77.      * Reads up to <code>byte.length</code> bytes of data from this 
  78.      * input stream into an array of bytes. This method blocks until some 
  79.      * input is available. 
  80.      * <p>
  81.      * The <code>read</code> method of <code>FilterInputStream</code> 
  82.      * calls the <code>read</code> method of three arguments with the 
  83.      * arguments <code>b</code>, <code>0</code>, and 
  84.      * <code>b.length</code>, and returns whatever value that method returns.
  85.      * <p>
  86.      * Note that this method does not call the one-argument 
  87.      * <code>read</code> method of its underlying stream with the single 
  88.      * argument <code>b</code>. Subclasses of 
  89.      * <code>FilterInputStream</code> do not need to override this method 
  90.      * if they have overridden the three-argument <code>read</code> method.
  91.      *
  92.      * @param      b   the buffer into which the data is read.
  93.      * @return     the total number of bytes read into the buffer, or
  94.      *             <code>-1</code> if there is no more data because the end of
  95.      *             the stream has been reached.
  96.      * @exception  IOException  if an I/O error occurs.
  97.      * @see        java.io.FilterInputStream#read(byte[], int, int)
  98.      * @since      JDK1.0
  99.      */
  100.     public int read(byte b[]) throws IOException {
  101.     return read(b, 0, b.length);
  102.     }
  103.  
  104.     /**
  105.      * Reads up to <code>len</code> bytes of data from this input stream 
  106.      * into an array of bytes. This method blocks until some input is 
  107.      * available. 
  108.      * <p>
  109.      * The <code>read</code> method of <code>FilterInputStream</code> 
  110.      * calls the <code>read</code> method of its underlying input stream 
  111.      * with the same arguments and returns whatever value that method returns.
  112.      *
  113.      * @param      b     the buffer into which the data is read.
  114.      * @param      off   the start offset of the data.
  115.      * @param      len   the maximum number of bytes read.
  116.      * @return     the total number of bytes read into the buffer, or
  117.      *             <code>-1</code> if there is no more data because the end of
  118.      *             the stream has been reached.
  119.      * @exception  IOException  if an I/O error occurs.
  120.      * @see        java.io.FilterInputStream#in
  121.      * @since      JDK1.0
  122.      */
  123.     public int read(byte b[], int off, int len) throws IOException {
  124.     return in.read(b, off, len);
  125.     }
  126.  
  127.     /**
  128.      * Skips over and discards <code>n</code> bytes of data from the 
  129.      * input stream. The <code>skip</code> method may, for a variety of 
  130.      * reasons, end up skipping over some smaller number of bytes, 
  131.      * possibly <code>0</code>. The actual number of bytes skipped is 
  132.      * returned. 
  133.      * <p>
  134.      * The <code>skip </code>method of <code>FilterInputStream</code> 
  135.      * calls the <code>skip</code> method of its underlying input stream 
  136.      * with the same argument, and returns whatever value that method does.
  137.      *
  138.      * @param      n   the number of bytes to be skipped.
  139.      * @return     the actual number of bytes skipped.
  140.      * @exception  IOException  if an I/O error occurs.
  141.      * @since      JDK1.0
  142.      */
  143.     public long skip(long n) throws IOException {
  144.     return in.skip(n);
  145.     }
  146.  
  147.     /**
  148.      * Returns the number of bytes that can be read from this input 
  149.      * stream without blocking. 
  150.      * <p>
  151.      * The <code>available</code> method of 
  152.      * <code>FilterInputStream</code> calls the <code>available</code> 
  153.      * method of its underlying input stream and returns whatever value 
  154.      * that method returns. 
  155.      *
  156.      * @return     the number of bytes that can be read from the input stream
  157.      *             without blocking.
  158.      * @exception  IOException  if an I/O error occurs.
  159.      * @see        java.io.FilterInputStream#in
  160.      * @since      JDK1.0
  161.      */
  162.     public int available() throws IOException {
  163.     return in.available();
  164.     }
  165.  
  166.     /**
  167.      * Closes this input stream and releases any system resources 
  168.      * associated with the stream. The <code>close</code> method of 
  169.      * <code>FilterInputStream</code> calls the <code>close</code> method 
  170.      * of its underlying input stream. 
  171.      *
  172.      * @exception  IOException  if an I/O error occurs.
  173.      * @see        java.io.FilterInputStream#in
  174.      * @since      JDK1.0
  175.      */
  176.     public void close() throws IOException {
  177.     in.close();
  178.     }
  179.  
  180.     /**
  181.      * Marks the current position in this input stream. A subsequent 
  182.      * call to the <code>reset</code> method repositions this stream at 
  183.      * the last marked position so that subsequent reads re-read the same bytes.
  184.      * <p>
  185.      * The <code>readlimit</code> argument tells this input stream to 
  186.      * allow that many bytes to be read before the mark position gets 
  187.      * invalidated. 
  188.      * <p>
  189.      * The <code>mark</code> method of <code>FilterInputStream</code> 
  190.      * calls the <code>mark</code> method of its underlying input stream 
  191.      * with the <code>readlimit</code> argument. 
  192.      *
  193.      * @param   readlimit   the maximum limit of bytes that can be read before
  194.      *                      the mark position becomes invalid.
  195.      * @see     java.io.FilterInputStream#in
  196.      * @see     java.io.FilterInputStream#reset()
  197.      * @since   JDK1.0
  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.      * The <code>reset</code> method of <code>FilterInputStream</code> 
  208.      * calls the <code>reset</code> method of its underlying input stream.
  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.      * @since      JDK1.0
  224.      */
  225.     public synchronized void reset() throws IOException {
  226.     in.reset();
  227.     }
  228.  
  229.     /**
  230.      * Tests if this input stream supports the <code>mark</code> 
  231.      * and <code>reset</code> methods. The <code>markSupported</code> 
  232.      * method of <code>FilterInputStream</code> calls the 
  233.      * <code>markSupported</code> method of its underlying input stream 
  234.      * and returns whatever value that method returns. 
  235.      *
  236.      * @return  <code>true</code> if this stream type supports the
  237.      *          <code>mark</code> and <code>reset</code> method;
  238.      *          <code>false</code> otherwise.
  239.      * @see     java.io.FilterInputStream#in
  240.      * @see     java.io.InputStream#mark(int)
  241.      * @see     java.io.InputStream#reset()
  242.      * @since   JDK1.0
  243.      */
  244.     public boolean markSupported() {
  245.     return in.markSupported();
  246.     }
  247. }
  248.