libjava/java/io/ByteArrayOutputStream.java

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