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