org.apache.commons.io.output

Class ByteArrayOutputStream


public class ByteArrayOutputStream
extends OutputStream

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.

Version:
$Id: ByteArrayOutputStream.java 610010 2008-01-08 14:50:59Z niallp $
Authors:
Jeremias Maerki
Holger Hoffstatte

Field Summary

private static byte[]
EMPTY_BYTE_ARRAY
A singleton empty byte array.
private List
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 int
filledBufferSum
The total count of bytes in all the filled buffers.

Constructor Summary

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

Method Summary

void
close()
Closing a ByteArrayOutputStream has no effect.
private byte[]
getBuffer(int index)
Return the appropriate byte[] buffer specified by index.
private void
needNewBuffer(int newcount)
Makes a new buffer available either by allocating a new one or re-cycling an existing one.
void
reset()
int
size()
Return the current size of the byte array.
byte[]
toByteArray()
Gets the curent contents of this byte stream as a byte array.
String
toString()
Gets the curent contents of this byte stream as a string.
String
toString(String enc)
Gets the curent contents of this byte stream as a string using the specified encoding.
int
write(InputStream in)
Writes the entire contents of the specified input stream to this byte stream.
void
write(byte[] b, int off, int len)
Write the bytes to byte array.
void
write(int b)
Write a byte to byte array.
void
writeTo(OutputStream out)
Writes the entire contents of this byte stream to the specified output stream.

Field Details

EMPTY_BYTE_ARRAY

private static final byte[] EMPTY_BYTE_ARRAY
A singleton empty byte array.

buffers

private List buffers
The list of buffers, which grows and never reduces.

count

private int count
The total count of bytes written.

currentBuffer

private byte[] currentBuffer
The current buffer.

currentBufferIndex

private int currentBufferIndex
The index of the current buffer.

filledBufferSum

private int filledBufferSum
The total count of bytes in all the filled buffers.

Constructor Details

ByteArrayOutputStream

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

ByteArrayOutputStream

public ByteArrayOutputStream(int size)
Creates a new byte array output stream, with a buffer capacity of the specified size, in bytes.
Parameters:
size - the initial size

Method Details

close

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

getBuffer

private byte[] getBuffer(int index)
Return the appropriate byte[] buffer specified by index.
Parameters:
index - the index of the buffer required
Returns:
the buffer

needNewBuffer

private void needNewBuffer(int newcount)
Makes a new buffer available either by allocating a new one or re-cycling an existing one.
Parameters:
newcount - the size of the buffer if one is created

reset

public void reset()
See Also:
java.io.ByteArrayOutputStream.reset()

size

public int size()
Return the current size of the byte array.
Returns:
the current size of the byte array

toByteArray

public byte[] toByteArray()
Gets the curent contents of this byte stream as a byte array. The result is independent of this stream.
Returns:
the current contents of this output stream, as a byte array
See Also:
java.io.ByteArrayOutputStream.toByteArray()

toString

public String toString()
Gets the curent contents of this byte stream as a string.
Returns:
the contents of the byte array as a String
See Also:
java.io.ByteArrayOutputStream.toString()

toString

public String toString(String enc)
            throws UnsupportedEncodingException
Gets the curent contents of this byte stream as a string using the specified encoding.
Parameters:
enc - the name of the character encoding
Returns:
the string converted from the byte array
See Also:
java.io.ByteArrayOutputStream.toString(String)

write

public int write(InputStream in)
            throws IOException
Writes the entire contents of the specified input stream to this byte stream. Bytes from the input stream are read directly into the internal buffers of this streams.
Parameters:
in - the input stream to read from
Returns:
total number of bytes read from the input stream (and written to this stream)
Since:
Commons IO 1.4

write

public void write(byte[] b,
                  int off,
                  int len)
Write the bytes to byte array.
Parameters:
b - the bytes to write
off - The start offset
len - The number of bytes to write

write

public void write(int b)
Write a byte to byte array.
Parameters:
b - the byte to write

writeTo

public void writeTo(OutputStream out)
            throws IOException
Writes the entire contents of this byte stream to the specified output stream.
Parameters:
out - the output stream to write to
See Also:
java.io.ByteArrayOutputStream.writeTo(OutputStream)

Copyright (c) 2002-2009 Apache Software Foundation