Interface IRingBuffer<T>

Type Parameters:
T - the type of instances to store in implementations of this ring buffer.
All Superinterfaces:
Iterable<T>, Serializable
All Known Implementing Classes:
RingBufferArray, RingBufferArrayFast

public interface IRingBuffer<T> extends Serializable, Iterable<T>
Interface for implementations of RingBuffers.

Version:
$Revision: 1.6 $
Author:
Achim Westermann
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final class 
    Special exception related to ring buffer operations.
  • Method Summary

    Modifier and Type
    Method
    Description
    add(T element)
    Adds element to the RingBuffer.
    void
    Clears the buffer without returning anything.
    int
    Returns the absolute amount of space in the buffer.
    Returns the oldest element from the buffer.
    Returns the last element added.
    boolean
    Tests whether no elements are stored in the buffer.
    boolean
    Returns true if no more space in the buffer is available.
    Returns an iterator starting from the first (youngest) to the last (oldest) element.
    Returns an iterator starting from the last (oldest) to the first (youngest) element.
    Removes the oldest element from the buffer.
    T[]
    Clears the buffer.
    void
    setBufferSize(int newSize)
    Sets a new buffer- size.
    int
    Returns the actual amount of elements stored in the buffer.

    Methods inherited from interface java.lang.Iterable

    forEach, iterator, spliterator
  • Method Details

    • 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

      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

      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

      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

      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.