--- jsr166/src/main/java/util/AbstractQueue.java 2003/06/24 14:34:30 1.4 +++ jsr166/src/main/java/util/AbstractQueue.java 2003/09/12 17:13:11 1.15 @@ -7,24 +7,76 @@ package java.util; /** - * AbstractQueue provides default implementations of add, remove, and - * element based on offer, poll, and peek, respectively but that throw - * exceptions instead of indicating failure via false or null returns. - * The provided implementations all assume that the base implementation - * does not allow null elements. + * This class provides skeletal implementations of some {@link Queue} + * operations. The implementations in this class are appropriate when + * the base implementation does not allow null + * elements. Methods {@link #add add}, {@link #remove remove}, and + * {@link #element element} are based on {@link #offer offer}, {@link + * #poll poll}, and {@link #peek peek}, respectively but throw + * exceptions instead of indicating failure via false or + * null returns. + * + *

A Queue implementation that extends this class must + * minimally define a method {@link Queue#offer} which does not permit + * insertion of null elements, along with methods {@link + * Queue#peek}, {@link Queue#poll}, {@link Collection#size}, {@link + * Collection#remove}, and a {@link Collection#iterator} supporting + * {@link Iterator#remove}. If these requirements cannot be met, + * consider instead subclassing {@link AbstractCollection}. + * * @since 1.5 * @author Doug Lea */ - -public abstract class AbstractQueue extends AbstractCollection implements Queue { +public abstract class AbstractQueue + extends AbstractCollection + implements Queue { + + /** + * Constructor for use by subclasses. + */ + protected AbstractQueue() { + } - public boolean add(E x) { - if (offer(x)) + /** + * Inserts the specified element to this queue, if possible. + * + * @param o the element to add. + * @return true if it was possible to add the element to + * this queue, else false + * @throws NullPointerException if the specified element is null + */ + public boolean offer(E o) { return false; } + // FIXME: Replace above no-op with following abstract version + // when javac allows it. + // public abstract boolean offer(E o); + + /** + * Adds the specified element to this queue. This implementation + * returns true if offer succeeds, else + * throws an IllegalStateException. + * th + * @param o the element + * @return true (as per the general contract of + * Collection.add). + * + * @throws NullPointerException if the specified element is null + * @throws IllegalStateException if element cannot be added + */ + public boolean add(E o) { + if (offer(o)) return true; else throw new IllegalStateException("Queue full"); } + /** + * Retrieves and removes the head of this queue. + * This implementation returns the result of poll + * unless the queue is empty. + * + * @return the head of this queue. + * @throws NoSuchElementException if this queue is empty. + */ public E remove() { E x = poll(); if (x != null) @@ -33,6 +85,15 @@ public abstract class AbstractQueue e throw new NoSuchElementException(); } + + /** + * Retrieves, but does not remove, the head of this queue. + * This implementation returns the result of peek + * unless the queue is empty. + * + * @return the head of this queue. + * @throws NoSuchElementException if this queue is empty. + */ public E element() { E x = peek(); if (x != null) @@ -41,9 +102,94 @@ public abstract class AbstractQueue e throw new NoSuchElementException(); } + /** + * Removes all of the elements from this collection. + * The collection will be empty after this call returns. + *

This implementation repeatedly invokes {@link #poll poll} until it + * returns null. + */ public void clear() { while (poll() != null) ; } + // Declarations that mostly just remove optionality clauses. + + /** + * Removes a single instance of the specified element from this + * queue, if one is present. More formally, removes an element + * e such that (o==null ? e==null : + * o.equals(e)), if the queue contains such an element. + * Returns true if the queue contained the specified + * element (or equivalently, if the queue changed as a result of + * the call). + * + * @param o the element to remove + * @return true if the element was removed + */ + public abstract boolean remove(Object o); + + /** + * Removes from this queue all of its elements that are contained in + * the specified collection.

+ * + * This implementation iterates over this queue, checking each + * element returned by the iterator in turn to see if it's contained + * in the specified collection. If it's so contained, it's removed from + * this queue with the iterator's remove method.

+ * + * @param c elements to be removed from this collection. + * @return true if this queue changed as a result of the + * call. + * @throws NullPointerException if the specified collection is null. + */ + public boolean removeAll(Collection c) { + return super.removeAll(c); + } + + /** + * Retains only the elements in this queue that are contained in the + * specified collection. In other words, removes + * from this queue all of its elements that are not contained in the + * specified collection.

+ * + * This implementation iterates over this queue, checking each + * element returned by the iterator in turn to see if it's contained + * in the specified collection. If it's not so contained, it's removed + * from this queue with the iterator's remove method.

+ * + * @param c elements to be retained in this collection. + * @return true if this queue changed as a result of the + * call. + * @throws NullPointerException if the specified collection is null. + * + */ + public boolean retainAll(Collection c) { + return super.retainAll(c); + } + + /** + * Adds all of the elements in the specified collection to this + * queue. The behavior of this operation is undefined if the + * specified collection is modified while the operation is in + * progress. (This implies that the behavior of this call is + * undefined if the specified collection is this queue, and this + * queue is nonempty.) + * + *

This implementation iterates over the specified collection, + * and uses the add method to insert each object returned by + * the iterator to this queue, in turn. + * + * @param c collection whose elements are to be added to this queue + * @return true if this queue changed as a result of the + * call. + * @throws NullPointerException if c or any element in c + * is null + * @throws IllegalStateException if any element cannot be added. + * + */ + public boolean addAll(Collection c) { + return super.addAll(c); + } + }