libjava/java/io/BufferedOutputStream.java

   1 /* BufferedOutputStream.java -- Buffer output into large blocks before writing
   2    Copyright (C) 1998, 2000, 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 /**
  42   * This class accumulates bytes written in a buffer instead of immediately
  43   * writing the data to the underlying output sink. The bytes are instead
  44   * as one large block when the buffer is filled, or when the stream is
  45   * closed or explicitly flushed. This mode operation can provide a more
  46   * efficient mechanism for writing versus doing numerous small unbuffered
  47   * writes.
  48   *
  49   * @author Aaron M. Renn (arenn@urbanophile.com)
  50   */
  51 public class BufferedOutputStream extends FilterOutputStream
  52 {
  53   /**
  54    * This is the default buffer size
  55    */
  56   private static final int DEFAULT_BUFFER_SIZE = 512;
  57
  58   /**
  59    * This is the internal byte array used for buffering output before
  60    * writing it.
  61    */
  62   protected byte[] buf;
  63
  64   /**
  65    * This is the number of bytes that are currently in the buffer and
  66    * are waiting to be written to the underlying stream.  It always points to
  67    * the index into the buffer where the next byte of data will be stored
  68    */
  69   protected int count;
  70
  71   /**
  72    * This method initializes a new <code>BufferedOutputStream</code> instance
  73    * that will write to the specified subordinate <code>OutputStream</code>
  74    * and which will use a default buffer size of 512 bytes.
  75    *
  76    * @param out The underlying <code>OutputStream</code> to write data to
  77    */
  78   public BufferedOutputStream(OutputStream out)
  79   {
  80     this(out, DEFAULT_BUFFER_SIZE);
  81   }
  82
  83   /**
  84    * This method initializes a new <code>BufferedOutputStream</code> instance
  85    * that will write to the specified subordinate <code>OutputStream</code>
  86    * and which will use the specified buffer size
  87    *
  88    * @param out The underlying <code>OutputStream</code> to write data to
  89    * @param size The size of the internal buffer
  90    */
  91   public BufferedOutputStream(OutputStream out, int size)
  92   {
  93     super(out);
  94
  95     buf = new byte[size];
  96   }
  97
  98   /**
  99    * This method causes any currently buffered bytes to be immediately
 100    * written to the underlying output stream.
 101    *
 102    * @exception IOException If an error occurs
 103    */
 104   public synchronized void flush() throws IOException
 105   {
 106     if (count == 0)
 107       return;
 108
 109     out.write(buf, 0, count);
 110     count = 0;
 111     out.flush();
 112   }
 113
 114   /**
 115    * This method flushes any remaining buffered bytes then closes the
 116    * underlying output stream.  Any further attempts to write to this stream
 117    * may throw an exception
 118    *
 119   public synchronized void close() throws IOException
 120   {
 121     flush();
 122     out.close();
 123   }
 124   */
 125
 126   /**
 127    * This method runs when the object is garbage collected.  It is
 128    * responsible for ensuring that all buffered bytes are written and
 129    * for closing the underlying stream.
 130    *
 131    * @exception IOException If an error occurs (ignored by the Java runtime)
 132    *
 133   protected void finalize() throws IOException
 134   {
 135     close();
 136   }
 137   */
 138
 139   /**
 140    * This method writes a single byte of data.  This will be written to the
 141    * buffer instead of the underlying data source.  However, if the buffer
 142    * is filled as a result of this write request, it will be flushed to the
 143    * underlying output stream.
 144    *
 145    * @param b The byte of data to be written, passed as an int
 146    *
 147    * @exception IOException If an error occurs
 148    */
 149   public synchronized void write(int b) throws IOException
 150   {
 151     if (count == buf.length)
 152       flush();
 153
 154     buf[count] = (byte)(b & 0xFF);
 155     ++count;
 156   }
 157
 158   /**
 159    * This method writes <code>len</code> bytes from the byte array
 160    * <code>buf</code> starting at position <code>offset</code> in the buffer.
 161    * These bytes will be written to the internal buffer.  However, if this
 162    * write operation fills the buffer, the buffer will be flushed to the
 163    * underlying output stream.
 164    *
 165    * @param buf The array of bytes to write.
 166    * @param offset The index into the byte array to start writing from.
 167    * @param len The number of bytes to write.
 168    *
 169    * @exception IOException If an error occurs
 170    */
 171   public synchronized void write(byte[] buf, int offset, int len)
 172     throws IOException
 173   {
 174     // Buffer can hold everything.  Note that the case where LEN < 0
 175     // is automatically handled by the downstream write.
 176     if (len < (this.buf.length - count))
 177       {
 178         System.arraycopy(buf, offset, this.buf, count, len);
 179         count += len;
 180       }
 181     else
 182       {
 183         // The write was too big.  So flush the buffer and write the new
 184         // bytes directly to the underlying stream, per the JDK 1.2
 185         // docs.
 186         flush();
 187         out.write (buf, offset, len);
 188       }
 189   }
 190
 191 } // class BufferedOutputStream
 192