Top Description Fields Constructors Methods
org.hsqldb.lib

public Class ClosableCharArrayWriter

extends Writer
Class Inheritance
Imports
java.io.CharArrayReader, .IOException, .Writer
Provides Closable semantics ordinarily missing in a java.io.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.

Author
Campbell Burnet (campbell-burnet@users dot sourceforge.net)
Since
1.8.x
Version
1.8.x

Field Summary

Modifier and TypeField and Description
protected char[]
buf

Data buffer.

protected boolean
closed

Whether this writer is closed.

protected int
count

# of valid characters in buffer.

protected boolean
freed

Whether this writer is freed.

Inherited from java.io.Writer:
lock

Constructor Summary

AccessConstructor and Description
public
ClosableCharArrayWriter()

Creates a new writer.

public
ClosableCharArrayWriter(int
the initial size.
size)

Creates a new writer with a buffer capacity of the specified size, in characters.

Method Summary

Modifier and TypeMethod and Description
public synchronized int

Returns:

the current capacity (the length of the internal data array)
capacity()

Returns the current capacity of this writer's data buffer.

protected synchronized void
checkClosed()

protected synchronized void
checkFreed()

public synchronized void
close()

Implements abstract java.io.Writer.close.

Implements java.io.Closeable.close.

Closes this object for further writing.

protected char[]

Returns:

copy of original with the given newLength
copyOf(char[]
the object to copy
original, int
the length of the copy
newLength)

Retrieves a copy of original with the given newLength.

public void
flush()

Implements abstract java.io.Writer.flush.

Implements java.io.Flushable.flush.

By default, does nothing.

public synchronized void
free()

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

public synchronized boolean
isClosed()

Returns: true if this writer is closed, else false

public synchronized boolean
isFreed()

Returns: true if this writer is freed; else false.

public synchronized void
reset()

Resets the count field of this writer to zero, so that all currently accumulated output is effectively discarded.

public synchronized void
setSize(int
the new size of this writer's accumulated data
newSize)

Sets the size of this writer's accumulated character data.

public synchronized int

Returns:

the value of the count field, which is the number of valid characters accumulated in this writer.
size()

Returns the current size of this writer's accumulated character data.

public synchronized char[]

Returns:

the current contents of this writer, as a character array.
toCharArray()

Creates a newly allocated character array.

public synchronized CharArrayReader

Returns:

a reader representing this writer's accumulated character data
toCharArrayReader()

Performs an efficient (zero-copy) conversion of the character data accumulated in this writer to a reader.

public synchronized String

Returns:

String constructed from this writer's accumulated data
toString()

Overrides java.lang.Object.toString.

Converts this writer's accumulated data into a string.

public synchronized void
trimToSize()

Attempts to reduce this writer's buffer capacity to its current size.

public synchronized void
write(int
the single character to be written.
c)

Overrides java.io.Writer.write.

Writes the specified single character.

public synchronized void
write(char[]
the source character sequence.
c, int
the start offset in the source character sequence.
off, int
the number of characters to write.
len)

Implements abstract java.io.Writer.write.

Writes the designated portion of the designated character array

.

public synchronized void
write(String
the string from which to write
str, int
the start offset in the string.
off, int
the number of characters to write.
len)

Overrides java.io.Writer.write.

Efficiently writes the designated portion of the designated string.

public synchronized void
writeTo(Writer
the writer to which to write the data.
out)

Writes the complete contents of this writer's buffered data to the specified writer.

Inherited from java.io.Writer:
appendappendappendnullWriterwritewrite

Field Detail

bufback to summary
protected char[] buf

Data buffer.

closedback to summary
protected boolean closed

Whether this writer is closed.

countback to summary
protected int count

# of valid characters in buffer.

freedback to summary
protected boolean freed

Whether this writer is freed.

Constructor Detail

ClosableCharArrayWriterback to summary
public ClosableCharArrayWriter()

Creates a new writer.

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

ClosableCharArrayWriterback to summary
public ClosableCharArrayWriter(int size) throws IllegalArgumentException

Creates a new writer with a buffer capacity of the specified size, in characters.

Parameters
size:int

the initial size.

Exceptions
IllegalArgumentException:
if size is negative.

Method Detail

capacityback to summary
public synchronized int capacity() throws IOException

Returns the current capacity of this writer's data buffer.

Returns:int

the current capacity (the length of the internal data array)

Exceptions
IOException:
if an I/O error occurs. In particular, an IOException may be thrown if this writer has been freed.
checkClosedback to summary
protected synchronized void checkClosed() throws IOException
Exceptions
IOException:
if this writer is closed.
checkFreedback to summary
protected synchronized void checkFreed() throws IOException
Exceptions
IOException:
if this writer is freed.
closeback to summary
public synchronized void close()

Implements abstract java.io.Writer.close.

Implements java.io.Closeable.close.

Closes this object for further writing.

Other operations may continue to succeed until after the first invocation of free().

copyOfback to summary
protected char[] copyOf(char[] original, int newLength)

Retrieves a copy of original with the given newLength.

Parameters
original:char[]

the object to copy

newLength:int

the length of the copy

Returns:char[]

copy of original with the given newLength

flushback to summary
public void flush() throws IOException

Implements abstract java.io.Writer.flush.

Implements java.io.Flushable.flush.

By default, does nothing.

Exceptions
IOException:
if an I/O error occurs. In particular, an IOException may be thrown if this writer has been closed.
freeback to summary
public synchronized void free()

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

isClosedback to summary
public synchronized boolean isClosed()
Returns:boolean

true if this writer is closed, else false

isFreedback to summary
public synchronized boolean isFreed()
Returns:boolean

true if this writer is freed; else false.

resetback to summary
public synchronized 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.

Exceptions
IOException:
if an I/O error occurs. In particular, an IOException may be thrown if this output stream has been closed.
See Also
count
setSizeback to summary
public synchronized void setSize(int newSize)

Sets the size of this writer's accumulated character data.

Parameters
newSize:int

the new size of this writer's accumulated data

Exceptions
ArrayIndexOutOfBoundsException:
if new size is negative
sizeback to summary
public synchronized int size()

Returns the current size of this writer's accumulated character data.

Returns:int

the value of the count field, which is the number of valid characters accumulated in this writer.

See Also
count
toCharArrayback to summary
public synchronized 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:char[]

the current contents of this writer, as a character array.

Exceptions
IOException:
if an I/O error occurs. In particular, an IOException may be thrown if this writer has been freed.
See Also
size()
toCharArrayReaderback to summary
public synchronized 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:CharArrayReader

a reader representing this writer's accumulated character data

Exceptions
IOException:
if an I/O error occurs. In particular, an IOException may be thrown if this writer has been freed.
toStringback to summary
public synchronized String toString()

Overrides java.lang.Object.toString.

Converts this writer's accumulated data into a string.

Returns:String

String constructed from this writer's accumulated data

Exceptions
RuntimeException:
may be thrown if this writer has been freed.
trimToSizeback to summary
public synchronized 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.

Exceptions
IOException:
if buffer is freed
writeback to summary
public synchronized void write(int c) throws IOException

Overrides java.io.Writer.write.

Writes the specified single character.

Parameters
c:int

the single character to be written.

Exceptions
IOException:
if an I/O error occurs. In particular, an IOException may be thrown if this writer has been closed.
writeback to summary
public synchronized void write(char[] c, int off, int len) throws IOException

Implements abstract java.io.Writer.write.

Writes the designated portion of the designated character array

.

Parameters
c:char[]

the source character sequence.

off:int

the start offset in the source character sequence.

len:int

the number of characters to write.

Exceptions
IOException:
if an I/O error occurs. In particular, an IOException may be thrown if this writer has been closed.
writeback to summary
public synchronized void write(String str, int off, int len) throws IOException

Overrides java.io.Writer.write.

Efficiently writes the designated portion of the designated string.

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

Parameters
str:String

the string from which to write

off:int

the start offset in the string.

len:int

the number of characters to write.

Exceptions
IOException:
if an I/O error occurs. In particular, an IOException may be thrown if this writer has been closed.
writeToback to summary
public synchronized 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:Writer

the writer to which to write the data.

Exceptions
IOException:
if an I/O error occurs. In particular, an IOException may be thrown if this writer has been freed.