Module org.hsqldb
Package org.hsqldb.lib

## Class ClosableCharArrayWriter

- java.lang.Object
- - java.io.Writer
  - - org.hsqldb.lib.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)

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ClosableCharArrayWriter()` | Creates a new writer.
    `ClosableCharArrayWriter​(int size)` | Creates a new writer with a buffer capacity of the specified `size`, in characters.

  - ### 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`

    - #### 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`.