Class ClosableByteArrayOutputStream

java.lang.Object
java.io.OutputStream
org.hsqldb.lib.ClosableByteArrayOutputStream
All Implemented Interfaces:
Closeable, Flushable, AutoCloseable
public class ClosableByteArrayOutputStream extends 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 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 specified size, in bytes.

  • Method Summary

    Modifier and Type
    Method
    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 accumulated data.
    byte[]
    toByteArray()
    Retrieves a copy of this stream's accumulated data, as a byte array.
    ByteArrayInputStream
    toByteArrayInputStream()
    Performs an efficient (zero-copy) conversion of the data accumulated in this output stream to an input stream.
    String
    toString()
    Converts this stream's accumulated data into a string, translating bytes into characters according to the platform's default character encoding.
    String
    toString(String enc)
    Converts this stream's accumulated 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(OutputStream out)
    Writes the complete contents of this stream's accumulated data to the specified output stream.

    Methods inherited from class OutputStream

    nullOutputStream, write

    Methods inherited from class Object

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

  • Constructor Details

    • 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 IllegalArgumentException
      Creates a new output stream with a buffer capacity of the specified size, in bytes.
      Parameters:
      size - the initial size.
      Throws:
      IllegalArgumentException - if size is negative.

  • Method Details

    • write

      public void write(int b) throws IOException
      Writes the specified single byte.
      Specified by:
      write in class OutputStream
      Parameters:
      b - the single byte to be written.
      Throws:
      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 IOException
      Writes the specified portion of the designated octet sequence.

      Overrides:
      write in class OutputStream
      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, an IOException may be thrown if this output stream has been closed.

    • flush

      public void flush() throws IOException
      By default, does nothing.

      Specified by:
      flush in interface Flushable
      Overrides:
      flush in class OutputStream
      Throws:
      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(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 - the output stream to which to write the data.
      Throws:
      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 IOException
      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, an IOException may be thrown if this output stream has been freed.

    • reset

      public 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.

      Throws:
      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 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:
      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 IOException
      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, an IOException may be thrown if this output stream has been freed.
      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:
      • count

    • 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

      public 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:
      an input stream representing this output stream's accumulated data
      Throws:
      IOException - if an I/O error occurs. In particular, an IOException may be thrown if this output stream has been freed.

    • toString

      public String 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 class Object
      Returns:
      String translated from this stream's accumulated data.
      Throws:
      RuntimeException - may be thrown if this output stream has been freed.

    • toString

      public 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 - a character-encoding name.
      Returns:
      String translated from the buffer's contents.
      Throws:
      IOException - may be thrown if this output stream has been freed.
      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 interface AutoCloseable
      Specified by:
      close in interface Closeable
      Overrides:
      close in class OutputStream

    • isClosed

      public boolean isClosed()
      Retrieves whether this stream is closed.

      Returns:
      true if this stream is closed, else false

    • 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; else false.