home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / io / Writer.java < prev   
Encoding:
Java Source  |  1998-03-20  |  4.5 KB  |  156 lines
  1. /*
  2.  * @(#)Writer.java    1.12 98/03/18
  3.  *
  4.  * Copyright 1996, 1997 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 writing to character streams.  The only methods that a
  20.  * subclass must implement are write(char[], int, int), flush(), and close().
  21.  * Most subclasses, however, will override some of the methods defined here in
  22.  * order to provide higher efficiency, additional functionality, or both.
  23.  *
  24.  * @see Writer
  25.  * @see   BufferedWriter
  26.  * @see   CharArrayWriter
  27.  * @see   FilterWriter
  28.  * @see   OutputStreamWriter
  29.  * @see     FileWriter
  30.  * @see   PipedWriter
  31.  * @see   PrintWriter
  32.  * @see   StringWriter
  33.  * @see Reader
  34.  *
  35.  * @version     1.12, 98/03/18
  36.  * @author    Mark Reinhold
  37.  * @since    JDK1.1
  38.  */
  39.  
  40. public abstract class Writer {
  41.  
  42.     /**
  43.      * The object used to synchronize operations on this stream.  For
  44.      * efficiency, a character-stream object may use an object other than
  45.      * itself to protect critical sections.  A subclass should therefore use
  46.      * the object in this field rather than <tt>this</tt> or a synchronized
  47.      * method.
  48.      */
  49.     protected Object lock;
  50.  
  51.     /**
  52.      * Create a new character-stream writer whose critical sections will
  53.      * synchronize on the writer itself.
  54.      */
  55.     protected Writer() {
  56.     this.lock = this;
  57.     }
  58.  
  59.     /**
  60.      * Create a new character-stream writer whose critical sections will
  61.      * synchronize on the given object.
  62.      */
  63.     protected Writer(Object lock) {
  64.     this.lock = lock;
  65.     }
  66.  
  67.     /**
  68.      * Write a single character.  The character to be written is contained in
  69.      * the 16 low-order bits of the given integer value; the 16 high-order bits
  70.      * are ignored.
  71.      *
  72.      * <p> Subclasses that intend to support efficient single-character output
  73.      * should override this method.
  74.      *
  75.      * @exception  IOException  If an I/O error occurs
  76.      */
  77.     public void write(int c) throws IOException {
  78.     synchronized (lock) {
  79.         char cb[] = new char[1];
  80.         cb[0] = (char) c;
  81.         write(cb, 0, 1);
  82.     }
  83.     }
  84.  
  85.     /**
  86.      * Write an array of characters.
  87.      *
  88.      * @param  cbuf  Array of characters to be written
  89.      * 
  90.      * @exception  IOException  If an I/O error occurs
  91.      */
  92.     public void write(char cbuf[]) throws IOException {
  93.     write(cbuf, 0, cbuf.length);
  94.     }
  95.  
  96.     /**
  97.      * Write a portion of an array of characters.
  98.      *
  99.      * @param  cbuf  Array of characters
  100.      * @param  off   Offset from which to start writing characters
  101.      * @param  len   Number of characters to write
  102.      *
  103.      * @exception  IOException  If an I/O error occurs
  104.      */
  105.     abstract public void write(char cbuf[], int off, int len) throws IOException;
  106.  
  107.     /**
  108.      * Write a string.
  109.      *
  110.      * @param  str  String to be written
  111.      *
  112.      * @exception  IOException  If an I/O error occurs
  113.      */
  114.     public void write(String str) throws IOException {
  115.     write(str, 0, str.length());
  116.     }
  117.  
  118.     /**
  119.      * Write a portion of a string.
  120.      *
  121.      * @param  str  A String
  122.      * @param  off  Offset from which to start writing characters
  123.      * @param  len  Number of characters to write
  124.      *
  125.      * @exception  IOException  If an I/O error occurs
  126.      */
  127.     public void write(String str, int off, int len) throws IOException {
  128.     synchronized (lock) {
  129.         char cbuf[] = new char[len];
  130.         str.getChars(off, len, cbuf, 0);
  131.         write(cbuf, 0, len);
  132.     }
  133.     }
  134.  
  135.     /**
  136.      * Flush the stream.  If the stream has saved any characters from the
  137.      * various write() methods in a buffer, write them immediately to their
  138.      * intended destination.  Then, if that destination is another character or
  139.      * byte stream, flush it.  Thus one flush() invocation will flush all the
  140.      * buffers in a chain of Writers and OutputStreams.
  141.      *
  142.      * @exception  IOException  If an I/O error occurs
  143.      */
  144.     abstract public void flush() throws IOException;
  145.  
  146.     /**
  147.      * Close the stream, flushing it first.  Once a stream has been closed,
  148.      * further write() or flush() invocations will cause an IOException to be
  149.      * thrown.  Closing a previously-closed stream, however, has no effect.
  150.      *
  151.      * @exception  IOException  If an I/O error occurs
  152.      */
  153.     abstract public void close() throws IOException;
  154.  
  155. }
  156.