com.claritysys.io
Class CharArrayWriter

java.lang.Object
  extended by java.io.Writer
      extended by com.claritysys.io.CharArrayWriter
All Implemented Interfaces:
java.io.Closeable, java.io.Flushable, java.lang.Appendable

public final class CharArrayWriter
extends java.io.Writer

A high performance, single-threaded writer that appends all writes to an output buffer, much like ByteArrayOutputStream. The buffer grows as needed.

Create one of these with a large buffer and reuse it from request to request.

It is not multi-thread safe!

You must ensure that only one servlet request is accessing it at a time, by allocating CharArrayWriters from a pool or some other technique.

There are several performance characteristics of this writer:

One of the challenges in using this will be to write the char[] to a byte stream. It has been found that OutputStreamWriter has disgusting performance characteristics.

The reason this class is a CharArray writer and not a ByteArray writer is because most of the output is String objects. The String class provides a method for copying the String's internal char[] directly to another char[] using System.arraycopy, without producing any objects during the copy. If it were a byte[], we would have to loop through the String's buffer (after getting a copy of it) and convert each char to a byte using the proper encoding (ASCII, UTF-8, etc). The String class has a getBytes method, but that produces a new byte[]. Object creation is the bane of performance.

Version:
$Revision: 2348 $ $Date: 2004-12-01 16:12:21 -0800 (Wed, 01 Dec 2004) $

Field Summary
 
Fields inherited from class java.io.Writer
lock
 
Constructor Summary
CharArrayWriter(int size)
          Create a new writer with a buffer size given.
 
Method Summary
 void close()
          Does nothing.
 void flush()
          Does nothing.
 char[] getBuffer()
          Get the current char[].
 int getBufferSize()
          Get the capacity of the buffer, that is the length of the char[].
 int getCount()
          Return the current number of characters in the buffer.
 void print(char c)
          Print a single char.
 void print(int i)
          Print an int directly to the buffer, without doing a Integer.toString first to avoid creating unnecessary objects.
 void print(java.lang.String str)
          "Print" a String.
 void reset()
          Reset the current number of characters in the buffer to zero.
 void toArray(byte[] bytes)
          Write the char[] into a byte[], while assuming all characters are actually ASCII (UTF-8), which HTML is, isn't it?
 java.lang.String toString()
          Create a new String object and copy the current buffer into the Strings char buffer.
 void write(char[] cbuf, int off, int len)
          Write a portion of an array of characters.
 void write(java.lang.String str)
          Write a string.
 void write(java.lang.String str, int off, int len)
          Write a portion of a string.
 
Methods inherited from class java.io.Writer
append, append, append, write, write
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

CharArrayWriter

public CharArrayWriter(int size)
Create a new writer with a buffer size given.

Parameters:
size - The size of the char[] in characters.
Method Detail

getCount

public int getCount()
Return the current number of characters in the buffer.

Returns:
The current number of characters in the buffer.
See Also:
getBufferSize()

reset

public void reset()
Reset the current number of characters in the buffer to zero.

This acts like "flushing" the buffer, but it just discards the current contents. It literally just sets the current count to zero.


getBuffer

public char[] getBuffer()
Get the current char[].

DO NOT MODIFY THE CHAR[].

This is the actualy char[] (for performance) in use by the writer,

You must call getCount() to know how many characters this buffer actually contains.

Returns:
The char[].

getBufferSize

public int getBufferSize()
Get the capacity of the buffer, that is the length of the char[].

Returns:
The buffer length, in characters.
See Also:
getCount()

toString

public java.lang.String toString()
Create a new String object and copy the current buffer into the Strings char buffer.

Thus this method creates 2 objects, the new String and its internal char[]. It then copies the characters into the String's char[] using System.arraycopy.

Generally not good for performance.

Overrides:
toString in class java.lang.Object
Returns:
The current char[] as a new String, by invoking String constructor String(char[], int off, int len).

write

public void write(java.lang.String str)
Write a string.

Overrides:
write in class java.io.Writer
Parameters:
str - String to be written

write

public void write(char[] cbuf,
                  int off,
                  int len)
Write a portion of an array of characters.

Specified by:
write in class java.io.Writer
Parameters:
cbuf - Array of characters
off - Offset from which to start writing characters
len - Number of characters to write

write

public void write(java.lang.String str,
                  int off,
                  int len)
Write a portion of a string.

Overrides:
write in class java.io.Writer
Parameters:
str - A String
off - Offset from which to start writing characters
len - Number of characters to write

flush

public void flush()
Does nothing.

Specified by:
flush in interface java.io.Flushable
Specified by:
flush in class java.io.Writer

close

public void close()
Does nothing.

Specified by:
close in interface java.io.Closeable
Specified by:
close in class java.io.Writer

print

public void print(java.lang.String str)
"Print" a String. This just calls write(String). It makes this writer look like a PrintWriter.

Parameters:
str - The string to print.

print

public void print(char c)
Print a single char.

Parameters:
c -

print

public void print(int i)
Print an int directly to the buffer, without doing a Integer.toString first to avoid creating unnecessary objects.

Parameters:
i - The int to print to the buffer.

toArray

public void toArray(byte[] bytes)
Write the char[] into a byte[], while assuming all characters are actually ASCII (UTF-8), which HTML is, isn't it?

Parameters:
bytes -


Copyright ? 2002 Clarity Systems Group, LLC. All Rights Reserved.