info.monitorenter.util.collections
Interface IRingBuffer

All Superinterfaces:

Serializable

All Known Implementing Classes:

RingBufferArray, RingBufferArrayFast

public interface IRingBuffer
extends Serializable

Interface for implementations of RingBuffers.

Version:

$Revision: 1.2 $

Author:

Achim Westermann

Nested Class Summary

static class

IRingBuffer.RingBufferException Special exception related to ringbuffer operations.

Method Summary

Object	add(Object 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.
Object	getOldest() Returns the oldest element from the buffer.
Object	getYoungest() Returns the last element added.
boolean	isEmpty() Tests wether no elements are stored in the buffer.
boolean	isFull() Returns true if no more space in the buffer is available.
Iterator	iteratorF2L() Returns an iterator starting from the first (youngest) to the last (oldest) element.
Iterator	iteratorL2F() Returns an iterator starting from the last (oldest) to the first (youngest) element.
Object	remove() Removes the oldest element from the buffer.
Object[]	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.

Method Detail

add

Object add(Object 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

Object 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

Object 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 wether 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

Iterator 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

Iterator 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

Object 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

Object[] 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.