- 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.OutputStreamProvides true Closable semantics ordinarily missing in aByteArrayOutputStream.Accumulates output in a byte array that automatically grows as needed.
Data is retrieved using
toByteArray(),toByteArrayInputStream(),toString()andtoString(encoding).ClosingaClosableByteArrayOutputStreamprevents further write operations, but all other operations may succeed until after the first invocation offree().Freeing a
ClosableByteArrayOutputStreamcloses the stream and releases the internal buffer, preventing successful invocation of all operations, with the exception ofsize(),close(),isClosed(),free()andisFreed().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.- Since:
- 1.9.0
- Author:
- Campbell Burnet (campbell-burnet@users dot sourceforge.net)
-
-
Constructor Summary
Constructors Constructor Description ClosableByteArrayOutputStream()Creates a new output stream.ClosableByteArrayOutputStream(int size)Creates a new output stream with a buffer capacity of the specifiedsize, in bytes.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description intcapacity()Returns the current capacity of this stream's data buffer.voidclose()Closes this object for further writing.voidflush()By default, does nothing.voidfree()Closes this object and releases the underlying buffer for garbage collection.booleanisClosed()Retrieves whether this stream is closed.booleanisFreed()Retrieves whether this stream is freed.voidreset()Resets thecountfield of this output stream to zero, so that all currently accumulated data is effectively discarded.voidsetSize(int newSize)Sets the size of this stream's accumulated data.intsize()Returns the current size of this stream's accumulated data.byte[]toByteArray()Retrieves a copy of this stream's accumulated data, as a byte array.java.io.ByteArrayInputStreamtoByteArrayInputStream()Performs an efficient (zero-copy) conversion of the data accumulated in this output stream to an input stream.java.lang.StringtoString()Converts this stream's accumulated data into a string, translating bytes into characters according to the platform's default character encoding.java.lang.StringtoString(java.lang.String enc)Converts this stream's accumulated data into a string, translating bytes into characters according to the specified character encoding.voidtrimToSize()Attempts to reduce this stream's capacity to its current size.voidwrite(byte[] b, int off, int len)Writes the specified portion of the designated octet sequence.voidwrite(int b)Writes the specified single byte.voidwriteTo(java.io.OutputStream out)Writes the complete contents of this stream's accumulated data to the specified output stream.
-
-
-
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.IllegalArgumentExceptionCreates a new output stream with a buffer capacity of the specifiedsize, 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.IOExceptionWrites the specified single byte.- Specified by:
writein classjava.io.OutputStream- Parameters:
b- the single byte to be written.- Throws:
java.io.IOException- if an I/O error occurs. In particular, anIOExceptionmay be thrown if this output stream has beenclosed.
-
write
public void write(byte[] b, int off, int len) throws java.io.IOExceptionWrites the specified portion of the designated octet sequence.- Overrides:
writein classjava.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, anIOExceptionmay be thrown if this output stream has beenclosed.
-
flush
public void flush() throws java.io.IOExceptionBy default, does nothing.- Specified by:
flushin interfacejava.io.Flushable- Overrides:
flushin classjava.io.OutputStream- Throws:
java.io.IOException- if an I/O error occurs. In particular, anIOExceptionmay be thrown if this output stream has beenclosed.
-
writeTo
public void writeTo(java.io.OutputStream out) throws java.io.IOExceptionWrites 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, anIOExceptionmay be thrown if this output stream has beenfreed.
-
capacity
public int capacity() throws java.io.IOExceptionReturns 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, anIOExceptionmay be thrown if this output stream has beenfreed.
-
reset
public void reset() throws java.io.IOExceptionResets thecountfield of this output stream to zero, so that all currently accumulated data is effectively discarded.Further write operations will reuse the allocated buffer space.
-
trimToSize
public void trimToSize() throws java.io.IOExceptionAttempts 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, anIOExceptionmay be thrown if this output stream has beenfreed.
-
toByteArray
public byte[] toByteArray() throws java.io.IOExceptionRetrieves a copy of this stream's accumulated data, as a byte array.
-
size
public int size()
Returns the current size of this stream's accumulated data.- Returns:
- the value of the
countfield, which is the number of valid bytes in this output stream. - 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.IOExceptionPerforms 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,
freeis 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, anIOExceptionmay be thrown if this output stream has beenfreed.
-
toString
public java.lang.String toString()
Converts this stream's accumulated data into a string, translating bytes into characters according to the platform's default character encoding.- Overrides:
toStringin classjava.lang.Object- Returns:
- String translated from this stream's accumulated data.
- Throws:
java.lang.RuntimeException- may be thrown if this output stream has beenfreed.
-
toString
public java.lang.String toString(java.lang.String enc) throws java.io.IOException, java.io.UnsupportedEncodingExceptionConverts this stream's accumulated 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 beenfreed.java.io.UnsupportedEncodingException- If the named encoding is not supported.
-
close
public void close()
Closes this object for further writing.Other operations may continue to succeed until after the first invocation of
free().- Specified by:
closein interfacejava.lang.AutoCloseable- Specified by:
closein interfacejava.io.Closeable- Overrides:
closein classjava.io.OutputStream
-
isClosed
public boolean isClosed()
Retrieves whether this stream is closed.- Returns:
trueif this stream is closed, elsefalse
-
free
public void free()
Closes this object and releases the underlying buffer for garbage collection.
-
isFreed
public boolean isFreed()
Retrieves whether this stream is freed.- Returns:
trueif this stream is freed; elsefalse.
-
-