Class ClosableCharArrayWriter

java.lang.Object
java.io.Writer
org.hsqldb.lib.ClosableCharArrayWriter
All Implemented Interfaces:
Closeable, Flushable, Appendable, AutoCloseable
public class ClosableCharArrayWriter extends 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

    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.
    CharArrayReader
    toCharArrayReader()
    Performs an efficient (zero-copy) conversion of the character data accumulated in this writer to a reader.
    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(String str, int off, int len)
    Efficiently writes the designated portion of the designated string.
    void
    writeTo(Writer out)
    Writes the complete contents of this writer's buffered data to the specified writer.

    Methods inherited from class Writer

    append, append, append, nullWriter, write, write

    Methods inherited from class Object

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

  • Constructor Details

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

  • Method Details

    • write

      public void write(int c) throws IOException
      Writes the specified single character.
      Overrides:
      write in class Writer
      Parameters:
      c - the single character to be written.
      Throws:
      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 IOException
      Writes the designated portion of the designated character array

      .

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

    • write

      public void write(String str, int off, int len) throws 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 Writer
      Parameters:
      str - the string from which to write
      off - the start offset in the string.
      len - the number of characters to write.
      Throws:
      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 IOException
      By default, does nothing.

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

    • writeTo

      public void writeTo(Writer out) throws 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:
      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 IOException
      Returns the current capacity of this writer's data buffer.
      Returns:
      the current capacity (the length of the internal data array)
      Throws:
      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 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:
      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 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:
      IOException - if buffer is freed

    • toCharArray

      public char[] toCharArray() throws 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:
      IOException - if an I/O error occurs. In particular, an IOException may be thrown if this writer has been freed.
      See Also:

    • 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:
      ArrayIndexOutOfBoundsException - if new size is negative

    • toCharArrayReader

      public CharArrayReader toCharArrayReader() throws 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:
      IOException - if an I/O error occurs. In particular, an IOException may be thrown if this writer has been freed.

    • toString

      public String toString()
      Converts this writer's accumulated data into a string.
      Overrides:
      toString in class Object
      Returns:
      String constructed from this writer's accumulated data
      Throws:
      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 AutoCloseable
      Specified by:
      close in interface Closeable
      Specified by:
      close in class 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.