- All Implemented Interfaces:
Closeable
,Flushable
,AutoCloseable
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.
- Since:
- 1.9.0
- Author:
- Campbell Burnet (campbell-burnet@users dot sourceforge.net)
-
Constructor Summary
ConstructorsConstructorDescriptionCreates a new output stream.ClosableByteArrayOutputStream
(int size) Creates a new output stream with a buffer capacity of the specifiedsize
, in bytes. -
Method Summary
Modifier and TypeMethodDescriptionint
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 thecount
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 accumulated data.byte[]
Retrieves a copy of this stream's accumulated data, as a byte array.Performs an efficient (zero-copy) conversion of the data accumulated in this output stream to an input stream.toString()
Converts this stream's accumulated data into a string, translating bytes into characters according to the platform's default character encoding.Converts this stream's accumulated data into a string, translating bytes into characters according to the specified character encoding.void
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
(OutputStream out) Writes the complete contents of this stream's accumulated data to the specified output stream.Methods inherited from class java.io.OutputStream
nullOutputStream, write
-
Constructor Details
-
ClosableByteArrayOutputStream
public ClosableByteArrayOutputStream()Creates a new output stream.The buffer capacity is initially 32 bytes, though its size increases if necessary.
-
ClosableByteArrayOutputStream
Creates a new output stream with a buffer capacity of the specifiedsize
, in bytes.- Parameters:
size
- the initial size.- Throws:
IllegalArgumentException
- if size is negative.
-
-
Method Details
-
write
Writes the specified single byte.- Specified by:
write
in classOutputStream
- Parameters:
b
- the single byte to be written.- Throws:
IOException
- if an I/O error occurs. In particular, anIOException
may be thrown if this output stream has beenclosed
.
-
write
Writes the specified portion of the designated octet sequence.- Overrides:
write
in classOutputStream
- Parameters:
b
- the data.off
- the start offset in the data.len
- the number of bytes to write.- Throws:
IOException
- if an I/O error occurs. In particular, anIOException
may be thrown if this output stream has beenclosed
.
-
flush
By default, does nothing.- Specified by:
flush
in interfaceFlushable
- Overrides:
flush
in classOutputStream
- Throws:
IOException
- if an I/O error occurs. In particular, anIOException
may be thrown if this output stream has beenclosed
.
-
writeTo
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:
IOException
- if an I/O error occurs. In particular, anIOException
may be thrown if this output stream has beenfreed
.
-
capacity
Returns the current capacity of this stream's data buffer.- Returns:
- the length of the internal data array
- Throws:
IOException
- if an I/O error occurs. In particular, anIOException
may be thrown if this output stream has beenfreed
.
-
reset
Resets thecount
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:
IOException
- if an I/O error occurs. In particular, anIOException
may be thrown if this output stream has beenclosed
.- See Also:
-
trimToSize
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:
IOException
- if an I/O error occurs. In particular, anIOException
may be thrown if this output stream has beenfreed
.
-
toByteArray
Retrieves a copy of this stream's accumulated data, as a byte array.- Returns:
- a copy of this stream's accumulated data, as a byte array.
- Throws:
IOException
- if an I/O error occurs. In particular, anIOException
may be thrown if this output stream has beenfreed
.- See Also:
-
size
public int size()Returns the current size of this stream's accumulated data.- Returns:
- the value of the
count
field, which is the number of valid bytes in this output stream. - See Also:
-
setSize
public void setSize(int newSize) Sets the size of this stream's accumulated data.- Parameters:
newSize
- the new size- Throws:
ArrayIndexOutOfBoundsException
- if new size is negative
-
toByteArrayInputStream
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:
- an input stream representing this output stream's accumulated data
- Throws:
IOException
- if an I/O error occurs. In particular, anIOException
may be thrown if this output stream has beenfreed
.
-
toString
Converts this stream's accumulated data into a string, translating bytes into characters according to the platform's default character encoding.- Overrides:
toString
in classObject
- Returns:
- String translated from this stream's accumulated data.
- Throws:
RuntimeException
- may be thrown if this output stream has beenfreed
.
-
toString
Converts 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:
IOException
- may be thrown if this output stream has beenfreed
.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:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- Overrides:
close
in classOutputStream
-
isClosed
public boolean isClosed()Retrieves whether this stream is closed.- Returns:
true
if 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:
true
if this stream is freed; elsefalse
.
-