HyperSQL Database 2.7.4 · org.hsqldb.lib.ClosableByteArrayOutputStream

Provides true Closable semantics ordinarily missing in a java.io.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 external 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.

Field Summary

Modifier and Type	Field and Description
protected byte[]	buf Data buffer.
protected boolean	closed Whether this stream is closed.
protected int	count # of valid bytes in buffer.
protected boolean	freed Whether this stream is freed.

Constructor Summary

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

Method Summary

Modifier and Type	Method and Description
public synchronized int	Returns: the length of the internal data array capacity() Returns the current capacity of this stream's data buffer.
protected synchronized void	checkClosed() Tests whether this stream is closed.
protected synchronized void	checkFreed() Tests whether this stream is freed.
public synchronized void	close() Overrides java.io.OutputStream.close. Implements java.io.Closeable.close. Closes this object for further writing.
protected byte[]	Returns: copy of `original` with the given `newLength` copyOf(byte[] the object to copy original, int the length of the copy newLength) Retrieves a copy of `original` with the given `newLength`.
public void	flush() Overrides java.io.OutputStream.flush. Implements java.io.Flushable.flush. By default, does nothing.
public synchronized void	free() Closes this object and releases the underlying buffer for garbage collection.
public synchronized boolean	Returns: `true` if this stream is closed, else `false` isClosed() Retrieves whether this stream is closed.
public synchronized boolean	Returns: `true` if this stream is freed; else `false`. isFreed() Retrieves whether this stream is freed.
public synchronized void	reset() Resets the `count` field of this output stream to zero, so that all currently accumulated data is effectively discarded.
public synchronized void	setSize(int the new size newSize) Sets the size of this stream's accumulated data.
public synchronized int	Returns: the value of the `count` field, which is the number of valid bytes in this output stream. size() Returns the current size of this stream's accumulated data.
public synchronized byte[]	Returns: a copy of this stream's accumulated data, as a byte array. toByteArray() Retrieves a copy of this stream's accumulated data, as a byte array.
public synchronized ByteArrayInputStream	Returns: an input stream representing this output stream's accumulated data toByteArrayInputStream() Performs an efficient (zero-copy) conversion of the data accumulated in this output stream to an input stream.
public synchronized String	Returns: String translated from this stream's accumulated data. toString() Overrides java.lang.Object.toString. Converts this stream's accumulated data into a string, translating bytes into characters according to the platform's default character encoding.
public synchronized String	Returns: String translated from the buffer's contents. toString(String a character-encoding name. enc) Converts this stream's accumulated data into a string, translating bytes into characters according to the specified character encoding.
public synchronized void	trimToSize() Attempts to reduce this stream's capacity to its current size.
public synchronized void	write(int the single byte to be written. b) Implements abstract java.io.OutputStream.write. Writes the specified single byte.
public synchronized 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 the specified portion of the designated octet sequence.
public synchronized void	writeTo(OutputStream the output stream to which to write the data. out) Writes the complete contents of this stream's accumulated data to the specified output stream.

Inherited from java.io.OutputStream:: nullOutputStream write

Field Detail

buf	back to summary
protected byte[] buf Data buffer.

closed	back to summary
protected boolean closed Whether this stream is closed.

count	back to summary
protected int count # of valid bytes in buffer.

freed	back to summary
protected boolean freed Whether this stream is freed.

Constructor Detail

ClosableByteArrayOutputStream	back to summary
public ClosableByteArrayOutputStream() Creates a new output stream. The buffer capacity is initially 32 bytes, though its size increases if necessary.

ClosableByteArrayOutputStream

back to summary

public ClosableByteArrayOutputStream()

Creates a new output stream.

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

ClosableByteArrayOutputStream back to summary

ClosableByteArrayOutputStream	back to summary
public ClosableByteArrayOutputStream(int size) throws IllegalArgumentException Creates a new output stream with a buffer capacity of the specified `size`, in bytes. Parameters size:int the initial size. Exceptions IllegalArgumentException: if size is negative.

public ClosableByteArrayOutputStream(int size) throws IllegalArgumentException

Creates a new 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

capacity back to summary

capacity	back to summary
public synchronized int capacity() throws IOException Returns the current capacity of this stream's data buffer. Returns:int the length of the internal data array Exceptions IOException: if an I/O error occurs. In particular, an `IOException` may be thrown if this output stream has been `freed`.

public synchronized int capacity() throws IOException

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

Returns:int

the length of the internal data array

Exceptions

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

checkClosed	back to summary
protected synchronized void checkClosed() throws IOException Tests whether this stream is closed. Exceptions IOException: if this stream is closed.

checkClosed

back to summary

protected synchronized void checkClosed() throws IOException

Tests whether this stream is closed.

Exceptions

IOException:: if this stream is closed.

checkFreed	back to summary
protected synchronized void checkFreed() throws IOException Tests whether this stream is freed. Exceptions IOException: if this stream is freed.

checkFreed

back to summary

protected synchronized void checkFreed() throws IOException

Tests whether this stream is freed.

Exceptions

IOException:: if this stream is freed.

close back to summary

close	back to summary
public synchronized void close() Overrides java.io.OutputStream.close. Implements java.io.Closeable.close. Closes this object for further writing. Other operations may continue to succeed until after the first invocation of `free()`.

public synchronized void close()

Overrides java.io.OutputStream.close.

Implements java.io.Closeable.close.

Closes this object for further writing.

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

copyOf back to summary

copyOf	back to summary
protected byte[] copyOf(byte[] original, int newLength) Retrieves a copy of `original` with the given `newLength`. Parameters original:byte[] the object to copy newLength:int the length of the copy Returns:byte[] copy of `original` with the given `newLength`

protected byte[] copyOf(byte[] original, int newLength)

Retrieves a copy of original with the given newLength.

Parameters

original:byte[]: the object to copy
newLength:int: the length of the copy

Returns:byte[]

copy of original with the given newLength

flush back to summary

flush	back to summary
public void flush() throws IOException Overrides java.io.OutputStream.flush. Implements java.io.Flushable.flush. By default, does nothing. Exceptions IOException: if an I/O error occurs. In particular, an `IOException` may be thrown if this output stream has been `closed`.

public void flush() throws IOException

Overrides java.io.OutputStream.flush.

Implements java.io.Flushable.flush.

By default, does nothing.

Exceptions

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

free	back to summary
public synchronized void free() Closes this object and releases the underlying buffer for garbage collection.

isClosed back to summary

isClosed	back to summary
public synchronized boolean isClosed() Retrieves whether this stream is closed. Returns:boolean `true` if this stream is closed, else `false`

public synchronized boolean isClosed()

Retrieves whether this stream is closed.

Returns:boolean: true if this stream is closed, else false

isFreed back to summary

isFreed	back to summary
public synchronized boolean isFreed() Retrieves whether this stream is freed. Returns:boolean `true` if this stream is freed; else `false`.

public synchronized boolean isFreed()

Retrieves whether this stream is freed.

Returns:boolean: true if this stream is freed; else false.

reset back to summary

reset	back to summary
public synchronized void reset() throws 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. Exceptions IOException: if an I/O error occurs. In particular, an `IOException` may be thrown if this output stream has been `closed`. See Also `count`

public synchronized void reset() throws 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.

Exceptions

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

See Also

count

setSize	back to summary
public synchronized void setSize(int newSize) Sets the size of this stream's accumulated data. Parameters newSize:int the new size Exceptions ArrayIndexOutOfBoundsException: if new size is negative

setSize

back to summary

public synchronized void setSize(int newSize)

Sets the size of this stream's accumulated data.

Parameters

newSize:int: the new size

Exceptions

ArrayIndexOutOfBoundsException:: if new size is negative

size back to summary

size	back to summary
public synchronized int size() Returns the current size of this stream's accumulated data. Returns:int the value of the `count` field, which is the number of valid bytes in this output stream. See Also `count`

public synchronized int size()

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

Returns:int: the value of the count field, which is the number of valid bytes in this output stream.
See Also: count

toByteArray back to summary

toByteArray	back to summary
public synchronized byte[] toByteArray() throws IOException Retrieves a copy of this stream's accumulated data, as a byte array. Returns:byte[] a copy of this stream's accumulated data, as a byte array. Exceptions IOException: if an I/O error occurs. In particular, an `IOException` may be thrown if this output stream has been `freed`. See Also `size()`

public synchronized byte[] toByteArray() throws IOException

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

Returns:byte[]

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

Exceptions

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

See Also

size()

toByteArrayInputStream back to summary

toByteArrayInputStream	back to summary
public synchronized ByteArrayInputStream toByteArrayInputStream() throws IOException Performs an efficient (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:ByteArrayInputStream an input stream representing this output stream's accumulated data Exceptions IOException: if an I/O error occurs. In particular, an `IOException` may be thrown if this output stream has been `freed`.

public synchronized ByteArrayInputStream toByteArrayInputStream() throws IOException

Performs an efficient (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:ByteArrayInputStream

an input stream representing this output stream's accumulated data

Exceptions

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

toString back to summary

toString	back to summary
public synchronized String toString() Overrides java.lang.Object.toString. Converts this stream's accumulated data into a string, translating bytes into characters according to the platform's default character encoding. Returns:String String translated from this stream's accumulated data. Exceptions RuntimeException: may be thrown if this output stream has been `freed`.

public synchronized String toString()

Overrides java.lang.Object.toString.

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

Returns:String

String translated from this stream's accumulated data.

Exceptions

RuntimeException:: may be thrown if this output stream has been freed.

toString back to summary

toString	back to summary
public synchronized String toString(String enc) throws IOException, UnsupportedEncodingException Converts this stream's accumulated data into a string, translating bytes into characters according to the specified character encoding. Parameters enc:String a character-encoding name. Returns:String String translated from the buffer's contents. Exceptions IOException: may be thrown if this output stream has been `freed`. UnsupportedEncodingException: If the named encoding is not supported.

public synchronized String toString(String enc) throws IOException, UnsupportedEncodingException

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

Parameters

enc:String: a character-encoding name.

Returns:String

String translated from the buffer's contents.

Exceptions

IOException:: may be thrown if this output stream has been freed.
UnsupportedEncodingException:: If the named encoding is not supported.

trimToSize back to summary

trimToSize	back to summary
public synchronized void trimToSize() throws 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. Exceptions IOException: if an I/O error occurs. In particular, an `IOException` may be thrown if this output stream has been `freed`.

public synchronized void trimToSize() throws 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.

Exceptions

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

write back to summary

write	back to summary
public synchronized void write(int b) throws IOException Implements abstract java.io.OutputStream.write. Writes the specified single byte. Parameters b:int the single byte to be written. Exceptions IOException: if an I/O error occurs. In particular, an `IOException` may be thrown if this output stream has been `closed`.

public synchronized void write(int b) throws IOException

Implements abstract java.io.OutputStream.write.

Writes the specified single byte.

Parameters

b:int: the single byte to be written.

Exceptions

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

write back to summary

write	back to summary
public synchronized void write(byte[] b, int off, int len) throws IOException Overrides java.io.OutputStream.write. Writes the specified portion of the designated octet sequence. Parameters b:byte[] the data. off:int the start offset in the data. len:int the number of bytes to write. Exceptions IOException: if an I/O error occurs. In particular, an `IOException` may be thrown if this output stream has been `closed`.

public synchronized void write(byte[] b, int off, int len) throws IOException

Overrides java.io.OutputStream.write.

Writes the specified portion of the designated octet sequence.

Parameters

b:byte[]: the data.
off:int: the start offset in the data.
len:int: the number of bytes to write.

Exceptions

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

writeTo back to summary

writeTo	back to summary
public synchronized void writeTo(OutputStream out) throws 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:OutputStream the output stream to which to write the data. Exceptions IOException: if an I/O error occurs. In particular, an `IOException` may be thrown if this output stream has been `freed`.

public synchronized void writeTo(OutputStream out) throws 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:OutputStream: the output stream to which to write the data.

Exceptions

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

public Class ClosableByteArrayOutputStream

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail