Top Description Fields Constructors Methods
org.apache.commons.io.output

public Class ByteArrayOutputStream

extends OutputStream
Class Inheritance
Imports
java.io.IOException, .OutputStream, .UnsupportedEncodingException, java.util.ArrayList, .List
This class implements an output stream in which the data is written into a byte array. The buffer automatically grows as data is written to it.

The data can be retrieved using toByteArray() and toString().

Closing a ByteArrayOutputStream has no effect. The methods in this class can be called after the stream has been closed without generating an IOException.

This is an alternative implementation of the java.io.ByteArrayOutputStream class. The original implementation only allocates 32 bytes at the beginning. As this class is designed for heavy duty it starts at 1024 bytes. In contrast to the original it doesn't reallocate the whole memory block but allocates additional buffers. This way no buffers need to be garbage collected and the contents don't have to be copied to the new buffer. This class is designed to behave exactly like the original. The only exception is the deprecated toString(int) method that has been ignored.

Authors
Jeremias Maerki, Holger Hoffstatte
Version
$Id: ByteArrayOutputStream.java 491007 2006-12-29 13:50:34Z scolebourne $

Field Summary

Modifier and TypeField and Description
private List<E>
buffers

The list of buffers, which grows and never reduces.

private int
count

The total count of bytes written.

private byte[]
currentBuffer

The current buffer.

private int
currentBufferIndex

The index of the current buffer.

private static final byte[]
EMPTY_BYTE_ARRAY

A singleton empty byte array.

private int
filledBufferSum

The total count of bytes in all the filled buffers.

Constructor Summary

AccessConstructor and Description
public
ByteArrayOutputStream()

Creates a new byte array output stream.

public
ByteArrayOutputStream(int
the initial size
size)

Creates a new byte array output stream, with a buffer capacity of the specified size, in bytes.

Method Summary

Modifier and TypeMethod and Description
public void
close()

Overrides java.io.OutputStream.close.

Implements java.io.Closeable.close.

Closing a ByteArrayOutputStream has no effect.
private byte[]

Returns:

the buffer
getBuffer(int
the index of the buffer required
index)

Return the appropriate byte[] buffer specified by index.

private void
needNewBuffer(int
the size of the buffer if one is created
newcount)

Makes a new buffer available either by allocating a new one or re-cycling an existing one.

public synchronized void
reset()

public synchronized int
size()

public synchronized byte[]

Returns:

the current contents of this output stream, as a byte array
toByteArray()

Gets the curent contents of this byte stream as a byte array.

public String
toString()

Overrides java.lang.Object.toString.

Gets the curent contents of this byte stream as a string.
public String

Returns:

the string converted from the byte array
toString(String
the name of the character encoding
enc)

Gets the curent contents of this byte stream as a string using the specified encoding.

public void
write(byte[]
the data.
b, int
the start offset in the data.
off, int
the number of bytes to write.
len)

Overrides java.io.OutputStream.write.

Writes len bytes from the specified byte array starting at offset off to this output stream.
public synchronized void
write(int
the byte.
b)

Implements abstract java.io.OutputStream.write.

Writes the specified byte to this output stream.
public synchronized void
writeTo(OutputStream
the output stream to write to
out)

Writes the entire contents of this byte stream to the specified output stream.

Inherited from java.io.OutputStream:
flushnullOutputStreamwrite

Field Detail

buffersback to summary
private List<E> buffers

The list of buffers, which grows and never reduces.

countback to summary
private int count

The total count of bytes written.

currentBufferback to summary
private byte[] currentBuffer

The current buffer.

currentBufferIndexback to summary
private int currentBufferIndex

The index of the current buffer.

EMPTY_BYTE_ARRAYback to summary
private static final byte[] EMPTY_BYTE_ARRAY

A singleton empty byte array.

filledBufferSumback to summary
private int filledBufferSum

The total count of bytes in all the filled buffers.

Constructor Detail

ByteArrayOutputStreamback to summary
public ByteArrayOutputStream()

Creates a new byte array output stream. The buffer capacity is initially 1024 bytes, though its size increases if necessary.

ByteArrayOutputStreamback to summary
public ByteArrayOutputStream(int size)

Creates a new byte array output stream, with a buffer capacity of the specified size, in bytes.

Parameters
size:int

the initial size

Exceptions
IllegalArgumentException:
if size is negative

Method Detail

closeback to summary
public void close() throws IOException

Overrides java.io.OutputStream.close.

Implements java.io.Closeable.close.

Closing a ByteArrayOutputStream has no effect. The methods in this class can be called after the stream has been closed without generating an IOException.

Exceptions
IOException:
never (this method should not declare this exception but it has to now due to backwards compatability)
getBufferback to summary
private byte[] getBuffer(int index)

Return the appropriate byte[] buffer specified by index.

Parameters
index:int

the index of the buffer required

Returns:byte[]

the buffer

needNewBufferback to summary
private void needNewBuffer(int newcount)

Makes a new buffer available either by allocating a new one or re-cycling an existing one.

Parameters
newcount:int

the size of the buffer if one is created

resetback to summary
public synchronized void reset()
See Also
java.io.ByteArrayOutputStream#reset()
sizeback to summary
public synchronized int size()
See Also
java.io.ByteArrayOutputStream#size()
toByteArrayback to summary
public synchronized byte[] toByteArray()

Gets the curent contents of this byte stream as a byte array. The result is independent of this stream.

Returns:byte[]

the current contents of this output stream, as a byte array

See Also
java.io.ByteArrayOutputStream#toByteArray()
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Gets the curent contents of this byte stream as a string.

Returns:String

Doc from java.lang.Object.toString.

a string representation of the object.

See Also
java.io.ByteArrayOutputStream#toString()
toStringback to summary
public String toString(String enc) throws UnsupportedEncodingException

Gets the curent contents of this byte stream as a string using the specified encoding.

Parameters
enc:String

the name of the character encoding

Returns:String

the string converted from the byte array

Exceptions
UnsupportedEncodingException:
if the encoding is not supported
See Also
java.io.ByteArrayOutputStream#toString(String)
writeback to summary
public void write(byte[] b, int off, int len)

Overrides java.io.OutputStream.write.

Doc from java.io.OutputStream.write.

Writes len bytes from the specified byte array starting at offset off to this output stream. The general contract for write(b, off, len) is that some of the bytes in the array b are written to the output stream in order; element b[off] is the first byte written and b[off+len-1] is the last byte written by this operation.

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.

Parameters
b:byte[]

the data.

off:int

the start offset in the data.

len:int

the number of bytes to write.

See Also
java.io.OutputStream#write(byte[], int, int)
writeback to summary
public synchronized void write(int b)

Implements abstract java.io.OutputStream.write.

Doc from java.io.OutputStream.write.

Writes the specified byte to this output stream. The general contract for write is that one byte is written to the output stream. The byte to be written is the eight low-order bits of the argument b. The 24 high-order bits of b are ignored.

Parameters
b:int

the byte.

See Also
java.io.OutputStream#write(int)
writeToback to summary
public synchronized void writeTo(OutputStream out) throws IOException

Writes the entire contents of this byte stream to the specified output stream.

Parameters
out:OutputStream

the output stream to write to

Exceptions
IOException:
if an I/O error occurs, such as if the stream is closed
See Also
java.io.ByteArrayOutputStream#writeTo(OutputStream)