com.Ostermiller.util
Class CircularCharBuffer

java.lang.Object
  extended by com.Ostermiller.util.CircularCharBuffer

public class CircularCharBuffer
extends java.lang.Object

Implements the Circular Buffer producer/consumer model for characters. More information about this class is available from ostermiller.org.

Using this class is a simpler alternative to using a PipedReader and a PipedWriter. PipedReaders and PipedWriters don't support the mark operation, don't allow you to control buffer sizes that they use, and have a more complicated API that requires instantiating two classes and connecting them.

This class is thread safe.

Since:
ostermillerutils 1.00.00
See Also:
CircularByteBuffer, CircularObjectBuffer

Nested Class Summary
protected  class CircularCharBuffer.CircularCharBufferReader
          Class for reading from a circular character buffer.
protected  class CircularCharBuffer.CircularCharBufferWriter
          Class for writing to a circular character buffer.
 
Field Summary
protected  boolean blockingWrite
          True if a write to a full buffer should block until the buffer has room, false if the write method should throw an IOException
protected  char[] buffer
          The circular buffer.
protected  boolean infinite
          If this buffer is infinite (should resize itself when full)
static int INFINITE_SIZE
          A buffer that will grow as things are added.
protected  int markPosition
          Index of the first saved character.
protected  int markSize
          Number of characters that have to be saved to support mark() and reset() on the Reader.
protected  java.io.Reader reader
          The Reader that can empty this buffer.
protected  boolean readerClosed
          true if the close() method has been called on the Reader
protected  int readPosition
          Index of the first character available to be read.
protected  int writePosition
          Index of the first character available to be written.
protected  java.io.Writer writer
          The Writer that can fill this buffer.
protected  boolean writerClosed
          true if the close() method has been called on the writer
 
Constructor Summary
CircularCharBuffer()
          Create a new buffer with a default capacity.
CircularCharBuffer(boolean blockingWrite)
          Create a new buffer with a default capacity and given blocking behavior.
CircularCharBuffer(int size)
          Create a new buffer with given capacity.
CircularCharBuffer(int size, boolean blockingWrite)
          Create a new buffer with the given capacity and blocking behavior.
 
Method Summary
 void clear()
          Make this buffer ready for reuse.
 int getAvailable()
          Get number of characters that are available to be read.
 java.io.Reader getReader()
          Retrieve a Reader that can be used to empty this buffer.
 int getSize()
          Get the capacity of this buffer.
 int getSpaceLeft()
          Get the number of characters this buffer has free for writing.
 java.io.Writer getWriter()
          Retrieve a Writer that can be used to fill this buffer.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

INFINITE_SIZE

public static final int INFINITE_SIZE
A buffer that will grow as things are added.

Since:
ostermillerutils 1.00.00
See Also:
Constant Field Values

buffer

protected char[] buffer
The circular buffer.

The actual capacity of the buffer is one less than the actual length of the buffer so that an empty and a full buffer can be distinguished. An empty buffer will have the markPostion and the writePosition equal to each other. A full buffer will have the writePosition one less than the markPostion.

There are three important indexes into the buffer: The readPosition, the writePosition, and the markPosition. If the Reader has never been marked, the readPosition and the markPosition should always be the same. The characters available to be read go from the readPosition to the writePosition, wrapping around the end of the buffer. The space available for writing goes from the write position to one less than the markPosition, wrapping around the end of the buffer. The characters that have been saved to support a reset() of the Reader go from markPosition to readPosition, wrapping around the end of the buffer.

Since:
ostermillerutils 1.00.00

readPosition

protected volatile int readPosition
Index of the first character available to be read.

Since:
ostermillerutils 1.00.00

writePosition

protected volatile int writePosition
Index of the first character available to be written.

Since:
ostermillerutils 1.00.00

markPosition

protected volatile int markPosition
Index of the first saved character. (To support stream marking.)

Since:
ostermillerutils 1.00.00

markSize

protected volatile int markSize
Number of characters that have to be saved to support mark() and reset() on the Reader.

Since:
ostermillerutils 1.00.00

infinite

protected volatile boolean infinite
If this buffer is infinite (should resize itself when full)

Since:
ostermillerutils 1.00.00

blockingWrite

protected boolean blockingWrite
True if a write to a full buffer should block until the buffer has room, false if the write method should throw an IOException

Since:
ostermillerutils 1.00.00

reader

protected java.io.Reader reader
The Reader that can empty this buffer.

Since:
ostermillerutils 1.00.00

readerClosed

protected boolean readerClosed
true if the close() method has been called on the Reader

Since:
ostermillerutils 1.00.00

writer

protected java.io.Writer writer
The Writer that can fill this buffer.

Since:
ostermillerutils 1.00.00

writerClosed

protected boolean writerClosed
true if the close() method has been called on the writer

Since:
ostermillerutils 1.00.00
Constructor Detail

CircularCharBuffer

public CircularCharBuffer()
Create a new buffer with a default capacity. Writing to a full buffer will block until space is available rather than throw an exception.

Since:
ostermillerutils 1.00.00

CircularCharBuffer

public CircularCharBuffer(int size)
Create a new buffer with given capacity. Writing to a full buffer will block until space is available rather than throw an exception.

Note that the buffer may reserve some characters for special purposes and capacity number of characters may not be able to be written to the buffer.

Note that if the buffer is of INFINITE_SIZE it will neither block or throw exceptions, but rather grow without bound.

Parameters:
size - desired capacity of the buffer in characters or CircularCharBuffer.INFINITE_SIZE
Since:
ostermillerutils 1.00.00

CircularCharBuffer

public CircularCharBuffer(boolean blockingWrite)
Create a new buffer with a default capacity and given blocking behavior.

Parameters:
blockingWrite - true writing to a full buffer should block until space is available, false if an exception should be thrown instead.
Since:
ostermillerutils 1.00.00

CircularCharBuffer

public CircularCharBuffer(int size,
                          boolean blockingWrite)
Create a new buffer with the given capacity and blocking behavior.

Note that the buffer may reserve some characters for special purposes and capacity number of characters may not be able to be written to the buffer.

Note that if the buffer is of CircularCharBuffer.INFINITE_SIZE it will neither block or throw exceptions, but rather grow without bound.

Parameters:
size - desired capacity of the buffer in characters or CircularCharBuffer.INFINITE_SIZE
blockingWrite - true writing to a full buffer should block until space is available, false if an exception should be thrown instead.
Since:
ostermillerutils 1.00.00
Method Detail

clear

public void clear()
Make this buffer ready for reuse. The contents of the buffer will be cleared and the streams associated with this buffer will be reopened if they had been closed.

Since:
ostermillerutils 1.00.00

getWriter

public java.io.Writer getWriter()
Retrieve a Writer that can be used to fill this buffer.

Write methods may throw a BufferOverflowException if the buffer is not large enough. A large enough buffer size must be chosen so that this does not happen or the caller must be prepared to catch the exception and try again once part of the buffer has been consumed.

Returns:
the producer for this buffer.
Since:
ostermillerutils 1.00.00

getReader

public java.io.Reader getReader()
Retrieve a Reader that can be used to empty this buffer.

This Reader supports marks at the expense of the buffer size.

Returns:
the consumer for this buffer.
Since:
ostermillerutils 1.00.00

getAvailable

public int getAvailable()
Get number of characters that are available to be read.

Note that the number of characters available plus the number of characters free may not add up to the capacity of this buffer, as the buffer may reserve some space for other purposes.

Returns:
the size in characters of this buffer
Since:
ostermillerutils 1.00.00

getSpaceLeft

public int getSpaceLeft()
Get the number of characters this buffer has free for writing.

Note that the number of characters available plus the number of characters free may not add up to the capacity of this buffer, as the buffer may reserve some space for other purposes.

Returns:
the available space in characters of this buffer
Since:
ostermillerutils 1.00.00

getSize

public int getSize()
Get the capacity of this buffer.

Note that the number of characters available plus the number of characters free may not add up to the capacity of this buffer, as the buffer may reserve some space for other purposes.

Returns:
the size in characters of this buffer
Since:
ostermillerutils 1.00.00