org.codehaus.groovy.grails.web.util
[Java] Class StreamCharBuffer

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

All Implemented Interfaces:

groovy.lang.Writable, java.lang.CharSequence, java.io.Externalizable

public class StreamCharBuffer

StreamCharBuffer is a multipurpose in-memory buffer that can replace JDK in-memory buffers (StringBuffer, StringBuilder, StringWriter).

Grails GSP rendering uses this class as a buffer that is optimized for performance.

StreamCharBuffer keeps the buffer in a linked list of "chunks". The main difference compared to JDK in-memory buffers (StringBuffer, StringBuilder & StringWriter) is that the buffer can be held in several smaller buffers ("chunks" here). In JDK in-memory buffers, 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. The StreamCharBuffer contains a linked list of different type of chunks: char arrays, java.lang.String chunks and other StreamCharBuffers as sub chunks. A StringChunk is appended to the linked list whenever a java.lang.String of a length that exceeds the "stringChunkMinSize" value is written to the buffer.

Grails tag libraries also use a StreamCharBuffer to "capture" the output of the taglib and return it to the caller. The buffer can be appended to it's parent buffer directly without extra object generation (like converting to java.lang.String in between). for example this line of code in a taglib would just append the buffer returned from the body closure evaluation to the buffer of the taglib:
out << body()
other example:
out << g.render(template: '/some/template', model:[somebean: somebean])
There's no extra java.lang.String generation overhead.

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

Each getReader() call will create a new reader instance that keeps it own state.
There is a alternative method getReader(boolean) for creating the reader. When reader is created by calling getReader(true), the reader will remove already read characters from the buffer. In this mode only a single reader instance is supported.

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. {

Authors:

Lari Hotari, Sagire Software Oy

See Also:

connectTo(Writer)

StreamCharBuffer

public StreamCharBuffer()

StreamCharBuffer

public StreamCharBuffer(int chunkSize)

StreamCharBuffer

public StreamCharBuffer(int chunkSize, int growProcent)

StreamCharBuffer

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

allocateSpace

protected int allocateSpace()

appendStreamCharBufferChunk

public void appendStreamCharBufferChunk(StreamCharBuffer subBuffer)

arrayCopy

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

charAt

public char charAt(int index)

connectTo

public final void connectTo(java.io.Writer w)

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:

w

connectTo

public final void connectTo(java.io.Writer w, boolean autoFlush)

connectTo

public final void connectTo(StreamCharBuffer.LazyInitializingWriter w)

connectTo

public final void connectTo(StreamCharBuffer.LazyInitializingWriter w, boolean autoFlush)

encodeAsHTML

public StreamCharBuffer encodeAsHTML()

equals

@Override
public boolean equals(java.lang.Object o)

equals uses String.equals to check for equality to support compatibility with String instances in maps, sets, etc.

See Also:

java.lang.Object#equals(java.lang.Object)

getChunkMinSize

public int getChunkMinSize()

getReader

public java.io.Reader getReader()

Creates a new Reader instance for reading/consuming data from the buffer. Each call creates a new instance that will keep it's reading state. There can be several readers on the buffer. (single thread only supported)

Returns:

the Reader

getReader

public java.io.Reader getReader(boolean removeAfterReading)

Like getReader(), but when removeAfterReading is true, the read data will be removed from the buffer.

Parameters:

removeAfterReading

Returns:

the Reader

getSubBufferChunkMinSize

public int getSubBufferChunkMinSize()

getSubStringChunkMinSize

public int getSubStringChunkMinSize()

getWriteDirectlyToConnectedMinSize

public int getWriteDirectlyToConnectedMinSize()

getWriter

public java.io.Writer getWriter()

Writer interface for adding/writing data to the buffer.

Returns:

the Writer

hashCode

@Override
public int hashCode()

hashCode() uses String's hashCode to support compatibility with String instances in maps, sets, etc.

See Also:

java.lang.Object#hashCode()

isChunkSizeResizeable

protected boolean isChunkSizeResizeable()

isConnectedMode

public boolean isConnectedMode()

isPreferSubChunkWhenWritingToOtherBuffer

public boolean isPreferSubChunkWhenWritingToOtherBuffer()

length

public int length()

plus

public java.lang.String plus(java.lang.String value)

plus

public java.lang.String plus(java.lang.Object value)

readAsCharArray

public char[] readAsCharArray()

Reads the buffer to a char[].

Returns:

the chars

readAsString

public java.lang.String readAsString()

Reads the buffer to a String.

Returns:

the String

readExternal

public void readExternal(java.io.ObjectInput in)

See Also:

java.io.Externalizable#readExternal(java.io.ObjectInput)

removeConnections

public final void removeConnections()

reset

public void reset()

reset

public void reset(boolean resetChunkSize)

resets the state of this buffer (empties it)

Parameters:

resetChunkSize

resizeChunkSizeAsProcentageOfTotalSize

protected void resizeChunkSizeAsProcentageOfTotalSize()

setChunkMinSize

public void setChunkMinSize(int chunkMinSize)

setPreferSubChunkWhenWritingToOtherBuffer

public void setPreferSubChunkWhenWritingToOtherBuffer(boolean preferSubChunkWhenWritingToOtherBuffer)

setSubBufferChunkMinSize

public void setSubBufferChunkMinSize(int subBufferChunkMinSize)

setSubStringChunkMinSize

public void setSubStringChunkMinSize(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

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

size

public int size()

subSequence

public java.lang.CharSequence subSequence(int start, int end)

toCharArray

public char[] toCharArray()

Reads the buffer to a char[]. Caches the result if there aren't any readers.

Returns:

the chars

toString

@Override
public java.lang.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.

See Also:

java.lang.Object#toString()

writeExternal

public void writeExternal(java.io.ObjectOutput out)

See Also:

java.io.Externalizable#writeExternal(java.io.ObjectOutput)

writeTo

public java.io.Writer writeTo(java.io.Writer target)

Writes the buffer content to a target java.io.Writer

throws:

IOException

Parameters:

target

writeTo

public void writeTo(java.io.Writer target, boolean flushTarget, boolean emptyAfter)

Writes the buffer content to a target java.io.Writer

throws:

IOException

Parameters:

target - Writer

flushAll - flush all content in buffer (if this is false, only filled chunks will be written)

flushTarget - calls target.flush() before finishing

Groovy Documentation