home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / ProgLangD.iso / VCAFE.3.0A / Main.bin / Reader.java < prev    next >
Text File  |  1998-09-22  |  7KB  |  216 lines
  1. /*
  2.  * @(#)Reader.java    1.9 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. /**
  19.  * Abstract class for reading character streams.  The only methods that a
  20.  * subclass must implement are read(char[], int, int) and close().  Most
  21.  * subclasses, however, will override some of the methods defined here in order
  22.  * to provide higher efficiency, additional functionality, or both.
  23.  *
  24.  * 
  25.  * @see BufferedReader
  26.  * @see   LineNumberReader
  27.  * @see CharArrayReader
  28.  * @see InputStreamReader
  29.  * @see   FileReader
  30.  * @see FilterReader
  31.  * @see   PushbackReader
  32.  * @see PipedReader
  33.  * @see StringReader
  34.  * @see Writer
  35.  *
  36.  * @version     1.9, 98/07/01
  37.  * @author    Mark Reinhold
  38.  * @since    JDK1.1
  39.  */
  40.  
  41. public abstract class Reader {
  42.  
  43.     /**
  44.      * The object used to synchronize operations on this stream.  For
  45.      * efficiency, a character-stream object may use an object other than
  46.      * itself to protect critical sections.  A subclass should therefore use
  47.      * the object in this field rather than <tt>this</tt> or a synchronized
  48.      * method.
  49.      */
  50.     protected Object lock;
  51.  
  52.     /**
  53.      * Create a new character-stream reader whose critical sections will
  54.      * synchronize on the reader itself.
  55.      */
  56.     protected Reader() {
  57.     this.lock = this;
  58.     }
  59.  
  60.     /**
  61.      * Create a new character-stream reader whose critical sections will
  62.      * synchronize on the given object.
  63.      */
  64.     protected Reader(Object lock) {
  65.     this.lock = lock;
  66.     }
  67.  
  68.     /**
  69.      * Read a single character.  This method will block until a character is
  70.      * available, an I/O error occurs, or the end of the stream is reached.
  71.      *
  72.      * <p> Subclasses that intend to support efficient single-character input
  73.      * should override this method.
  74.      *
  75.      * @return     The character read, as an integer in the range 0 to 16383
  76.      *             (<tt>0x00-0xffff</tt>), or -1 if the end of the stream has
  77.      *             been reached
  78.      *
  79.      * @exception  IOException  If an I/O error occurs
  80.      */
  81.     public int read() throws IOException {
  82.     char cb[] = new char[1];
  83.     if (read(cb, 0, 1) == -1)
  84.         return -1;
  85.     else
  86.         return cb[0];
  87.     }
  88.  
  89.     /**
  90.      * Read characters into an array.  This method will block until some input
  91.      * is available, an I/O error occurs, or the end of the stream is reached.
  92.      *
  93.      * @param       cbuf  Destination buffer
  94.      *
  95.      * @return      The number of bytes read, or -1 if the end of the stream
  96.      *              has been reached
  97.      *
  98.      * @exception   IOException  If an I/O error occurs
  99.      */
  100.     public int read(char cbuf[]) throws IOException {
  101.     return read(cbuf, 0, cbuf.length);
  102.     }
  103.  
  104.     /**
  105.      * Read characters into a portion of an array.  This method will block
  106.      * until some input is available, an I/O error occurs, or the end of the
  107.      * stream is reached.
  108.      *
  109.      * @param      cbuf  Destination buffer
  110.      * @param      off   Offset at which to start storing characters
  111.      * @param      len   Maximum number of characters to read
  112.      *
  113.      * @return     The number of characters read, or -1 if the end of the
  114.      *             stream has been reached
  115.      *
  116.      * @exception  IOException  If an I/O error occurs
  117.      */
  118.     abstract public int read(char cbuf[], int off, int len) throws IOException;
  119.  
  120.     /** Maximum skip-buffer size */
  121.     private static final int maxSkipBufferSize = 8192;
  122.  
  123.     /** Skip buffer, null until allocated */
  124.     private char skipBuffer[] = null;
  125.  
  126.     /**
  127.      * Skip characters.  This method will block until some characters are
  128.      * available, an I/O error occurs, or the end of the stream is reached.
  129.      *
  130.      * @param  n  The number of characters to skip
  131.      *
  132.      * @return    The number of characters actually skipped
  133.      *
  134.      * @exception  IOException  If an I/O error occurs
  135.      */
  136.     public long skip(long n) throws IOException {
  137.     int nn = (int) Math.min(n, maxSkipBufferSize);
  138.     synchronized (lock) {
  139.         if ((skipBuffer == null) || (skipBuffer.length < nn))
  140.         skipBuffer = new char[nn];
  141.         long r = n;
  142.         while (r > 0) {
  143.         int nc = read(skipBuffer, 0, nn);
  144.         if (nc == -1)
  145.             break;
  146.         r -= nc;
  147.         }
  148.         return n - r;
  149.     }
  150.     }
  151.  
  152.     /**
  153.      * Tell whether this stream is ready to be read.
  154.      *
  155.      * @return True if the next read() is guaranteed not to block for input,
  156.      * false otherwise.  Note that returning false does not guarantee that the
  157.      * next read will block.
  158.      *
  159.      * @exception  IOException  If an I/O error occurs
  160.      */
  161.     public boolean ready() throws IOException {
  162.     return false;
  163.     }
  164.  
  165.     /**
  166.      * Tell whether this stream supports the mark() operation.
  167.      */
  168.     public boolean markSupported() {
  169.     return false;
  170.     }
  171.  
  172.     /**
  173.      * Mark the present position in the stream.  Subsequent calls to reset()
  174.      * will attempt to reposition the stream to this point.  Not all
  175.      * character-input streams support the mark() operation.
  176.      *
  177.      * @param  readAheadLimit  Limit on the number of characters that may be
  178.      *                         read while still preserving the mark.  After
  179.      *                         reading this many characters, attempting to
  180.      *                         reset the stream may fail.
  181.      *
  182.      * @exception  IOException  If the stream does not support mark(),
  183.      *                          or if some other I/O error occurs
  184.      */
  185.     public void mark(int readAheadLimit) throws IOException {
  186.     throw new IOException("mark() not supported");
  187.     }
  188.  
  189.     /**
  190.      * Reset the stream.  If the stream has been marked, then attempt to
  191.      * reposition it at the mark.  If the stream has not been marked, then
  192.      * attempt to reset it in some way appropriate to the particular stream,
  193.      * for example by repositioning it to its starting point.  Not all
  194.      * character-input streams support the reset() operation, and some support
  195.      * reset() without supporting mark().
  196.      *
  197.      * @exception  IOException  If the stream has not been marked,
  198.      *                          or if the mark has been invalidated,
  199.      *                          or if the stream does not support reset(),
  200.      *                          or if some other I/O error occurs
  201.      */
  202.     public void reset() throws IOException {
  203.     throw new IOException("reset() not supported");
  204.     }
  205.  
  206.     /**
  207.      * Close the stream.  Once a stream has been closed, further read(),
  208.      * ready(), mark(), or reset() invocations will throw an IOException.
  209.      * Closing a previously-closed stream, however, has no effect.
  210.      *
  211.      * @exception  IOException  If an I/O error occurs
  212.      */
  213.      abstract public void close() throws IOException;
  214.  
  215. }
  216.