libjava/java/io/ByteArrayOutputStream.java

   1 /* BufferedReader.java
   2    Copyright (C) 1998, 1999, 2000, 2001 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 /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
  42  * "The Java Language Specification", ISBN 0-201-63451-1
  43  * Status:  Complete to version 1.1.
  44  */
  45
  46 /**
  47   * This class allows data to be written to a byte array buffer and
  48   * and then retrieved by an application.   The internal byte array
  49   * buffer is dynamically resized to hold all the data written.  Please
  50   * be aware that writing large amounts to data to this stream will
  51   * cause large amounts of memory to be allocated.
  52   * <p>
  53   * The size of the internal buffer defaults to 32 and it is resized
  54   * by doubling the size of the buffer.  This default size can be
  55   * overridden by using the
  56   * <code>gnu.java.io.ByteArrayOutputStream.initialBufferSize</code>
  57   * property.
  58   * <p>
  59   * There is a constructor that specified the initial buffer size and
  60   * that is the preferred way to set that value because it it portable
  61   * across all Java class library implementations.
  62   * <p>
  63   * Note that this class also has methods that convert the byte array
  64   * buffer to a <code>String</code> using either the system default or an
  65   * application specified character encoding.  Thus it can handle
  66   * multibyte character encodings.
  67   *
  68   * @version 0.0
  69   *
  70   * @author Aaron M. Renn (arenn@urbanophile.com)
  71   * @author Tom Tromey <tromey@cygnus.com>
  72   * @date September 24, 1998
  73   */
  74 public class ByteArrayOutputStream extends OutputStream
  75 {
  76   /**
  77    * This method initializes a new <code>ByteArrayOutputStream</code>
  78    * with the default buffer size of 32 bytes.  If a different initial
  79    * buffer size is desired, see the constructor
  80    * <code>ByteArrayOutputStream(int size)</code>.  For applications
  81    * where the source code is not available, the default buffer size
  82    * can be set using the system property
  83    * <code>gnu.java.io.ByteArrayOutputStream.initialBufferSize</code>
  84    */
  85   public ByteArrayOutputStream ()
  86   {
  87     this (initial_buffer_size);
  88   }
  89
  90   /**
  91    * This method initializes a new <code>ByteArrayOutputStream</code> with
  92    * a specified initial buffer size.
  93    *
  94    * @param size The initial buffer size in bytes
  95    */
  96   public ByteArrayOutputStream (int size)
  97   {
  98     buf = new byte[size];
  99     count = 0;
 100   }
 101
 102   /**
 103    * This method discards all of the bytes that have been written to
 104    * the internal buffer so far by setting the <code>count</code>
 105    * variable to 0.  The internal buffer remains at its currently
 106    * allocated size.
 107    */
 108   public synchronized void reset ()
 109   {
 110     count = 0;
 111   }
 112
 113   /**
 114    * This method returns the number of bytes that have been written to
 115    * the buffer so far.  This is the same as the value of the protected
 116    * <code>count</code> variable.  If the <code>reset</code> method is
 117    * called, then this value is reset as well.  Note that this method does
 118    * not return the length of the internal buffer, but only the number
 119    * of bytes that have been written to it.
 120    *
 121    * @return The number of bytes in the internal buffer
 122    *
 123    * @see reset
 124    */
 125   public int size ()
 126   {
 127     return count;
 128   }
 129
 130   /**
 131    * This method returns a byte array containing the bytes that have been
 132    * written to this stream so far.  This array is a copy of the valid
 133    * bytes in the internal buffer and its length is equal to the number of
 134    * valid bytes, not necessarily to the the length of the current
 135    * internal buffer.  Note that since this method allocates a new array,
 136    * it should be used with caution when the internal buffer is very large.
 137    */
 138   public synchronized byte[] toByteArray ()
 139   {
 140     byte[] ret = new byte[count];
 141     System.arraycopy(buf, 0, ret, 0, count);
 142     return ret;
 143   }
 144
 145   /**
 146    * Returns the bytes in the internal array as a <code>String</code>.  The
 147    * bytes in the buffer are converted to characters using the system default
 148    * encoding.  There is an overloaded <code>toString()</code> method that
 149    * allows an application specified character encoding to be used.
 150    *
 151    * @return A <code>String</code> containing the data written to this
 152    * stream so far
 153    */
 154   public String toString ()
 155   {
 156     return new String (buf, 0, count);
 157   }
 158
 159   /**
 160    * Returns the bytes in the internal array as a <code>String</code>.  The
 161    * bytes in the buffer are converted to characters using the specified
 162    * encoding.
 163    *
 164    * @param enc The name of the character encoding to use
 165    *
 166    * @return A <code>String</code> containing the data written to this
 167    * stream so far
 168    *
 169    * @exception UnsupportedEncodingException If the named encoding is
 170    * not available
 171    */
 172   public String toString (String enc) throws UnsupportedEncodingException
 173   {
 174     return new String (buf, 0, count, enc);
 175   }
 176
 177   /**
 178    * This method returns the bytes in the internal array as a
 179    * <code>String</code>.  It uses each byte in the array as the low
 180    * order eight bits of the Unicode character value and the passed in
 181    * parameter as the high eight bits.
 182    * <p>
 183    * This method does not convert bytes to characters in the proper way and
 184    * so is deprecated in favor of the other overloaded <code>toString</code>
 185    * methods which use a true character encoding.
 186    *
 187    * @param hibyte The high eight bits to use for each character in
 188    * the <code>String</code>
 189    *
 190    * @return A <code>String</code> containing the data written to this
 191    * stream so far
 192    *
 193    * @deprecrated
 194    */
 195   public String toString (int hibyte)
 196   {
 197     return new String (buf, 0, count, hibyte);
 198   }
 199
 200   // Resize buffer to accommodate new bytes.
 201   private void resize (int add)
 202   {
 203     if (count + add >= buf.length)
 204       {
 205         int newlen = buf.length * 2;
 206         if (count + add > newlen)
 207           newlen = count + add;
 208         byte[] newbuf = new byte[newlen];
 209         System.arraycopy(buf, 0, newbuf, 0, count);
 210         buf = newbuf;
 211       }
 212   }
 213
 214   /**
 215    * This method writes the writes the specified byte into the internal
 216    * buffer.
 217    *
 218    * @param oneByte The byte to be read passed as an int
 219    */
 220   public synchronized void write (int oneByte)
 221   {
 222     resize (1);
 223     buf[count++] = (byte) oneByte;
 224   }
 225
 226   /**
 227    * This method writes <code>len</code> bytes from the passed in array
 228    * <code>buf</code> starting at index <code>offset</code> into the
 229    * internal buffer.
 230    *
 231    * @param buffer The byte array to write data from
 232    * @param offset The index into the buffer to start writing data from
 233    * @param add The number of bytes to write
 234    */
 235   public synchronized void write (byte[] buffer, int offset, int add)
 236   {
 237     // If ADD < 0 then arraycopy will throw the appropriate error for
 238     // us.
 239     if (add >= 0)
 240       resize (add);
 241     System.arraycopy(buffer, offset, buf, count, add);
 242     count += add;
 243   }
 244
 245   /**
 246    * This method writes all the bytes that have been written to this stream
 247    * from the internal buffer to the specified <code>OutputStream</code>.
 248    *
 249    * @param out The <code>OutputStream</code> to write to
 250    *
 251    * @exception IOException If an error occurs
 252    */
 253   public synchronized void writeTo (OutputStream out) throws IOException
 254   {
 255     out.write(buf, 0, count);
 256   }
 257
 258   /**
 259    * The internal buffer where the data written is stored
 260    */
 261   protected byte[] buf;
 262
 263   /**
 264    * The number of bytes that have been written to the buffer
 265    */
 266   protected int count;
 267
 268   /**
 269    * The default initial buffer size.  Specified by the JCL.
 270    */
 271   private static final int DEFAULT_INITIAL_BUFFER_SIZE = 32;
 272
 273   // The default buffer size which can be overridden by the user.
 274   private static final int initial_buffer_size;
 275
 276   static
 277   {
 278     int r
 279       = Integer.getInteger ("gnu.java.io.ByteArrayOutputStream.initialBufferSize",
 280                             DEFAULT_INITIAL_BUFFER_SIZE).intValue ();
 281     if (r <= 0)
 282       r = DEFAULT_INITIAL_BUFFER_SIZE;
 283     initial_buffer_size = r;
 284   }
 285 }