Module org.hsqldb
Package org.hsqldb.lib

Class 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)

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