org.codehaus.groovy.grails.web.util
Class StreamCharBuffer

java.lang.Object
  extended by org.codehaus.groovy.grails.web.util.StreamCharBuffer

public class StreamCharBuffer
extends Object

StreamCharBuffer is a multipurpose in-memory buffer.

There's a java.io.Writer interface for appending character data to the buffer and a java.io.Reader interface for reading data.

There's also several other options for reading data: readAsCharArray() reads the buffer to a char[] array
readAsString() reads the buffer and wraps the char[] data as a String
writeTo(Writer) writes the buffer to a java.io.Writer
toCharArray() returns the buffer as a char[] array, caches the return value internally so that this method can be called several times.
toString() returns the buffer as a String, caches the return value internally
By using the "connectTo" method, one can connect the buffer directly to a target java.io.Writer. The internal buffer gets flushed automaticly to the target whenever the buffer gets filled up.

Author:
Lari Hotari, Sagire Software Oy
See Also:

This class is not thread-safe. Object instances of this class are intended to be used by a single Thread. The Reader and Writer interfaces can be open simultaneous and the same Thread can write and read several times.

Main operation principle:
StreamCharBuffer keeps the buffer in a LinkedList of "chunks" ({@link StreamCharBufferChunk}). The main difference compared to JDK in-memory buffers is that the buffer can be held in several smaller buffers ("chunks" here). Normally the buffer has to be expanded whenever it gets filled up. The old buffer's data is copied to the new one and the old one is discarded. In StreamCharBuffer, there are several ways to prevent unnecessary allocation & copy operations. Each chunk may contain several sub-chunks ({@link StringChunk} that are java.lang.String instances. A StringChunk is appended to the current chunk (that's under writing) whenever a java.lang.String of a length that exceeds the "stringChunkMinSize" value is written to the buffer. There's actually several layers in storing the data in the buffer: - linked list of StreamCharBufferChunk instances - for each chunk - char[] buffer - linked list of StringChunkGroup instances - for each StringChunkGroup - linked list of StringChunk instances - java.lang.String is kept in StringChunk If the buffer is in "connectTo" mode, any String or char[] that's length is over writeDirectlyToConnectedMinSize gets written directly to the target. The buffer content will get fully flushed to the target before writing the String or char[]. There can be several targets "listening" the buffer in "connectTo" mode. The same content will be written to all targets. Growable chunksize: By default, a newly allocated chunk's size will grow based on the total size of all written chunks. The default growProcent value is 100. If the total size is currently 1024, the newly created chunk will have a internal buffer that's size is 1024. Growable chunksize can be turned off by setting the growProcent to 0. There's a default maximum chunksize of 1MB by default. The minimum size is the initial chunksize size.


Nested Class Summary
(package private) static class StreamCharBuffer.ConnectedWriter
          Simple holder class for the connected writer
static interface StreamCharBuffer.LazyInitializingWriter
          Interface for a Writer that gets initialized if it is used Can be used for passing in to "connectTo" method of StreamCharBuffer
(package private) static class StreamCharBuffer.MultiOutputWriter
          delegates to several writers, used in "connectTo" mode.
(package private) static class StreamCharBuffer.StreamCharBufferChunk
          The data in the buffer is stored in a linked list of StreamCharBufferChunks.
 class StreamCharBuffer.StreamCharBufferReader
          This is the java.io.Reader implementation for StreamCharBuffer
 class StreamCharBuffer.StreamCharBufferWriter
          This is the java.io.Writer implementation for StreamCharBuffer
(package private) static class StreamCharBuffer.StringChunk
          StringChunk is a wrapper for java.lang.String.
(package private) static class StreamCharBuffer.StringChunkGroup
          StringChunkGroup is related to a certain position in the StreamCharBufferChunk.
 
Constructor Summary
StreamCharBuffer()
           
StreamCharBuffer(int chunkSize)
           
StreamCharBuffer(int chunkSize, int growProcent)
           
StreamCharBuffer(int chunkSize, int growProcent, int maxChunkSize)
           
 
Method Summary
protected  int allocateSpace()
           
protected static void arrayCopy(char[] src, int srcPos, char[] dest, int destPos, int length)
           
 int calculateTotalCharsUnread()
           
 int charsAvailable()
           
 void connectTo(StreamCharBuffer.LazyInitializingWriter writer)
           
 void connectTo(StreamCharBuffer.LazyInitializingWriter writer, boolean autoFlush)
           
 void connectTo(Writer writer)
          Connect this buffer to a target Writer.
 void connectTo(Writer writer, boolean autoFlush)
           
 int filledChunkCount()
           
 Reader getReader()
          Reader interface for reading/consuming data from the buffer
 int getStringChunkMinSize()
           
 int getWriteDirectlyToConnectedMinSize()
           
 Writer getWriter()
          Writer interface for adding/writing data to the buffer.
protected  boolean isChunkSizeResizeable()
           
protected  int prepareRead()
           
protected  int prepareRead(boolean readLast)
           
 char[] readAsCharArray()
          reads (and empties) the buffer to a char[]
 String readAsString()
          reads (and empties) the buffer to a String
 void removeConnections()
           
 void reset()
           
 void reset(boolean resetChunkSize)
          resets the state of this buffer (empties it)
protected  void resizeChunkSizeAsProcentageOfTotalSize()
           
 void setStringChunkMinSize(int stringChunkMinSize)
          Minimum size for a String to be added as a StringChunk instead of copying content to the char[] buffer of the current StreamCharBufferChunk
 void setWriteDirectlyToConnectedMinSize(int writeDirectlyToConnectedMinSize)
          Minimum size for a String or char[] to get written directly to connected writer (in "connectTo" mode).
 int size()
           
 char[] toCharArray()
          reads (and empties) the buffer to a char[], but caches the return value for subsequent calls.
 String toString()
          reads (and empties) the buffer to a String, but caches the return value for subsequent calls.
 void writeTo(Writer target)
          Writes the buffer content to a target java.io.Writer
 void writeTo(Writer target, boolean flushAll, boolean flushTarget)
          Writes the buffer content to a target java.io.Writer
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

StreamCharBuffer

public StreamCharBuffer()

StreamCharBuffer

public StreamCharBuffer(int chunkSize)

StreamCharBuffer

public StreamCharBuffer(int chunkSize,
                        int growProcent)

StreamCharBuffer

public StreamCharBuffer(int chunkSize,
                        int growProcent,
                        int maxChunkSize)
Method Detail

reset

public void reset()

connectTo

public void connectTo(Writer writer)
Connect this buffer to a target Writer. When the buffer (a chunk) get filled up, it will automaticly write it's content to the Writer

Parameters:
writer -

connectTo

public void connectTo(Writer writer,
                      boolean autoFlush)

connectTo

public void connectTo(StreamCharBuffer.LazyInitializingWriter writer)

connectTo

public void connectTo(StreamCharBuffer.LazyInitializingWriter writer,
                      boolean autoFlush)

removeConnections

public void removeConnections()

filledChunkCount

public int filledChunkCount()

getStringChunkMinSize

public int getStringChunkMinSize()

setStringChunkMinSize

public void setStringChunkMinSize(int stringChunkMinSize)
Minimum size for a String to be added as a StringChunk instead of copying content to the char[] buffer of the current StreamCharBufferChunk

Parameters:
stringChunkMinSize -

getWriteDirectlyToConnectedMinSize

public int getWriteDirectlyToConnectedMinSize()

setWriteDirectlyToConnectedMinSize

public void setWriteDirectlyToConnectedMinSize(int writeDirectlyToConnectedMinSize)
Minimum size for a String or char[] to get written directly to connected writer (in "connectTo" mode).

Parameters:
writeDirectlyToConnectedMinSize -

reset

public void reset(boolean resetChunkSize)
resets the state of this buffer (empties it)

Parameters:
resetChunkSize -

getWriter

public Writer getWriter()
Writer interface for adding/writing data to the buffer.

Returns:

getReader

public Reader getReader()
Reader interface for reading/consuming data from the buffer

Returns:

writeTo

public void writeTo(Writer target)
             throws IOException
Writes the buffer content to a target java.io.Writer

Parameters:
target -
Throws:
IOException

writeTo

public void writeTo(Writer target,
                    boolean flushAll,
                    boolean flushTarget)
             throws IOException
Writes the buffer content to a target java.io.Writer

Parameters:
target - Writer
flushAll - flush all content in buffer (if this is false, only filled chunks will be written)
flushTarget - call target.flush() before finishing
Throws:
IOException

readAsCharArray

public char[] readAsCharArray()
reads (and empties) the buffer to a char[]

Returns:

readAsString

public String readAsString()
reads (and empties) the buffer to a String

Returns:

toString

public String toString()
reads (and empties) the buffer to a String, but caches the return value for subsequent calls. if more content has been added between 2 calls, the returned value will be joined from the previously cached value and the data read from the buffer.

Overrides:
toString in class Object
See Also:
Object.toString()

toCharArray

public char[] toCharArray()
reads (and empties) the buffer to a char[], but caches the return value for subsequent calls. if more content has been added between 2 calls, the returned value will be joined from the previously cached value and the data read from the buffer.

Returns:

size

public int size()

charsAvailable

public int charsAvailable()

calculateTotalCharsUnread

public int calculateTotalCharsUnread()

allocateSpace

protected int allocateSpace()
                     throws IOException
Throws:
IOException

isChunkSizeResizeable

protected boolean isChunkSizeResizeable()

resizeChunkSizeAsProcentageOfTotalSize

protected void resizeChunkSizeAsProcentageOfTotalSize()

prepareRead

protected int prepareRead()

prepareRead

protected int prepareRead(boolean readLast)

arrayCopy

protected static final void arrayCopy(char[] src,
                                      int srcPos,
                                      char[] dest,
                                      int destPos,
                                      int length)


Copyright (c) 2005-2009 The Grails project