home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / io / InputStream.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  8.5 KB  |  241 lines
  1. /*
  2.  * @(#)InputStream.java    1.27 98/03/18
  3.  *
  4.  * Copyright 1994-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 abstract class is the superclass of all classes representing 
  19.  * an input stream of bytes. 
  20.  * <p>
  21.  * Applications that need to define a subclass of 
  22.  * <code>InputStream</code> must always provide a method that returns 
  23.  * the next byte of input.
  24.  * 
  25.  * @author  Arthur van Hoff
  26.  * @version 1.27, 03/18/98
  27.  * @see     java.io.BufferedInputStream
  28.  * @see     java.io.ByteArrayInputStream
  29.  * @see     java.io.DataInputStream
  30.  * @see     java.io.FilterInputStream
  31.  * @see     java.io.InputStream#read()
  32.  * @see     java.io.OutputStream
  33.  * @see     java.io.PushbackInputStream
  34.  * @since   JDK1.0
  35.  */
  36. public abstract class InputStream {
  37.     /**
  38.      * Reads the next byte of data from this input stream. The value 
  39.      * byte is returned as an <code>int</code> in the range 
  40.      * <code>0</code> to <code>255</code>. If no byte is available 
  41.      * because the end of the stream has been reached, the value 
  42.      * <code>-1</code> is returned. This method blocks until input data 
  43.      * is available, the end of the stream is detected, or an exception 
  44.      * is thrown. 
  45.      * <p>
  46.      * A subclass must provide an implementation of this method. 
  47.      *
  48.      * @return     the next byte of data, or <code>-1</code> if the end of the
  49.      *             stream is reached.
  50.      * @exception  IOException  if an I/O error occurs.
  51.      */
  52.     public abstract int read() throws IOException;
  53.  
  54.     /**
  55.      * Reads up to <code>b.length</code> bytes of data from this input 
  56.      * stream into an array of bytes. 
  57.      * <p>
  58.      * The <code>read</code> method of <code>InputStream</code> calls 
  59.      * the <code>read</code> method of three arguments with the arguments 
  60.      * <code>b</code>, <code>0</code>, and <code>b.length</code>. 
  61.      *
  62.      * @param      b   the buffer into which the data is read.
  63.      * @return     the total number of bytes read into the buffer, or
  64.      *             <code>-1</code> is there is no more data because the end of
  65.      *             the stream has been reached.
  66.      * @exception  IOException  if an I/O error occurs.
  67.      * @see        java.io.InputStream#read(byte[], int, int)
  68.      */
  69.     public int read(byte b[]) throws IOException {
  70.     return read(b, 0, b.length);
  71.     }
  72.  
  73.     /**
  74.      * Reads up to <code>len</code> bytes of data from this input stream 
  75.      * into an array of bytes. This method blocks until some input is 
  76.      * available. If the argument <code>b</code> is <code>null</code>, a 
  77.      * <code>NullPointerException</code> is thrown. 
  78.      * <p>
  79.      * The <code>read</code> method of <code>InputStream</code> reads a 
  80.      * single byte at a time using the read method of zero arguments to 
  81.      * fill in the array. Subclasses are encouraged to provide a more 
  82.      * efficient implementation of this method. 
  83.      *
  84.      * @param      b     the buffer into which the data is read.
  85.      * @param      off   the start offset of the data.
  86.      * @param      len   the maximum number of bytes read.
  87.      * @return     the total number of bytes read into the buffer, or
  88.      *             <code>-1</code> if there is no more data because the end of
  89.      *             the stream has been reached.
  90.      * @exception  IOException  if an I/O error occurs.
  91.      * @see        java.io.InputStream#read()
  92.      */
  93.     public int read(byte b[], int off, int len) throws IOException {
  94.     if (len <= 0) {
  95.         return 0;
  96.     }
  97.  
  98.     int c = read();
  99.     if (c == -1) {
  100.         return -1;
  101.     }
  102.     b[off] = (byte)c;
  103.  
  104.     int i = 1;
  105.     try {
  106.         for (; i < len ; i++) {
  107.         c = read();
  108.         if (c == -1) {
  109.             break;
  110.         }
  111.         if (b != null) {
  112.             b[off + i] = (byte)c;
  113.         }
  114.         }
  115.     } catch (IOException ee) {
  116.     }
  117.     return i;
  118.     }
  119.  
  120.     /**
  121.      * Skips over and discards <code>n</code> bytes of data from this 
  122.      * input stream. The <code>skip</code> method may, for a variety of 
  123.      * reasons, end up skipping over some smaller number of bytes, 
  124.      * possibly <code>0</code>. The actual number of bytes skipped is 
  125.      * returned.  If <code>n</code> is negative, no bytes are skipped.
  126.      * <p>
  127.      * The <code>skip</code> method of <code>InputStream</code> creates 
  128.      * a byte array and then repeatedly reads into it until 
  129.      * <code>n</code> bytes have been read or the end of the stream has 
  130.      * been reached. Subclasses are encouraged to provide a more 
  131.      * efficient implementation of this method. 
  132.      *
  133.      * @param      n   the number of bytes to be skipped.
  134.      * @return     the actual number of bytes skipped.
  135.      * @exception  IOException  if an I/O error occurs.
  136.      */
  137.     public long skip(long n) throws IOException {
  138.     int chunk = 2048;             
  139.     long remaining = n;
  140.     byte data[];
  141.     int nr;
  142.  
  143.     if (n <= 0) {
  144.         return 0;
  145.     }
  146.     
  147.     data = new byte[chunk];
  148.     while (remaining > 0) {
  149.         nr = read(data, 0, (int) Math.min(chunk, remaining));
  150.         if (nr < 0) {
  151.         break;
  152.         }
  153.         remaining -= nr;
  154.     }
  155.     
  156.     return n - remaining;
  157.     }
  158.  
  159.     /**
  160.      * Returns the number of bytes that can be read from this input 
  161.      * stream without blocking. The available method of 
  162.      * <code>InputStream</code> returns <code>0</code>. This method 
  163.      * <B>should</B> be overridden by subclasses. 
  164.      *
  165.      * @return     the number of bytes that can be read from this input stream
  166.      *             without blocking.
  167.      * @exception  IOException  if an I/O error occurs.
  168.      */
  169.     public int available() throws IOException {
  170.     return 0;
  171.     }
  172.  
  173.     /**
  174.      * Closes this input stream and releases any system resources 
  175.      * associated with the stream. 
  176.      * <p>
  177.      * The <code>close</code> method of <code>InputStream</code> does nothing.
  178.      *
  179.      * @exception  IOException  if an I/O error occurs.
  180.      */
  181.     public void close() throws IOException {}
  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 
  187.      * bytes. 
  188.      * <p>
  189.      * The <code>readlimit</code> arguments tells this input stream to 
  190.      * allow that many bytes to be read before the mark position gets 
  191.      * invalidated. 
  192.      * <p>
  193.      * The <code>mark</code> method of <code>InputStream</code> does nothing.
  194.      *
  195.      * @param   readlimit   the maximum limit of bytes that can be read before
  196.      *                      the mark position becomes invalid.
  197.      * @see     java.io.InputStream#reset()
  198.      */
  199.     public synchronized void mark(int readlimit) {}
  200.  
  201.     /**
  202.      * Repositions this stream to the position at the time the 
  203.      * <code>mark</code> method was last called on this input stream. 
  204.      * <p>
  205.      * The <code>reset</code> method of <code>InputStream</code> throws 
  206.      * an <code>IOException</code>, because input streams, by default, do 
  207.      * not support <code>mark</code> and <code>reset</code>.
  208.      * <p>
  209.      * Stream marks are intended to be used in
  210.      * situations where you need to read ahead a little to see what's in
  211.      * the stream. Often this is most easily done by invoking some
  212.      * general parser. If the stream is of the type handled by the
  213.      * parser, it just chugs along happily. If the stream is not of
  214.      * that type, the parser should toss an exception when it fails,
  215.      * which, if it happens within readlimit bytes, allows the outer
  216.      * code to reset the stream and try another parser.
  217.      *
  218.      * @exception  IOException  if this stream has not been marked or if the
  219.      *               mark has been invalidated.
  220.      * @see     java.io.InputStream#mark(int)
  221.      * @see     java.io.IOException
  222.      */
  223.     public synchronized void reset() throws IOException {
  224.     throw new IOException("mark/reset not supported");
  225.     }
  226.  
  227.     /**
  228.      * Tests if this input stream supports the <code>mark</code> 
  229.      * and <code>reset</code> methods. The <code>markSupported</code> 
  230.      * method of <code>InputStream</code> returns <code>false</code>. 
  231.      *
  232.      * @return  <code>true</code> if this true type supports the mark and reset
  233.      *          method; <code>false</code> otherwise.
  234.      * @see     java.io.InputStream#mark(int)
  235.      * @see     java.io.InputStream#reset()
  236.      */
  237.     public boolean markSupported() {
  238.     return false;
  239.     }
  240. }
  241.