com.Ostermiller.util Java Utilities


com.Ostermiller.util
Class CircularObjectBuffer<ElementType>

java.lang.Object
  extended by com.Ostermiller.util.CircularObjectBuffer<ElementType>
Type Parameters:
ElementType - Type of object allowed in this circular buffer

public class CircularObjectBuffer<ElementType>
extends Object

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

This class is thread safe.

Since:
ostermillerutils 1.00.00
Author:
Stephen Ostermiller http://ostermiller.org/contact.pl?regarding=Java+Utilities
See Also:
CircularCharBuffer, CircularByteBuffer

Field Summary
static int INFINITE_SIZE
          A buffer that will grow as things are added.
 
Constructor Summary
CircularObjectBuffer()
          Create a new buffer with a default capacity.
CircularObjectBuffer(boolean blockingWrite)
          Create a new buffer with a default capacity and given blocking behavior.
CircularObjectBuffer(int size)
          Create a new buffer with given capacity.
CircularObjectBuffer(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.
 void done()
          This method should be used by the producer to signal to the consumer that the producer is done producing objects and that the consumer should stop asking for objects once it has used up buffered objects.
 int getAvailable()
          Get number of Objects that are available to be read.
 int getSize()
          Get the capacity of this buffer.
 int getSpaceLeft()
          Get the number of Objects this buffer has free for writing.
 ElementType read()
          Get a single Object from this buffer.
 int read(ElementType[] buf)
          Get Objects into an array from this buffer.
 int read(ElementType[] buf, int off, int len)
          Get Objects into a portion of an array from this buffer.
 long skip(long n)
          Skip Objects.
 void write(ElementType o)
          Add a single Object to this buffer.
 void write(ElementType[] buf)
          Fill this buffer with array of Objects.
 void write(ElementType[] buf, int off, int len)
          Fill this buffer with a portion of an array of Objects.
 
Methods inherited from class java.lang.Object
equals, 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
Constructor Detail

CircularObjectBuffer

public CircularObjectBuffer()
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

CircularObjectBuffer

public CircularObjectBuffer(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 Objects for special purposes and capacity number of Objects 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 Objects or CircularObjectBuffer.INFINITE_SIZE.
Since:
ostermillerutils 1.00.00

CircularObjectBuffer

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

CircularObjectBuffer

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

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

getAvailable

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

Note that the number of Objects available plus the number of Objects 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 Objects of this buffer
Since:
ostermillerutils 1.00.00

getSpaceLeft

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

Note that the number of Objects available plus the number of Objects 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 Objects of this buffer
Since:
ostermillerutils 1.00.00

getSize

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

Note that the number of Objects available plus the number of Objects 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 Objects of this buffer
Since:
ostermillerutils 1.00.00

read

public ElementType read()
                 throws InterruptedException
Get a single Object from this buffer. This method should be called by the consumer. This method will block until a Object is available or no more objects are available.

Returns:
The Object read, or null if there are no more objects
Throws:
InterruptedException - if the thread is interrupted while waiting.
Since:
ostermillerutils 1.00.00

read

public int read(ElementType[] buf)
         throws InterruptedException
Get Objects into an array from this buffer. This method should be called by the consumer. This method will block until some input is available, or there is no more input.

Parameters:
buf - Destination buffer.
Returns:
The number of Objects read, or -1 there will be no more objects available.
Throws:
InterruptedException - if the thread is interrupted while waiting.
Since:
ostermillerutils 1.00.00

read

public int read(ElementType[] buf,
                int off,
                int len)
         throws InterruptedException
Get Objects into a portion of an array from this buffer. This method should be called by the consumer. This method will block until some input is available, an I/O error occurs, or the end of the stream is reached.

Parameters:
buf - Destination buffer.
off - Offset at which to start storing Objects.
len - Maximum number of Objects to read.
Returns:
The number of Objects read, or -1 there will be no more objects available.
Throws:
InterruptedException - if the thread is interrupted while waiting.
Since:
ostermillerutils 1.00.00

skip

public long skip(long n)
          throws InterruptedException,
                 IllegalArgumentException
Skip Objects. This method should be used by the consumer when it does not care to examine some number of Objects. This method will block until some Objects are available, or there will be no more Objects available.

Parameters:
n - The number of Objects to skip
Returns:
The number of Objects actually skipped
Throws:
IllegalArgumentException - if n is negative.
InterruptedException - if the thread is interrupted while waiting.
Since:
ostermillerutils 1.00.00

done

public void done()
This method should be used by the producer to signal to the consumer that the producer is done producing objects and that the consumer should stop asking for objects once it has used up buffered objects.

Once the producer has signaled that it is done, further write() invocations will cause an IllegalStateException to be thrown. Calling done() multiple times, however, has no effect.

Since:
ostermillerutils 1.00.00

write

public void write(ElementType[] buf)
           throws BufferOverflowException,
                  IllegalStateException,
                  InterruptedException
Fill this buffer with array of Objects. This method should be called by the producer. If the buffer allows blocking writes, this method will block until all the data has been written rather than throw a BufferOverflowException.

Parameters:
buf - Array of Objects to be written
Throws:
BufferOverflowException - if buffer does not allow blocking writes and the buffer is full. If the exception is thrown, no data will have been written since the buffer was set to be non-blocking.
IllegalStateException - if done() has been called.
InterruptedException - if the write is interrupted.
Since:
ostermillerutils 1.00.00

write

public void write(ElementType[] buf,
                  int off,
                  int len)
           throws BufferOverflowException,
                  IllegalStateException,
                  InterruptedException
Fill this buffer with a portion of an array of Objects. This method should be called by the producer. If the buffer allows blocking writes, this method will block until all the data has been written rather than throw an IOException.

Parameters:
buf - Array of Objects
off - Offset from which to start writing Objects
len - - Number of Objects to write
Throws:
BufferOverflowException - if buffer does not allow blocking writes and the buffer is full. If the exception is thrown, no data will have been written since the buffer was set to be non-blocking.
IllegalStateException - if done() has been called.
InterruptedException - if the write is interrupted.
Since:
ostermillerutils 1.00.00

write

public void write(ElementType o)
           throws BufferOverflowException,
                  IllegalStateException,
                  InterruptedException
Add a single Object to this buffer. This method should be called by the producer. If the buffer allows blocking writes, this method will block until all the data has been written rather than throw an IOException.

Parameters:
o - Object to be written.
Throws:
BufferOverflowException - if buffer does not allow blocking writes and the buffer is full. If the exception is thrown, no data will have been written since the buffer was set to be non-blocking.
IllegalStateException - if done() has been called.
InterruptedException - if the write is interrupted.
Since:
ostermillerutils 1.00.00

com.Ostermiller.util Java Utilities


Copyright © 2001-2012 by Stephen Ostermiller