jsimple.io

Class ByteArrayOutputStream

java.lang.Object

jsimple.lang.AutoCloseable

jsimple.io.OutputStream

jsimple.io.ByteArrayOutputStream

All Implemented Interfaces:

java.lang.AutoCloseable

public class ByteArrayOutputStream
extends OutputStream

This class was based on, and modified from, the Apache Harmony java.io.ByteArrayOutputStream class. Unlike the Java OutputStream class, none of the methods are synchronized & this class provides a way to get the underlying byte array without copying it.

A specialized OutputStream for class for writing content to an (internal) byte array. As bytes are written to this stream, the byte array may be expanded to hold more bytes. When the writing is considered to be finished, the byte array can be requested from the class.

See Also:

ByteArrayInputStream

Field Summary

Fields

Modifier and Type	Field and Description
protected byte[]	buffer The byte array containing the bytes written.
protected int	count The number of bytes written.

Constructor Summary

Constructors

Constructor and Description
ByteArrayOutputStream() Constructs a new ByteArrayOutputStream with a default size of 32 bytes.
ByteArrayOutputStream(int size) Constructs a new ByteArrayOutputStream with a default size of size bytes.

Method Summary

Modifier and Type	Method and Description
ByteArrayRange	closeAndGetByteArray() Closes the stream and returns its contents as a ByteArrayRange.
protected void	doClose() Closes this stream.
ByteArrayRange	getByteArray() Returns the contents of this ByteArrayOutputStream as a byte array.
int	getLength() Returns the total number of bytes written to this stream so far.
void	reset() Resets this stream to the beginning of the underlying byte array.
byte[]	toByteArray() Returns the contents of this ByteArrayOutputStream as a byte array.
void	write(byte[] buffer, int offset, int length) Writes count bytes from the byte array buffer starting at offset index to this stream.
void	write(int oneByte) Writes the specified byte oneByte to the OutputStream.

Methods inherited from class jsimple.io.OutputStream

close, flush, getClosedListener, setClosedListener, write, write, writeLatin1EncodedString, writeUtf8EncodedString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

buffer

protected byte[] buffer

The byte array containing the bytes written.

count

protected int count

The number of bytes written.

Constructor Detail

ByteArrayOutputStream

public ByteArrayOutputStream()

Constructs a new ByteArrayOutputStream with a default size of 32 bytes. If more than 32 bytes are written to this instance, the underlying byte array will expand.

ByteArrayOutputStream

public ByteArrayOutputStream(int size)

Constructs a new ByteArrayOutputStream with a default size of size bytes. If more than size bytes are written to this instance, the underlying byte array will expand.

Parameters:

size - initial size for the underlying byte array, must be non-negative

Method Detail

doClose

protected void doClose()

Closes this stream. This releases system resources used for this stream.

Specified by:

doClose in class OutputStream

closeAndGetByteArray

public ByteArrayRange closeAndGetByteArray()

Closes the stream and returns its contents as a ByteArrayRange. Only the first ByteArrayRange.getLength() bytes of the ByteArrayRange contain the stream data--the remainder is is just overage that never got used. The caller can use ByteArrayRange.toByteArray() if they wish to obtain a byte[] of exactly the right length. Doing that normally results in making a copy, unless the source byte array is already exactly the right size, and is less efficient. On the other hand, getting a byte array of exactly the right size can be more convenient in some cases & if it'll stick around for a long time more memory efficient.

Returns:

this stream's current contents as a byte array; the array can be arbitrarily big, but only the first ByteArrayRange.getLength() bytes contain stream data

reset

public void reset()

Resets this stream to the beginning of the underlying byte array. All subsequent writes will overwrite any bytes previously stored in this stream.

getLength

public int getLength()

Returns the total number of bytes written to this stream so far.

Returns:

the number of bytes written to this stream

getByteArray

public ByteArrayRange getByteArray()

Returns the contents of this ByteArrayOutputStream as a byte array. Only the first length[0] bytes of this array contain the stream data. Unlike the standard Java implementation, this just returns a reference to the internal byte array. That has the advantage of superior performance--no needless copy is needed--but the caller should be careful not to modify the array & be aware that it can change as more data is written to the stream.

Returns:

this stream's current contents as a byte array; the array can be arbitrarily big, but only the first length[0] bytes contain stream data

toByteArray

public byte[] toByteArray()

Returns the contents of this ByteArrayOutputStream as a byte array. Unlike getByteArray(int[] length) this method returns an array of exactly the right size, containing just the data in question and no more, and the returned array is a copy of the data, so the caller need not be concerned about the array changing as more data is written. However, that convenience comes at the expense of performance, as an extra copy is required.

Returns:

a copy of the contents of this stream

write

public void write(byte[] buffer,
                  int offset,
                  int length)

Writes count bytes from the byte array buffer starting at offset index to this stream.

Overrides:

write in class OutputStream

Parameters:

buffer - the buffer to be written.

offset - the initial position in buffer to retrieve bytes.

length - the number of bytes of buffer to write.

Throws:

java.lang.NullPointerException - if buffer is null.

java.lang.IndexOutOfBoundsException - if offset < 0 or len < 0, or if offset + len is greater than the length of buffer.

write

public void write(int oneByte)

Writes the specified byte oneByte to the OutputStream. Only the low order byte of oneByte is written.

Specified by:

write in class OutputStream

Parameters:

oneByte - the byte to be written.