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

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

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      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

        forEach, iterator, spliterator
    • 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.
      • 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.
      • 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.