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

Constructor Summary

Constructors

Constructor and 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 and 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 effecient (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, 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()
         throws java.io.IOException

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.

Throws:

java.io.IOException - never

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 effecient (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()
           throws java.io.IOException

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.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in class java.io.Writer

Throws:

java.io.IOException - if an I/O error occurs (default: never)

isClosed

public boolean isClosed()

Returns:

true if this writer is closed, else false

free

public void free()
          throws java.io.IOException

Closes this object and releases the underlying buffer for garbage collection.

Throws:

java.io.IOException - if an I/O error occurs while closing this writer (default: never).

isFreed

public boolean isFreed()

Returns:

true if this writer is freed; else false.