/*
 * IRingBuffer, an interface for implementations of a RingBuffer.
 * Copyright (c) 2004 - 2011 Achim Westermann, Achim.Westermann@gmx.de.
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; either
 *  version 2.1 of the License, or (at your option) any later version.
 * 
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Lesser General Public License for more details.
 * 
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 *
 *  If you modify or optimize the code in a useful way please let me know.
 *  Achim.Westermann@gmx.de
 */
package info.monitorenter.util.collections;


/**
 * Interface for implementations of RingBuffers.
 * 

 * 
 * @param 
 *            the type of instances to store in implementations of this ring
 *            buffer.
 * 
 * @author Achim Westermann 
 * 
 * @version $Revision: 1.6 $
 */
public interface IRingBuffer extends java.io.Serializable, Iterable {

  /**
   * Special exception related to ring buffer operations.
   * 

   * 
   * @author Achim Westermann 
   * 
   * @version $Revision: 1.6 $
   */
  public final class RingBufferException
      extends RuntimeException {
    /**
     * Comment for serialVersionUID.
     */
    private static final long serialVersionUID = 3762255244691714610L;

    /**
     * Creates an instance with the given message.
     * 

     * 
     * @param msg
     *            the message of the exception.
     */
    protected RingBufferException(final String msg) {
      super(msg);
    }
  }

  /**
   * 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.
   * 

   * 
   * @param element
   *            the element to add.
   * 
   * @return 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.
   * 
   * 
   */
  public T add(final T element) throws IRingBuffer.RingBufferException;

  /**
   * Clears the buffer without returning anything.
   * 

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

   * 
   */
  public void clear();

  /**
   * Returns the absolute amount of space in the buffer.
   * 

   * 
   * @return the absolute amount of space in the buffer.
   */
  public int getBufferSize();

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

   * 
   * @return the oldest element from the buffer.
   * 
   * @throws IRingBuffer.RingBufferException
   *             if the buffer is empty.
   */
  public T getOldest() throws IRingBuffer.RingBufferException;

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

   * 
   * @return the last element added.
   * 
   * @throws IRingBuffer.RingBufferException
   *             if the buffer is empty.
   */
  public T getYoungest() throws IRingBuffer.RingBufferException;

  /**
   * Tests whether no elements are stored in the buffer.
   * 

   * 
   * @return true if no element is stored in the buffer.
   */
  public boolean isEmpty();

  /**
   * Returns true if no more space in the buffer is available. This method
   * should be used to test before calling {@link #add(Object)}.
   * 

   * 
   * 
   * @return true if no more space in the buffer is available.
   */
  public boolean isFull();

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

   * 
   * @return an iterator starting from the first (youngest) to the last (oldest)
   *         element.
   */
  public java.util.Iterator iteratorF2L();

  /**
   * Returns an iterator starting from the last (oldest) to the first (youngest)
   * element.
   * 
   * @return an iterator starting from the last (oldest) to the first (youngest)
   *         element.
   */
  public java.util.Iterator iteratorL2F();

  /**
   * Removes the oldest element from the buffer.
   * 

   * 
   * @return the removed oldest element from the buffer.
   * 
   * @throws IRingBuffer.RingBufferException
   *             if the buffer is empty.
   */
  public T remove() throws IRingBuffer.RingBufferException;

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

   * 
   * @return all removed elements.
   */
  public T[] removeAll();

  /**
   * 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.
   * 

   * 
   * @param newSize
   *            the new buffer size to set.
   */
  public void setBufferSize(final int newSize);

  /**
   * Returns the actual amount of elements stored in the buffer.
   * 

   * 
   * @return the actual amount of elements stored in the buffer.
   */
  public int size();

}