Module org.hsqldb
Package org.hsqldb.lib

Class ClosableCharArrayWriter

  • All Implemented Interfaces:
    java.io.Closeable, java.io.Flushable, java.lang.Appendable, java.lang.AutoCloseable
    public class ClosableCharArrayWriter
extends java.io.Writer
    Provides Closable semantics ordinarily missing in a CharArrayWriter.

    Accumulates output in a character array that automatically grows as needed.

    Data is retrieved using toCharArray(), toCharArrayReader() and toString().

    Closing a ClosableCharArrayWriter prevents further write operations, but all other operations will succeed until after the first invocation of free().

    Freeing a ClosableCharArrayWriter closes the writer and releases its 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 writer must be handed off to an extenal client under contract that the writer should exhibit true Closable behaviour, both in response to internally tracked events and to client invocation of the Writer.close() method.

    Since:
    1.8.x
    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 writer'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()  
      boolean isFreed()  
      void reset()
      Resets the count field of this writer to zero, so that all currently accumulated output is effectively discarded.
      void setSize​(int newSize)
      Sets the size of this writer's accumulated character data.
      int size()
      Returns the current size of this writer's accumulated character data.
      char[] toCharArray()
      Creates a newly allocated character array.
      java.io.CharArrayReader toCharArrayReader()
      Performs an efficient (zero-copy) conversion of the character data accumulated in this writer to a reader.
      java.lang.String toString()
      Converts this writer's accumulated data into a string.
      void trimToSize()
      Attempts to reduce this writer's buffer capacity to its current size.
      void write​(char[] c, int off, int len)
      Writes the designated portion of the designated character array
      void write​(int c)
      Writes the specified single character.
      void write​(java.lang.String str, int off, int len)
      Efficiently writes the designated portion of the designated string.
      void writeTo​(java.io.Writer out)
      Writes the complete contents of this writer's buffered data to the specified writer.

      • Methods inherited from class java.io.Writer

        append, append, append, nullWriter, write, write

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • ClosableCharArrayWriter

        public ClosableCharArrayWriter()
        Creates a new writer.

        The buffer capacity is initially 32 characters, although its size automatically increases when necessary.

      • ClosableCharArrayWriter

        public ClosableCharArrayWriter​(int size)
                        throws java.lang.IllegalArgumentException
        Creates a new writer with a buffer capacity of the specified size, in characters.
        Parameters:
        size - the initial size.
        Throws:
        java.lang.IllegalArgumentException - if size is negative.

    • Method Detail

      • write

        public void write​(int c)
           throws java.io.IOException
        Writes the specified single character.
        Overrides:
        write in class java.io.Writer
        Parameters:
        c - the single character to be written.
        Throws:
        java.io.IOException - if an I/O error occurs. In particular, an IOException may be thrown if this writer has been closed.

      • write

        public void write​(char[] c,
                  int off,
                  int len)
           throws java.io.IOException
        Writes the designated portion of the designated character array

        .

        Specified by:
        write in class java.io.Writer
        Parameters:
        c - the source character sequence.
        off - the start offset in the source character sequence.
        len - the number of characters to write.
        Throws:
        java.io.IOException - if an I/O error occurs. In particular, an IOException may be thrown if this writer has been closed.

      • write

        public void write​(java.lang.String str,
                  int off,
                  int len)
           throws java.io.IOException
        Efficiently writes the designated portion of the designated string.

        The operation occurs as if by calling str.getChars(off, off + len, buf, count).

        Overrides:
        write in class java.io.Writer
        Parameters:
        str - the string from which to write
        off - the start offset in the string.
        len - the number of characters to write.
        Throws:
        java.io.IOException - if an I/O error occurs. In particular, an IOException may be thrown if this writer has been closed.

      • flush

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

        Specified by:
        flush in interface java.io.Flushable
        Specified by:
        flush in class java.io.Writer
        Throws:
        java.io.IOException - if an I/O error occurs. In particular, an IOException may be thrown if this writer has been closed.

      • writeTo

        public void writeTo​(java.io.Writer out)
             throws java.io.IOException
        Writes the complete contents of this writer's buffered data to the specified writer.

        The operation occurs as if by calling out.write(buf, 0, count).

        Parameters:
        out - the writer 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 writer has been freed.

      • capacity

        public int capacity()
             throws java.io.IOException
        Returns the current capacity of this writer's data buffer.
        Returns:
        the current capacity (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 writer has been freed.

      • reset

        public void reset()
           throws java.io.IOException
        Resets the count field of this writer to zero, so that all currently accumulated output 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 writer's buffer capacity to its current size.

        If the buffer is larger than necessary to hold its current sequence of characters, 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 buffer is freed

      • toCharArray

        public char[] toCharArray()
                   throws java.io.IOException
        Creates a newly allocated character array. Its size is the current size of this writer and the valid contents of the buffer have been copied into it.
        Returns:
        the current contents of this writer, as a character array.
        Throws:
        java.io.IOException - if an I/O error occurs. In particular, an IOException may be thrown if this writer has been freed.
        See Also:
        size()

      • size

        public int size()
        Returns the current size of this writer's accumulated character data.
        Returns:
        the value of the count field, which is the number of valid characters accumulated in this writer.
        See Also:
        count

      • setSize

        public void setSize​(int newSize)
        Sets the size of this writer's accumulated character data.

        Parameters:
        newSize - the new size of this writer's accumulated data
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - if new size is negative

      • toCharArrayReader

        public java.io.CharArrayReader toCharArrayReader()
                                          throws java.io.IOException
        Performs an efficient (zero-copy) conversion of the character data accumulated in this writer to a reader.

        To ensure the integrity of the resulting reader, free is invoked upon this writer as a side-effect.

        Returns:
        a reader representing this writer's accumulated character data
        Throws:
        java.io.IOException - if an I/O error occurs. In particular, an IOException may be thrown if this writer has been freed.

      • toString

        public java.lang.String toString()
        Converts this writer's accumulated data into a string.
        Overrides:
        toString in class java.lang.Object
        Returns:
        String constructed from this writer's accumulated data
        Throws:
        java.lang.RuntimeException - may be thrown if this writer has been freed.

      • 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
        Specified by:
        close in class java.io.Writer

      • isClosed

        public boolean isClosed()
        Returns:
        true if this writer is closed, else false

      • free

        public void free()
        Closes this object and releases the underlying buffer for garbage collection.

      • isFreed

        public boolean isFreed()
        Returns:
        true if this writer is freed; else false.