From 8c2174786799881f53c8fd68153a37940c1f4c91 Mon Sep 17 00:00:00 2001 From: Michael Smith Date: Wed, 3 Jul 2002 01:44:04 +0000 Subject: [PATCH] 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 --- .../apache/commons/collections/Buffer.java | 55 +++++++++++++++++++ .../collections/BufferOverflowException.java | 48 ++++++++++++++++ .../collections/BufferUnderflowException.java | 53 ++++++++++++++++++ 3 files changed, 156 insertions(+) create mode 100644 src/java/org/apache/commons/collections/Buffer.java create mode 100644 src/java/org/apache/commons/collections/BufferOverflowException.java create mode 100644 src/java/org/apache/commons/collections/BufferUnderflowException.java diff --git a/src/java/org/apache/commons/collections/Buffer.java b/src/java/org/apache/commons/collections/Buffer.java new file mode 100644 index 000000000..74cd22dd4 --- /dev/null +++ b/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.

+ * + * Note that the removal order is not necessarily the same as the iteration + * order. A Buffer implementation may have equivalent removal + * and iteration orders, but this is not required.

+ * + * This interface does not specify any behavior for + * {@link Object#equals(Object)} and {@link Object#hashCode} methods. It + * is therefore possible for a Buffer implementation to also + * also implement {@link java.util.List}, {@link java.util.Set} or + * {@link Bag}. + * + * @author Berin Loritsch + * @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(); +} diff --git a/src/java/org/apache/commons/collections/BufferOverflowException.java b/src/java/org/apache/commons/collections/BufferOverflowException.java new file mode 100644 index 000000000..fc9f3c96d --- /dev/null +++ b/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 Berin Loritsch + * @author Jeff Turner + */ +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; + } +} diff --git a/src/java/org/apache/commons/collections/BufferUnderflowException.java b/src/java/org/apache/commons/collections/BufferUnderflowException.java new file mode 100644 index 000000000..359a74bd9 --- /dev/null +++ b/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 Berin Loritsch + * @author Jeff Turner + */ +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; + } +}