Added Buffer interface from Avalon Excaliber.

Modified the interface from Avalon so that it (a) defines a read-only get()
method and (b) extends java.util.Collection. Also altered the documentation so
that the scope of the interface is broader; it can apply to stacks, heaps and
LRU caches as well.

Submitted by: Paul Jack ( pjack at sfaf dot org )


git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@130738 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/commons/collections/Buffer.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright (C) The Apache Software Foundation. All rights reserved.
+ *
+ * This software is published under the terms of the Apache Software License
+ * version 1.1, a copy of which has been included with this distribution in
+ * the LICENSE.txt file.
+ */
+package org.apache.commons.collections;
+
+
+import java.util.Collection;
+
+
+/**
+ * A Buffer is a collection that allows objects to be removed in some
+ * well-defined order.  The removal order can be based on insertion order
+ * (eg, a FIFO queue or a LIFO stack), on access order (eg, an LRU cache), 
+ * on some arbitrary comparator (eg, a priority queue) or on any other 
+ * well-defined ordering.<P>
+ *
+ * Note that the removal order is not necessarily the same as the iteration
+ * order.  A <Code>Buffer</Code> implementation may have equivalent removal
+ * and iteration orders, but this is not required.<P>
+ *
+ * This interface does not specify any behavior for 
+ * {@link Object#equals(Object)} and {@link Object#hashCode} methods.  It
+ * is therefore possible for a <Code>Buffer</Code> implementation to also
+ * also implement {@link java.util.List}, {@link java.util.Set} or 
+ * {@link Bag}.
+ *
+ * @author  <a href="bloritsch@apache.org">Berin Loritsch</a>
+ * @version CVS $Revision: 1.1 $ $Date: 2002/07/03 01:44:04 $
+ * @since Avalon 4.0
+ */
+public interface Buffer extends Collection
+{
+
+    /**
+     * Removes the next object from the buffer.
+     *
+     * @return  the removed object
+     * @throws BufferUnderflowException if the buffer is already empty
+     */
+    Object remove();
+
+
+
+    /**
+     *  Returns the next object in the buffer without removing it.
+     *
+     *  @return  the next object in the buffer
+     *  @throws BufferUnderflowException if the buffer is empty
+     */
+    Object get();
+}

src/java/org/apache/commons/collections/BufferOverflowException.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright (C) The Apache Software Foundation. All rights reserved.
+ *
+ * This software is published under the terms of the Apache Software License
+ * version 1.1, a copy of which has been included with this distribution in
+ * the LICENSE.txt file.
+ */
+package org.apache.commons.collections;
+
+/**
+ * The BufferOverflowException is used when the buffer's capacity has been
+ * exceeded.
+ *
+ * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
+ * @author <a href="mailto:jefft@apache.org">Jeff Turner</a>
+ */
+public class BufferOverflowException extends RuntimeException
+{
+    private final Throwable m_throwable;
+
+    /** Construct a new BufferOverflowException.
+     * @param message The detail message for this exception.
+     */
+    public BufferOverflowException( String message )
+    {
+        this( message, null );
+    }
+
+    /** Construct a new BufferOverflowException.
+     * @param message The detail message for this exception.
+     * @param throwable the root cause of the exception
+     */
+    public BufferOverflowException( String message, Throwable exception )
+    {
+        super( message );
+        m_throwable = exception;
+    }
+
+    /**
+     * Retrieve root cause of the exception.
+     *
+     * @return the root cause
+     */
+    public final Throwable getCause()
+    {
+        return m_throwable;
+    }
+}

src/java/org/apache/commons/collections/BufferUnderflowException.java

@@ -0,0 +1,53 @@
+/*
+ * Copyright (C) The Apache Software Foundation. All rights reserved.
+ *
+ * This software is published under the terms of the Apache Software License
+ * version 1.1, a copy of which has been included with this distribution in
+ * the LICENSE.txt file.
+ */
+package org.apache.commons.collections;
+
+/**
+ * The BufferUnderflowException is used when the buffer is already empty
+ *
+ * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
+ * @author <a href="mailto:jefft@apache.org">Jeff Turner</a>
+ */
+public class BufferUnderflowException extends RuntimeException
+{
+    private final Throwable m_throwable;
+
+    /** Construct a new BufferUnderflowException.
+     * @param message The detail message for this exception.
+     */
+    public BufferUnderflowException( String message )
+    {
+        this( message, null );
+    }
+
+    /** Construct a new BufferUnderflowException.
+     * @param message The detail message for this exception.
+     * @param throwable the root cause of the exception
+     */
+    public BufferUnderflowException( String message, Throwable exception )
+    {
+        super( message );
+        m_throwable = exception;
+    }
+
+
+    public BufferUnderflowException() {
+        super();
+        m_throwable = null;
+    }
+
+    /**
+     * Retrieve root cause of the exception.
+     *
+     * @return the root cause
+     */
+    public final Throwable getCause()
+    {
+        return m_throwable;
+    }
+}