Module org.hsqldb
Package 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 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

    All Methods Instance Methods Concrete Methods
    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.
    `java.io.ByteArrayInputStream` | `toByteArrayInputStream()` | Performs an efficient (zero-copy) conversion of the data accumulated in this output stream to an input stream.
    `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.
    `java.lang.String` | `toString​(java.lang.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​(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

      `nullOutputStream, 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 accumulated data, as a byte array.
      Returns:
        a copy of this stream's accumulated 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()

      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:
        `java.lang.ArrayIndexOutOfBoundsException` - if new size is negative

    - #### toByteArrayInputStream

          public java.io.ByteArrayInputStream toByteArrayInputStream()
                                                              throws java.io.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:
        `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 accumulated 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 accumulated 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 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 been `freed`.
        `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:
        `close` in interface `java.lang.AutoCloseable`
      Specified by:
        `close` in interface `java.io.Closeable`
      Overrides:
        `close` in class `java.io.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`.