22.18 The Class java.io.ByteArrayOutputStream

A ByteArrayOutputStream contains an internal buffer that accumulates all the bytes written to the stream since its creation or the most recent call to the reset method. At any point, the bytes written to the stream so far may be retrieved in the form of an array of bytes or a String. The bytes written so far may also be copied to some other output stream. The size method returns the number of characters written so far.

public class ByteArrayOutputStream extends OutputStream {
	protected byte[] buf;
	protected int count;
	public ByteArrayOutputStream();
	public ByteArrayOutputStream(int size);
	public void write(int b);
	public void write(byte[] b, int off, int len)
		throws NullPointerException, IndexOutOfBoundsException;
	public int size();
	public void reset();
	public byte[] toByteArray();
	public String toString();
	public String toString(int hibyte);
	public void writeTo(OutputStream out) throws IOException;
}

22.18.1 protected byte[] buf;

An internal array of bytes. Elements buf[0] through buf[count-1] are the bytes that have been written to the stream since its creation or the last reset (§22.18.8) operation.

22.18.2 protected int count;

This value should always be nonnegative. It is the number of bytes that have been written to the stream since its creation or the last reset (§22.18.8) operation.

22.18.3 public ByteArrayOutputStream()

This constructor initializes a newly created ByteArrayOutputStream so that its internal buffer array has length 32.

22.18.4 public ByteArrayOutputStream(int size)

This constructor initializes a newly created ByteArrayOutputStream so that its internal buffer array has length size. This matters only for reasons of efficiency; the buffer array is replaced by a larger one whenever necessary to accommodate additional bytes written to the stream.

22.18.5 public void write(int b)

One byte is added on the internal buffer. The byte to be added is the eight low- order bits of the argument n. The 24 high-order bits of n are ignored.

Implements the write method of OutputStream (§22.15.1).

22.18.6 public void write(byte[] b, int off, int len) throws NullPointerException, IndexOutOfBoundsException

Elements b[off] through b[off+len-1] are appended to the internal buffer.

If b is null, a NullPointerException is thrown.

If off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown.

Overrides the write method of OutputStream (§22.15.3).

22.18.7 public int size()

The current value of count is returned.

22.18.8 public void reset()

The internal variable count is reset to zero, thereby logically discarding all bytes written to the stream so far. However, the internal buffer array, which may be quite large, remains as it is.

22.18.9 public byte[] toByteArray()

22.18.10 public String toString()

A new String is created and returned. Its length is equal to the current value of count. Its initial contents are copies of the bytes written to the stream so far-that is, elements 0 through count-1 of buf, zero-extended to produce characters. Thus, tostring() has the same effect as toString(0) (§22.18.11).

Overrides the toString method of Object (§20.1.2).

22.18.11 public String toString(int hibyte)

A new array of bytes is created and returned. Its length is equal to the current value of count. Its initial contents are copies of the bytes written to the stream so far-that is, elements 0 through count-1 of buf-with hibyte supplying the high-order eight bits of each character. Thus, character k of the result is equal to:

((hibyte & 0xff) << 8) | (buf[k] & 0xff)

See the String constructor that accepts a hibyte argument (§20.12.6).

22.18.12 public void writeTo(OutputStream out) throws IOException

The current contents of the internal buffer are written to the output stream out by the call:

out.write(buf, 0, count)

Note that if out is the same as this, the effect is simply to append to the buffer a copy of its current contents, thereby doubling the number of buffered bytes. This may not be a particularly useful effect; the point is merely that the operation does terminate, having had a sensible effect, rather than running off into an endless loop.