info.monitorenter.util.collections
Interface IRingBuffer<T>

Type Parameters:

T - the type of instances to store in implementations of this ring buffer.

All Superinterfaces:

java.lang.Iterable<T>, java.io.Serializable

All Known Implementing Classes:

RingBufferArray, RingBufferArrayFast

public interface IRingBuffer<T>
extends java.io.Serializable, java.lang.Iterable<T>

Interface for implementations of RingBuffers.

Version:

$Revision: 1.6 $

Author:

Achim Westermann

Nested Class Summary

static class

IRingBuffer.RingBufferException Special exception related to ring buffer operations.

Method Summary

T	add(T element) Adds element to the RingBuffer.
void	clear() Clears the buffer without returning anything.
int	getBufferSize() Returns the absolute amount of space in the buffer.
T	getOldest() Returns the oldest element from the buffer.
T	getYoungest() Returns the last element added.
boolean	isEmpty() Tests whether no elements are stored in the buffer.
boolean	isFull() Returns true if no more space in the buffer is available.
java.util.Iterator<T>	iteratorF2L() Returns an iterator starting from the first (youngest) to the last (oldest) element.
java.util.Iterator<T>	iteratorL2F() Returns an iterator starting from the last (oldest) to the first (youngest) element.
T	remove() Removes the oldest element from the buffer.
T[]	removeAll() Clears the buffer.
void	setBufferSize(int newSize) Sets a new buffer- size.
int	size() Returns the actual amount of elements stored in the buffer.

Methods inherited from interface java.lang.Iterable

iterator

Method Detail

add

T add(T element)
      throws IRingBuffer.RingBufferException

Adds element to the RingBuffer.

If the buffer is full, an Exception will be thrown.

Note that RingBufferException does not need to be caught because it is an inheritant of java.lang.RuntimeException. Especially for the Object add(Object element)- method there may be an implementation that never throws BUFFER_FULL but returns the oldest element in case the buffer is full.

Parameters:

element - the element to add.

Returns:

the instance that had to be removed in order to add the new one or null, if the capacity was not reached yet.

Throws:

IRingBuffer.RingBufferException - if the buffer cannot accept any more elements.

clear

void clear()

Clears the buffer without returning anything.

If the content is of no interest prefer using this method instead of removeAll() as it may be implemented in a much faster way ( O(constant) instead of O(n)).

getBufferSize

int getBufferSize()

Returns the absolute amount of space in the buffer.

Returns:

the absolute amount of space in the buffer.

getOldest

T getOldest()
            throws IRingBuffer.RingBufferException

Returns the oldest element from the buffer. This method does not remove the element.

Returns:

the oldest element from the buffer.

Throws:

IRingBuffer.RingBufferException - if the buffer is empty.

getYoungest

T getYoungest()
              throws IRingBuffer.RingBufferException

Returns the last element added. This method does not remove the element.

Returns:

the last element added.

Throws:

IRingBuffer.RingBufferException - if the buffer is empty.

isEmpty

boolean isEmpty()

Tests whether no elements are stored in the buffer.

Returns:

true if no element is stored in the buffer.

isFull

boolean isFull()

Returns true if no more space in the buffer is available. This method should be used to test before calling add(Object).

Returns:

true if no more space in the buffer is available.

iteratorF2L

java.util.Iterator<T> iteratorF2L()

Returns an iterator starting from the first (youngest) to the last (oldest) element.

Returns:

an iterator starting from the first (youngest) to the last (oldest) element.

iteratorL2F

java.util.Iterator<T> iteratorL2F()

Returns an iterator starting from the last (oldest) to the first (youngest) element.

Returns:

an iterator starting from the last (oldest) to the first (youngest) element.

remove

T remove()
         throws IRingBuffer.RingBufferException

Removes the oldest element from the buffer.

Returns:

the removed oldest element from the buffer.

Throws:

IRingBuffer.RingBufferException - if the buffer is empty.

removeAll

T[] removeAll()

Clears the buffer. It will return all of it's stored elements.

Returns:

all removed elements.

setBufferSize

void setBufferSize(int newSize)

Sets a new buffer- size.

Implementations may vary on handling the problem that the new size is smaller than the actual amount of elements in the buffer:
The oldest elements may be thrown away.

A new size is assigned but the elements "overhanging" are returned by the Object remove()- method first. This may take time until the buffer has its actual size again.

Parameters:

newSize - the new buffer size to set.

size

int size()

Returns the actual amount of elements stored in the buffer.

Returns:

the actual amount of elements stored in the buffer.