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