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   * @version 0.0
  50   *
  51   * @author Aaron M. Renn (arenn@urbanophile.com)
  52   */
  53 public class BufferedOutputStream extends FilterOutputStream
  54 {
  55
  56 /*************************************************************************/
  57
  58 /*
  59  * Class Variables
  60  */
  61
  62 /**
  63   * This is the default buffer size
  64   */
  65 private static final int DEFAULT_BUFFER_SIZE = 512;
  66
  67 /*************************************************************************/
  68
  69 /*
  70  * Instance Variables
  71  */
  72
  73 /**
  74   * This is the internal byte array used for buffering output before
  75   * writing it.
  76   */
  77 protected byte[] buf;
  78
  79 /**
  80   * This is the number of bytes that are currently in the buffer and
  81   * are waiting to be written to the underlying stream.  It always points to
  82   * the index into the buffer where the next byte of data will be stored
  83   */
  84 protected int count;
  85
  86 /*************************************************************************/
  87
  88 /*
  89  * Constructors
  90  */
  91
  92 /**
  93   * This method initializes a new <code>BufferedOutputStream</code> instance
  94   * that will write to the specified subordinate <code>OutputStream</code>
  95   * and which will use a default buffer size of 512 bytes.
  96   *
  97   * @param out The underlying <code>OutputStream</code> to write data to
  98   */
  99 public
 100 BufferedOutputStream(OutputStream out)
 101 {
 102   this(out, DEFAULT_BUFFER_SIZE);
 103 }
 104
 105 /*************************************************************************/
 106
 107 /**
 108   * This method initializes a new <code>BufferedOutputStream</code> instance
 109   * that will write to the specified subordinate <code>OutputStream</code>
 110   * and which will use the specified buffer size
 111   *
 112   * @param out The underlying <code>OutputStream</code> to write data to
 113   * @param size The size of the internal buffer
 114   */
 115 public
 116 BufferedOutputStream(OutputStream out, int size)
 117 {
 118   super(out);
 119
 120   buf = new byte[size];
 121 }
 122
 123 /*************************************************************************/
 124
 125 /*
 126  * Instance Methods
 127  */
 128
 129 /**
 130   * This method causes any currently buffered bytes to be immediately
 131   * written to the underlying output stream.
 132   *
 133   * @exception IOException If an error occurs
 134   */
 135 public synchronized void
 136 flush() throws IOException
 137 {
 138   if (count == 0)
 139     return;
 140
 141   out.write(buf, 0, count);
 142   count = 0;
 143   out.flush();
 144 }
 145
 146 /*************************************************************************/
 147
 148 /*
 149   * This method flushes any remaining buffered bytes then closes the
 150   * underlying output stream.  Any further attempts to write to this stream
 151   * may throw an exception
 152   *
 153 public synchronized void
 154 close() throws IOException
 155 {
 156   flush();
 157   out.close();
 158 }
 159 */
 160
 161 /*************************************************************************/
 162
 163 /*
 164   * This method runs when the object is garbage collected.  It is
 165   * responsible for ensuring that all buffered bytes are written and
 166   * for closing the underlying stream.
 167   *
 168   * @exception IOException If an error occurs (ignored by the Java runtime)
 169   *
 170 protected void
 171 finalize() throws IOException
 172 {
 173   close();
 174 }
 175 */
 176
 177 /*************************************************************************/
 178
 179 /**
 180   * This method writes a single byte of data.  This will be written to the
 181   * buffer instead of the underlying data source.  However, if the buffer
 182   * is filled as a result of this write request, it will be flushed to the
 183   * underlying output stream.
 184   *
 185   * @param b The byte of data to be written, passed as an int
 186   *
 187   * @exception IOException If an error occurs
 188   */
 189 public synchronized void
 190 write(int b) throws IOException
 191 {
 192   if (count == buf.length)
 193     flush();
 194
 195   buf[count] = (byte)(b & 0xFF);
 196   ++count;
 197 }
 198
 199 /*************************************************************************/
 200
 201 /**
 202   * This method writes <code>len</code> bytes from the byte array
 203   * <code>buf</code> starting at position <code>offset</code> in the buffer.
 204   * These bytes will be written to the internal buffer.  However, if this
 205   * write operation fills the buffer, the buffer will be flushed to the
 206   * underlying output stream.
 207   *
 208   * @param buf The array of bytes to write.
 209   * @param offset The index into the byte array to start writing from.
 210   * @param len The number of bytes to write.
 211   *
 212   * @exception IOException If an error occurs
 213   */
 214 public synchronized void
 215 write(byte[] buf, int offset, int len) throws IOException
 216 {
 217   // Buffer can hold everything.  Note that the case where LEN < 0
 218   // is automatically handled by the downstream write.
 219   if (len < (this.buf.length - count))
 220     {
 221       System.arraycopy(buf, offset, this.buf, count, len);
 222       count += len;
 223     }
 224   else
 225     {
 226       // The write was too big.  So flush the buffer and write the new
 227       // bytes directly to the underlying stream, per the JDK 1.2
 228       // docs.
 229       flush();
 230       out.write (buf, offset, len);
 231     }
 232 }
 233
 234 } // class BufferedOutputStream