org.hsqldb.lib

Class ClosableByteArrayOutputStream

java.lang.Object

java.io.OutputStream

org.hsqldb.lib.ClosableByteArrayOutputStream

All Implemented Interfaces:

java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable

public class ClosableByteArrayOutputStream
extends java.io.OutputStream

Provides true Closable semantics ordinarily missing in a ByteArrayOutputStream.

Accumulates output in a byte array that automatically grows as needed.

Data is retrieved using toByteArray(), toByteArrayInputStream(), toString() and toString(encoding).

Closing a ClosableByteArrayOutputStream prevents further write operations, but all other operations may succeed until after the first invocation of free().

Freeing a ClosableByteArrayOutputStream closes the stream and releases the internal buffer, preventing successful invocation of all operations, with the exception of size(), close(), isClosed(), free() and isFreed().

This class is especially useful when an accumulating output stream must be handed off to an extenal client under contract that the stream should exhibit true Closable behaviour in response both to internally tracked events and to client invocation of the OutputStream.close() method.

Since:

1.9.0

Constructor Summary

Constructors

Constructor and Description
ClosableByteArrayOutputStream() Creates a new output stream.
ClosableByteArrayOutputStream(int size) Creates a new output stream with a buffer capacity of the specified size, in bytes.

Method Summary

Modifier and Type	Method and Description
int	capacity() Returns the current capacity of this stream's data buffer.
void	close() Closes this object for further writing.
void	flush() By default, does nothing.
void	free() Closes this object and releases the underlying buffer for garbage collection.
boolean	isClosed() Retrieves whether this stream is closed.
boolean	isFreed() Retrieves whether this stream is freed.
void	reset() Resets the count field of this output stream to zero, so that all currently accumulated data is effectively discarded.
void	setSize(int newSize) Sets the size of this stream's accumulated data.
int	size() Returns the current size of this stream's accumated data.
byte[]	toByteArray() Retrieves a copy of this stream's accumated data, as a byte array.
java.io.ByteArrayInputStream	toByteArrayInputStream() Performs an effecient (zero-copy) conversion of the data accumulated in this output stream to an input stream.
java.lang.String	toString() Converts this stream's accumuated data into a string, translating bytes into characters according to the platform's default character encoding.
java.lang.String	toString(java.lang.String enc) Converts this stream's accumuated data into a string, translating bytes into characters according to the specified character encoding.
void	trimToSize() Attempts to reduce this stream's capacity to its current size.
void	write(byte[] b, int off, int len) Writes the specified portion of the designated octet sequence.
void	write(int b) Writes the specified single byte.
void	writeTo(java.io.OutputStream out) Writes the complete contents of this stream's accumulated data to the specified output stream.

Methods inherited from class java.io.OutputStream

write

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ClosableByteArrayOutputStream

public ClosableByteArrayOutputStream()

Creates a new output stream.

The buffer capacity is initially 32 bytes, though its size increases if necessary.

ClosableByteArrayOutputStream

public ClosableByteArrayOutputStream(int size)
                              throws java.lang.IllegalArgumentException

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

Parameters:

size - the initial size.

Throws:

java.lang.IllegalArgumentException - if size is negative.

Method Detail

write

public void write(int b)
           throws java.io.IOException

Writes the specified single byte.

Specified by:

write in class java.io.OutputStream

Parameters:

b - the single byte to be written.

Throws:

java.io.IOException - if an I/O error occurs. In particular, an IOException may be thrown if this output stream has been closed.

write

public void write(byte[] b,
                  int off,
                  int len)
           throws java.io.IOException

Writes the specified portion of the designated octet sequence.

Overrides:

write in class java.io.OutputStream

Parameters:

b - the data.

off - the start offset in the data.

len - the number of bytes to write.

Throws:

java.io.IOException - if an I/O error occurs. In particular, an IOException may be thrown if this output stream has been closed.

flush

public void flush()
           throws java.io.IOException

By default, does nothing.

Specified by:

flush in interface java.io.Flushable

Overrides:

flush in class java.io.OutputStream

Throws:

java.io.IOException - if an I/O error occurs. In particular, an IOException may be thrown if this output stream has been closed.

writeTo

public void writeTo(java.io.OutputStream out)
             throws java.io.IOException

Writes the complete contents of this stream's accumulated data to the specified output stream.

The operation occurs as if by calling out.write(buf, 0, count).

Parameters:

out - the output stream to which to write the data.

Throws:

java.io.IOException - if an I/O error occurs. In particular, an IOException may be thrown if this output stream has been freed.

capacity

public int capacity()
             throws java.io.IOException

Returns the current capacity of this stream's data buffer.

Returns:

the length of the internal data array

Throws:

java.io.IOException - if an I/O error occurs. In particular, an IOException may be thrown if this output stream has been freed.

reset

public void reset()
           throws java.io.IOException

Resets the count field of this output stream to zero, so that all currently accumulated data is effectively discarded.

Further write operations will reuse the allocated buffer space.

Throws:

java.io.IOException - if an I/O error occurs. In particular, an IOException may be thrown if this output stream has been closed.

See Also:

count

trimToSize

public void trimToSize()
                throws java.io.IOException

Attempts to reduce this stream's capacity to its current size.

If the data buffer is larger than necessary to hold its current sequence of bytes, then it may be resized to become more space efficient. Calling this method may, but is not required to, affect the value returned by a subsequent call to the capacity() method.

Throws:

java.io.IOException - if an I/O error occurs. In particular, an IOException may be thrown if this output stream has been freed.

toByteArray

public byte[] toByteArray()
                   throws java.io.IOException

Retrieves a copy of this stream's accumated data, as a byte array.

Returns:

a copy of this stream's accumated data, as a byte array.

Throws:

java.io.IOException - if an I/O error occurs. In particular, an IOException may be thrown if this output stream has been freed.

See Also:

size()

size

public int size()
         throws java.io.IOException

Returns the current size of this stream's accumated data.

Returns:

the value of the count field, which is the number of valid bytes in this output stream.

Throws:

java.io.IOException - never

See Also:

count

setSize

public void setSize(int newSize)

Sets the size of this stream's accumulated data.

Parameters:

newSize - the new size

Throws:

java.lang.ArrayIndexOutOfBoundsException - if new size is negative

toByteArrayInputStream

public java.io.ByteArrayInputStream toByteArrayInputStream()
                                                    throws java.io.IOException

Performs an effecient (zero-copy) conversion of the data accumulated in this output stream to an input stream.

To ensure the future integrity of the resulting input stream, free is invoked upon this output stream as a side-effect.

Returns:

an input stream representing this output stream's accumulated data

Throws:

java.io.IOException - if an I/O error occurs. In particular, an IOException may be thrown if this output stream has been freed.

toString

public java.lang.String toString()

Converts this stream's accumuated data into a string, translating bytes into characters according to the platform's default character encoding.

Overrides:

toString in class java.lang.Object

Returns:

String translated from this stream's accumuated data.

Throws:

java.lang.RuntimeException - may be thrown if this output stream has been freed.

toString

public java.lang.String toString(java.lang.String enc)
                          throws java.io.IOException,
                                 java.io.UnsupportedEncodingException

Converts this stream's accumuated data into a string, translating bytes into characters according to the specified character encoding.

Parameters:

enc - a character-encoding name.

Returns:

String translated from the buffer's contents.

Throws:

java.io.IOException - may be thrown if this output stream has been freed.

java.io.UnsupportedEncodingException - If the named encoding is not supported.

close

public void close()
           throws java.io.IOException

Closes this object for further writing.

Other operations may continue to succeed until after the first invocation of free().

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Overrides:

close in class java.io.OutputStream

Throws:

java.io.IOException - if an I/O error occurs (default: never)

isClosed

public boolean isClosed()

Retrieves whether this stream is closed.

Returns:

true if this stream is closed, else false

free

public void free()
          throws java.io.IOException

Closes this object and releases the underlying buffer for garbage collection.

Throws:

java.io.IOException - if an I/O error occurs while closing this stream (default: never).

isFreed

public boolean isFreed()

Retrieves whether this stream is freed.

Returns:

true if this stream is freed; else false.