libjava/java/io/PipedWriter.java

   1 /* PipedWriter.java -- Write portion of piped character streams.
   2    Copyright (C) 1998, 2000, 2001, 2003 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.io;
  40
  41 // NOTE: This implementation is very similar to that of PipedOutputStream.
  42 // If you fix a bug in here, chances are you should make a similar change to
  43 // the PipedOutputStream code.
  44
  45 /**
  46   * This class writes its chars to a <code>PipedReader</code> to
  47   * which it is connected.
  48   * <p>
  49   * It is highly recommended that a <code>PipedWriter</code> and its
  50   * connected <code>PipedReader</code> be in different threads.  If
  51   * they are in the same thread, read and write operations could deadlock
  52   * the thread.
  53   *
  54   * @author Aaron M. Renn (arenn@urbanophile.com)
  55   */
  56 public class PipedWriter extends Writer
  57 {
  58   /** Target PipedReader to which this is connected. Null only if this
  59     * Writer hasn't been connected yet. */
  60   PipedReader sink;
  61
  62   /** Set to true if close() has been called on this Writer. */
  63   boolean closed;
  64
  65   /** Buffer used to implement single-argument write */
  66   char[] read_buf = new char[1];
  67
  68   /**
  69     * Create an unconnected PipedWriter.  It must be connected
  70     * to a <code>PipedReader</code> using the <code>connect</code>
  71     * method prior to writing any data or an exception will be thrown.
  72     */
  73   public PipedWriter()
  74   {
  75   }
  76
  77   /**
  78      * Create a new <code>PipedWriter</code> instance
  79     * to write to the specified <code>PipedReader</code>.  This stream
  80     * is then ready for writing.
  81     *
  82     * @param sink The <code>PipedReader</code> to connect this stream to.
  83     *
  84     * @exception IOException If <code>sink</code> has already been connected
  85     *                        to a different PipedWriter.
  86     */
  87   public PipedWriter(PipedReader sink) throws IOException
  88   {
  89     sink.connect(this);
  90   }
  91
  92   /**
  93     * Connects this object to the specified <code>PipedReader</code>
  94     * object.  This stream will then be ready for writing.
  95     *
  96     * @param sink The <code>PipedReader</code> to connect this stream to
  97     *
  98     * @exception IOException If the stream has not been connected or has
  99     *                        been closed.
 100     */
 101   public void connect(PipedReader sink) throws IOException
 102   {
 103     if (this.sink != null || sink.source != null)
 104       throw new IOException ("Already connected");
 105     sink.connect(this);
 106   }
 107
 108   /**
 109     * Write a single char of date to the stream.  Note that this method will
 110     * block if the <code>PipedReader</code> to which this object is
 111     * connected has a full buffer.
 112     *
 113     * @param b The char of data to be written, passed as an <code>int</code>.
 114     *
 115     * @exception IOException If the stream has not been connected or has
 116     *                        been closed.
 117     */
 118   public void write(int b) throws IOException
 119   {
 120     read_buf[0] = (char) (b & 0xffff);
 121     sink.receive (read_buf, 0, 1);
 122   }
 123
 124   /**
 125     * This method writes <code>len</code> chars of data from the char array
 126     * <code>buf</code> starting at index <code>offset</code> in the array
 127     * to the stream.  Note that this method will block if the
 128     * <code>PipedReader</code> to which this object is connected has
 129     * a buffer that cannot hold all of the chars to be written.
 130     *
 131     * @param buf The array containing chars to write to the stream.
 132     * @param offset The index into the array to start writing chars from.
 133     * @param len The number of chars to write.
 134     *
 135     * @exception IOException If the stream has not been connected or has
 136     *                        been closed.
 137     */
 138   public void write(char[] b, int off, int len) throws IOException
 139   {
 140     if (sink == null)
 141       throw new IOException ("Not connected");
 142     if (closed)
 143       throw new IOException ("Pipe closed");
 144
 145     sink.receive (b, off, len);
 146   }
 147
 148   /**
 149     * This method does nothing.
 150     *
 151     * @exception IOException If the stream is closed.
 152     * @specnote You'd think that this method would block until the sink
 153     *           had read all available data. Thats not the case - this method
 154     *           appears to be a no-op?
 155     */
 156   public void flush() throws IOException
 157   {
 158     if (closed)
 159       throw new IOException ("Pipe closed");
 160   }
 161
 162   /**
 163     * This method closes this stream so that no more data can be written
 164     * to it. Any further attempts to write to this stream may throw an
 165     * exception
 166     *
 167     * @exception IOException If an error occurs
 168     */
 169   public void close() throws IOException
 170   {
 171     // A close call on an unconnected PipedWriter has no effect.
 172     if (sink != null)
 173       {
 174         closed = true;
 175         // Notify any waiting readers that the stream is now closed.
 176         synchronized (sink)
 177         {
 178           sink.notifyAll();
 179         }
 180       }
 181   }
 182 }