Module org.hsqldb

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
    Creates a new writer.
    Creates a new writer with a buffer capacity of the specified size, in characters.
  • Method Summary

    Modifier and Type
    Method
    Description
    int
    Returns the current capacity of this writer's data buffer.
    void
    Closes this object for further writing.
    void
    By default, does nothing.
    void
    Closes this object and releases the underlying buffer for garbage collection.
    boolean
     
    boolean
     
    void
    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
    Returns the current size of this writer's accumulated character data.
    char[]
    Creates a newly allocated character array.
    Performs an efficient (zero-copy) conversion of the character data accumulated in this writer to a reader.
    Converts this writer's accumulated data into a string.
    void
    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
    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 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.