Package org.serviceconnector.util

Class CircularByteBuffer

java.lang.Object

org.serviceconnector.util.CircularByteBuffer

public class CircularByteBuffer
extends Object

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

Using this class is a simpler alternative to using a PipedInputStream and a PipedOutputStream. PipedInputStreams and PipedOutputStreams 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

Author:

Stephen Ostermiller http://ostermiller.org/contact.pl?regarding=Java+Utilities

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected class	CircularByteBuffer.CircularByteBufferInputStream	Class for reading from a circular byte buffer.
protected class	CircularByteBuffer.CircularByteBufferOutputStream	Class for writing to a circular byte buffer.

Field Summary

Fields

Modifier and Type	Field	Description
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 byte[]	buffer	The circular buffer.
protected InputStream	in	The InputStream that can empty this buffer.
protected boolean	infinite	If this buffer is infinite (should resize itself when full).
static final int	INFINITE_SIZE	A buffer that will grow as things are added.
protected boolean	inputStreamClosed	true if the close() method has been called on the InputStream.
protected int	markPosition	Index of the first saved byte.
protected int	markSize	Number of bytes that have to be saved to support mark() and reset() on the InputStream.
protected OutputStream	out	The OutputStream that can fill this buffer.
protected boolean	outputStreamClosed	true if the close() method has been called on the OutputStream.
protected int	readPosition	Index of the first byte available to be read.
protected int	writePosition	Index of the first byte available to be written.

Constructor Summary

Constructors

Constructor	Description
CircularByteBuffer()	Create a new buffer with a default capacity.
CircularByteBuffer(boolean blockingWrite)	Create a new buffer with a default capacity and given blocking behavior.
CircularByteBuffer(int size)	Create a new buffer with given capacity.
CircularByteBuffer(int size, boolean blockingWrite)	Create a new buffer with the given capacity and blocking behavior.

Method Summary

Modifier and Type	Method	Description
void	clear()	Make this buffer ready for reuse.
int	getAvailable()	Get number of bytes that are available to be read.
InputStream	getInputStream()	Retrieve a InputStream that can be used to empty this buffer.
OutputStream	getOutputStream()	Retrieve a OutputStream that can be used to fill this buffer.
int	getSize()	Get the capacity of this buffer.
int	getSpaceLeft()	Get the number of bytes this buffer has free for writing.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

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 byte[] 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 InputStream has never been marked, the readPosition and the markPosition should always be the same. The bytes 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 bytes that have been saved to support a reset() of the InputStream 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 byte available to be read.

Since:

ostermillerutils 1.00.00

writePosition

protected volatile int writePosition

Index of the first byte available to be written.

Since:

ostermillerutils 1.00.00

markPosition

protected volatile int markPosition

Index of the first saved byte. (To support stream marking.)

Since:

ostermillerutils 1.00.00

markSize

protected volatile int markSize

Number of bytes that have to be saved to support mark() and reset() on the InputStream.

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

in

protected InputStream in

The InputStream that can empty this buffer.

Since:

ostermillerutils 1.00.00

inputStreamClosed

protected boolean inputStreamClosed

true if the close() method has been called on the InputStream.

Since:

ostermillerutils 1.00.00

out

protected OutputStream out

The OutputStream that can fill this buffer.

Since:

ostermillerutils 1.00.00

outputStreamClosed

protected boolean outputStreamClosed

true if the close() method has been called on the OutputStream.

Since:

ostermillerutils 1.00.00

Constructor Details

CircularByteBuffer

public CircularByteBuffer()

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

CircularByteBuffer

public CircularByteBuffer(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 bytes for special purposes and capacity number of bytes 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 bytes or CircularByteBuffer.INFINITE_SIZE.

Since:

ostermillerutils 1.00.00

CircularByteBuffer

public CircularByteBuffer(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

CircularByteBuffer

public CircularByteBuffer(int size,
 boolean blockingWrite)

Create a new buffer with the given capacity and blocking behavior.

Note that the buffer may reserve some bytes for special purposes and capacity number of bytes 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 bytes or CircularByteBuffer.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 Details

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

getOutputStream

public OutputStream getOutputStream()

Retrieve a OutputStream 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

getInputStream

public InputStream getInputStream()

Retrieve a InputStream that can be used to empty this buffer.

This InputStream 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 bytes that are available to be read.

Note that the number of bytes available plus the number of bytes 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 bytes of this buffer

Since:

ostermillerutils 1.00.00

getSpaceLeft

public int getSpaceLeft()

Get the number of bytes this buffer has free for writing.

Note that the number of bytes available plus the number of bytes 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 bytes of this buffer

Since:

ostermillerutils 1.00.00

getSize

public int getSize()

Get the capacity of this buffer.

Note that the number of bytes available plus the number of bytes 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 bytes of this buffer

Since:

ostermillerutils 1.00.00