home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1998 July & August / Pcwk78a98.iso / Internet / Javadraw / DATA.Z / FilterInputStream.java < prev    next >
Text File  |  1997-08-30  |  10KB  |  256 lines
  1. /*
  2.  * @(#)FilterInputStream.java    1.15 97/01/22
  3.  * 
  4.  * Copyright (c) 1995, 1996 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  * CopyrightVersion 1.1_beta
  20.  * 
  21.  */
  22.  
  23. package java.io;
  24.  
  25. /**
  26.  * This class is the superclass of all classes that filter input 
  27.  * streams. These streams sit on top of an already existing input 
  28.  * stream (the <i>underlying</i> input stream), but provide 
  29.  * additional functionality. 
  30.  * <p>
  31.  * The class <code>FilterInputStream</code> itself simply overrides 
  32.  * all methods of <code>InputStream</code> with versions that pass 
  33.  * all requests to the underlying input stream. Subclasses of 
  34.  * <code>FilterInputStream</code> may further override some of these 
  35.  * methods as well as provide additional methods and fields. 
  36.  *
  37.  * @author  Jonathan Payne
  38.  * @version 1.15, 01/22/97
  39.  * @since   JDK1.0
  40.  */
  41. public
  42. class FilterInputStream extends InputStream {
  43.     /**
  44.      * The underlying input stream. 
  45.      *
  46.      * @since   JDK1.0
  47.      */
  48.     protected InputStream in;
  49.  
  50.     /**
  51.      * Creates an input stream filter built on top of the specified 
  52.      * input stream. 
  53.      *
  54.      * @param   in   the underlying input stream.
  55.      * @since   JDK1.0
  56.      */
  57.     protected FilterInputStream(InputStream in) {
  58.     this.in = in;
  59.     }
  60.  
  61.     /**
  62.      * Reads the next byte of data from this input stream. The value 
  63.      * byte is returned as an <code>int</code> in the range 
  64.      * <code>0</code> to <code>255</code>. If no byte is available 
  65.      * because the end of the stream has been reached, the value 
  66.      * <code>-1</code> is returned. This method blocks until input data 
  67.      * is available, the end of the stream is detected, or an exception 
  68.      * is thrown. 
  69.      * <p>
  70.      * The <code>read</code> method of <code>FilterInputStream</code> 
  71.      * calls the <code>read</code> method of its underlying input stream 
  72.      * and returns whatever value that method returns. 
  73.      *
  74.      * @return     the next byte of data, or <code>-1</code> if the end of the
  75.      *             stream is reached.
  76.      * @exception  IOException  if an I/O error occurs.
  77.      * @see        java.io.FilterInputStream#in
  78.      * @since      JDK1.0
  79.      */
  80.     public int read() throws IOException {
  81.     return in.read();
  82.     }
  83.  
  84.     /**
  85.      * Reads up to <code>byte.length</code> bytes of data from this 
  86.      * input stream into an array of bytes. This method blocks until some 
  87.      * input is available. 
  88.      * <p>
  89.      * The <code>read</code> method of <code>FilterInputStream</code> 
  90.      * calls the <code>read</code> method of three arguments with the 
  91.      * arguments <code>b</code>, <code>0</code>, and 
  92.      * <code>b.length</code>, and returns whatever value that method returns.
  93.      * <p>
  94.      * Note that this method does not call the one-argument 
  95.      * <code>read</code> method of its underlying stream with the single 
  96.      * argument <code>b</code>. Subclasses of 
  97.      * <code>FilterInputStream</code> do not need to override this method 
  98.      * if they have overridden the three-argument <code>read</code> method.
  99.      *
  100.      * @param      b   the buffer into which the data is read.
  101.      * @return     the total number of bytes read into the buffer, or
  102.      *             <code>-1</code> if there is no more data because the end of
  103.      *             the stream has been reached.
  104.      * @exception  IOException  if an I/O error occurs.
  105.      * @see        java.io.FilterInputStream#read(byte[], int, int)
  106.      * @since      JDK1.0
  107.      */
  108.     public int read(byte b[]) throws IOException {
  109.     return read(b, 0, b.length);
  110.     }
  111.  
  112.     /**
  113.      * Reads up to <code>len</code> bytes of data from this input stream 
  114.      * into an array of bytes. This method blocks until some input is 
  115.      * available. 
  116.      * <p>
  117.      * The <code>read</code> method of <code>FilterInputStream</code> 
  118.      * calls the <code>read</code> method of its underlying input stream 
  119.      * with the same arguments and returns whatever value that method returns.
  120.      *
  121.      * @param      b     the buffer into which the data is read.
  122.      * @param      off   the start offset of the data.
  123.      * @param      len   the maximum number of bytes read.
  124.      * @return     the total number of bytes read into the buffer, or
  125.      *             <code>-1</code> if there is no more data because the end of
  126.      *             the stream has been reached.
  127.      * @exception  IOException  if an I/O error occurs.
  128.      * @see        java.io.FilterInputStream#in
  129.      * @since      JDK1.0
  130.      */
  131.     public int read(byte b[], int off, int len) throws IOException {
  132.     return in.read(b, off, len);
  133.     }
  134.  
  135.     /**
  136.      * Skips over and discards <code>n</code> bytes of data from the 
  137.      * input stream. The <code>skip</code> method may, for a variety of 
  138.      * reasons, end up skipping over some smaller number of bytes, 
  139.      * possibly <code>0</code>. The actual number of bytes skipped is 
  140.      * returned. 
  141.      * <p>
  142.      * The <code>skip </code>method of <code>FilterInputStream</code> 
  143.      * calls the <code>skip</code> method of its underlying input stream 
  144.      * with the same argument, and returns whatever value that method does.
  145.      *
  146.      * @param      n   the number of bytes to be skipped.
  147.      * @return     the actual number of bytes skipped.
  148.      * @exception  IOException  if an I/O error occurs.
  149.      * @since      JDK1.0
  150.      */
  151.     public long skip(long n) throws IOException {
  152.     return in.skip(n);
  153.     }
  154.  
  155.     /**
  156.      * Returns the number of bytes that can be read from this input 
  157.      * stream without blocking. 
  158.      * <p>
  159.      * The <code>available</code> method of 
  160.      * <code>FilterInputStream</code> calls the <code>available</code> 
  161.      * method of its underlying input stream and returns whatever value 
  162.      * that method returns. 
  163.      *
  164.      * @return     the number of bytes that can be read from the input stream
  165.      *             without blocking.
  166.      * @exception  IOException  if an I/O error occurs.
  167.      * @see        java.io.FilterInputStream#in
  168.      * @since      JDK1.0
  169.      */
  170.     public int available() throws IOException {
  171.     return in.available();
  172.     }
  173.  
  174.     /**
  175.      * Closes this input stream and releases any system resources 
  176.      * associated with the stream. The <code>close</code> method of 
  177.      * <code>FilterInputStream</code> calls the <code>close</code> method 
  178.      * of its underlying input stream. 
  179.      *
  180.      * @exception  IOException  if an I/O error occurs.
  181.      * @see        java.io.FilterInputStream#in
  182.      * @since      JDK1.0
  183.      */
  184.     public void close() throws IOException {
  185.     in.close();
  186.     }
  187.  
  188.     /**
  189.      * Marks the current position in this input stream. A subsequent 
  190.      * call to the <code>reset</code> method repositions this stream at 
  191.      * the last marked position so that subsequent reads re-read the same bytes.
  192.      * <p>
  193.      * The <code>readlimit</code> argument tells this input stream to 
  194.      * allow that many bytes to be read before the mark position gets 
  195.      * invalidated. 
  196.      * <p>
  197.      * The <code>mark</code> method of <code>FilterInputStream</code> 
  198.      * calls the <code>mark</code> method of its underlying input stream 
  199.      * with the <code>readlimit</code> argument. 
  200.      *
  201.      * @param   readlimit   the maximum limit of bytes that can be read before
  202.      *                      the mark position becomes invalid.
  203.      * @see     java.io.FilterInputStream#in
  204.      * @see     java.io.FilterInputStream#reset()
  205.      * @since   JDK1.0
  206.      */
  207.     public synchronized void mark(int readlimit) {
  208.     in.mark(readlimit);
  209.     }
  210.  
  211.     /**
  212.      * Repositions this stream to the position at the time the 
  213.      * <code>mark</code> method was last called on this input stream. 
  214.      * <p>
  215.      * The <code>reset</code> method of <code>FilterInputStream</code> 
  216.      * calls the <code>reset</code> method of its underlying input stream.
  217.      * <p>
  218.      * Stream marks are intended to be used in
  219.      * situations where you need to read ahead a little to see what's in
  220.      * the stream. Often this is most easily done by invoking some
  221.      * general parser. If the stream is of the type handled by the
  222.      * parse, it just chugs along happily. If the stream is not of
  223.      * that type, the parser should toss an exception when it fails.
  224.      * If this happens within readlimit bytes, it allows the outer
  225.      * code to reset the stream and try another parser.
  226.      *
  227.      * @exception  IOException  if the stream has not been marked or if the
  228.      *               mark has been invalidated.
  229.      * @see        java.io.FilterInputStream#in
  230.      * @see        java.io.FilterInputStream#mark(int)
  231.      * @since      JDK1.0
  232.      */
  233.     public synchronized void reset() throws IOException {
  234.     in.reset();
  235.     }
  236.  
  237.     /**
  238.      * Tests if this input stream supports the <code>mark</code> 
  239.      * and <code>reset</code> methods. The <code>markSupported</code> 
  240.      * method of <code>FilterInputStream</code> calls the 
  241.      * <code>markSupported</code> method of its underlying input stream 
  242.      * and returns whatever value that method returns. 
  243.      *
  244.      * @return  <code>true</code> if this stream type supports the
  245.      *          <code>mark</code> and <code>reset</code> method;
  246.      *          <code>false</code> otherwise.
  247.      * @see     java.io.FilterInputStream#in
  248.      * @see     java.io.InputStream#mark(int)
  249.      * @see     java.io.InputStream#reset()
  250.      * @since   JDK1.0
  251.      */
  252.     public boolean markSupported() {
  253.     return in.markSupported();
  254.     }
  255. }
  256.